Referencia de CLI

El binario audio es el punto de entrada principal para todas las tareas de procesamiento de voz. Compila con make build y luego ejecuta desde .build/release/audio.

transcribe

Transcribe archivos de audio a texto.

audio transcribe <file> [options]

Opción	Por defecto	Descripción
`<file>`		Archivo de audio a transcribir (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	Motor ASR: `qwen3`, `qwen3-coreml`, `parakeet` u `omnilingual`
`--model, -m`	`0.6B`	Variante del modelo: `0.6B`, `1.7B`, o un ID completo de modelo de HuggingFace (solo qwen3)
`--language`		Pista de idioma (opcional, ignorada por omnilingual)
`--window`	`10`	`[omnilingual]` Tamaño de ventana CoreML en segundos: `5` o `10`
`--backend`	`coreml`	`[omnilingual]` Backend: `coreml` (Neural Engine) o `mlx` (GPU Metal)
`--variant`	`300M`	`[omnilingual mlx]` Tamaño: `300M`, `1B`, `3B` o `7B`
`--bits`	`4`	`[omnilingual mlx]` Bits de cuantización: `4` u `8`
`--stream`		Activa la transcripción en streaming con VAD
`--max-segment`	`10`	Duración máxima del segmento en segundos (streaming)
`--partial`		Emite resultados parciales durante el habla (streaming)

Ejemplos:

# Basic transcription
audio transcribe recording.wav

# Use larger model
audio transcribe recording.wav --model 1.7B

# CoreML encoder (Neural Engine + MLX decoder)
audio transcribe recording.wav --engine qwen3-coreml

# Use Parakeet (CoreML) engine
audio transcribe recording.wav --engine parakeet

# Omnilingual (CoreML, 1,672 languages)
audio transcribe recording.wav --engine omnilingual                              # 10 s window
audio transcribe recording.wav --engine omnilingual --window 5                     # 5 s window

# Omnilingual (MLX, any length up to 40 s)
audio transcribe recording.wav --engine omnilingual --backend mlx                              # 300M @ 4-bit
audio transcribe recording.wav --engine omnilingual --backend mlx --variant 1B                  # 1B @ 4-bit
audio transcribe recording.wav --engine omnilingual --backend mlx --variant 3B --bits 8         # 3B @ 8-bit
audio transcribe recording.wav --engine omnilingual --backend mlx --variant 7B                  # 7B @ 4-bit

# Streaming with VAD
audio transcribe recording.wav --stream --partial

align

Alineación forzada a nivel de palabra — obtén marcas temporales precisas para cada palabra.

audio align <file> [options]

Opción	Por defecto	Descripción
`<file>`		Archivo de audio
`--text, -t`		Texto a alinear (si se omite, primero transcribe)
`--model, -m`	`0.6B`	Modelo ASR para transcripción: `0.6B`, `1.7B`, o ID completo
`--aligner-model`		ID del modelo del alineador forzado
`--language`		Pista de idioma

Ejemplos:

# Auto-transcribe then align
audio align recording.wav

# Align with known text
audio align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

Síntesis de texto a voz.

audio speak "<text>" [options]

Opción	Por defecto	Descripción
`<text>`		Texto a sintetizar (opcional si se usa `--batch-file`)
`--engine`	`qwen3`	Motor TTS: `qwen3` o `cosyvoice`
`--output, -o`	`output.wav`	Ruta del archivo WAV de salida
`--language`	`english`	Idioma. Omítelo para usar el dialecto nativo del hablante cuando se define `--speaker`.
`--stream`		Activa la síntesis en streaming
`--voice-sample`		Audio de referencia para clonación de voz (funciona con los motores `qwen3` y `cosyvoice`)
`--verbose`		Muestra información de tiempos detallada

Opciones de Qwen3-TTS

Opción	Por defecto	Descripción
`--model`	`base`	Variante del modelo: `base`, `customVoice` o ID completo de HF
`--speaker`		Voz del hablante (requiere `--model customVoice`)
`--instruct`		Instrucción de estilo (modelo CustomVoice)
`--list-speakers`		Lista los hablantes disponibles y sale
`--temperature`	`0.3`	Temperatura de muestreo
`--top-k`	`50`	Muestreo top-k
`--max-tokens`	`500`	Tokens máximos (500 = ~40s de audio)
`--batch-file`		Archivo con un texto por línea para síntesis por lotes
`--batch-size`	`4`	Tamaño máximo de lote para generación paralela
`--first-chunk-frames`	`3`	Frames de códec en el primer fragmento en streaming
`--chunk-frames`	`25`	Frames de códec por fragmento en streaming

Opciones de CosyVoice3

Opción	Por defecto	Descripción
`--speakers`		Mapeo de hablantes para diálogo multi-hablante: `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		Instrucción de estilo (anula la predeterminada). Controla el estilo de voz para CosyVoice3.
`--turn-gap`	`0.2`	Silencio entre turnos de diálogo en segundos
`--crossfade`	`0.0`	Solapamiento de crossfade entre turnos en segundos
`--model-id`		ID de modelo de HuggingFace

Ejemplos:

# Basic TTS
audio speak "Hello, world!" --output hello.wav

# Voice cloning (Qwen3-TTS)
audio speak "Hello in your voice" --voice-sample reference.wav -o cloned.wav

# Voice cloning (CosyVoice)
audio speak "Hello in your voice" --engine cosyvoice --voice-sample reference.wav -o cloned.wav

# CosyVoice multilingual
audio speak "Hallo Welt" --engine cosyvoice --language german -o hallo.wav

# Multi-speaker dialogue
audio speak "[S1] Hello there! [S2] Hey, how are you?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o dialogue.wav

# Inline emotion/style tags
audio speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Combined: dialogue + emotions + voice cloning
audio speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# Custom style instruction
audio speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# Streaming synthesis
audio speak "Long text here..." --stream

# Batch synthesis from file
audio speak --batch-file texts.txt --batch-size 4

kokoro

Texto a voz ligero usando Kokoro-82M en el Neural Engine (CoreML). No autoregresivo — una sola pasada hacia adelante, latencia de ~45 ms.

audio kokoro "<text>" [options]

Opción	Por defecto	Descripción
`<text>`		Texto a sintetizar
`--voice`	`af_heart`	Preset de voz (50 disponibles en 10 idiomas)
`--language`	`en`	Código de idioma: en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	Ruta del archivo WAV de salida
`--list-voices`		Lista todas las voces disponibles y sale
`--model, -m`		ID de modelo de HuggingFace

Ejemplos:

# Basic Kokoro TTS
audio kokoro "Hello, world!" --voice af_heart -o hello.wav

# French voice
audio kokoro "Bonjour le monde" --voice ff_siwis --language fr -o bonjour.wav

# List all 50 voices
audio kokoro --list-voices

respond

Diálogo de voz a voz full-duplex usando PersonaPlex 7B.

audio respond [options]

Opción	Por defecto	Descripción
`--input, -i`		Archivo WAV de audio de entrada (24 kHz mono) (obligatorio)
`--output, -o`	`response.wav`	Archivo WAV de respuesta de salida
`--voice`	`NATM0`	Preset de voz (p. ej. NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	Preset: `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		Texto personalizado del system prompt (anula el preset)
`--max-steps`	`200`	Pasos máximos de generación a 12.5 Hz (~16 s)
`--stream`		Emite fragmentos de audio durante la generación
`--compile`		Activa el transformador compilado (calentamiento + fusión de kernels)
`--list-voices`		Lista los presets de voz disponibles
`--list-prompts`		Lista los presets de system prompt disponibles
`--transcript`		Imprime el texto del monólogo interior del modelo
`--json`		Salida en JSON (transcripción, latencia, ruta de audio)
`--verbose`		Muestra información de tiempos detallada

Ajustes de muestreo

Opción	Por defecto	Descripción
`--audio-temp`	`0.8`	Temperatura de muestreo de audio
`--text-temp`	`0.7`	Temperatura de muestreo de texto
`--audio-top-k`	`250`	Candidatos top-k de audio
`--repetition-penalty`	`1.2`	Penalización de repetición de audio (1.0 = desactivada)
`--text-repetition-penalty`	`1.2`	Penalización de repetición de texto (1.0 = desactivada)
`--repetition-window`	`30`	Ventana de penalización de repetición en frames
`--silence-early-stop`	`15`	Frames de silencio antes de la parada temprana (0 = desactivado)
`--entropy-threshold`	`0`	Umbral de entropía de texto para parada temprana (0 = desactivado)
`--entropy-window`	`10`	Pasos consecutivos de baja entropía antes de la parada temprana

Ejemplos:

# Basic speech-to-speech
audio respond --input question.wav

# Use a female voice with compiled transformer
audio respond -i question.wav --voice NATF1 --compile

# Stream response and show transcript
audio respond -i question.wav --stream --transcript --verbose

vad

Detección de actividad vocal offline usando segmentación Pyannote.

audio vad <file> [options]

Opción	Descripción
`<file>`	Archivo de audio a analizar
`--model, -m`	ID de modelo de HuggingFace
`--onset`	Umbral de inicio (comienzo del habla)
`--offset`	Umbral de fin (final del habla)
`--min-speech`	Duración mínima del habla en segundos
`--min-silence`	Duración mínima del silencio en segundos
`--json`	Salida en JSON

vad-stream

Detección de actividad vocal en streaming usando Silero VAD v5. Procesa audio en fragmentos de 32 ms.

audio vad-stream <file> [options]

Opción	Descripción
`<file>`	Archivo de audio a analizar
`--engine`	Motor de VAD: `mlx` (por defecto) o `coreml`
`--model, -m`	ID de modelo de HuggingFace (autoseleccionado por el motor)
`--onset`	Umbral de inicio
`--offset`	Umbral de fin
`--min-speech`	Duración mínima del habla en segundos
`--min-silence`	Duración mínima del silencio en segundos
`--json`	Salida en JSON

diarize

Diarización de hablantes — identifica quién habló cuándo.

audio diarize <file> [options]

Opción	Por defecto	Descripción
`<file>`		Archivo de audio a analizar
`--engine`	`pyannote`	Motor de diarización: `pyannote` (segmentación + encadenado de hablantes) o `sortformer` (CoreML de extremo a extremo)
`--target-speaker`		Audio de enrolamiento para extracción del hablante objetivo (solo pyannote)
`--embedding-engine`	`mlx`	Motor de embedding de hablante: `mlx` o `coreml` (solo pyannote)
`--vad-filter`		Pre-filtra con Silero VAD (solo pyannote)
`--rttm`		Salida en formato RTTM
`--json`		Salida en JSON
`--score-against`		Archivo RTTM de referencia para calcular DER

Ejemplos:

# Basic diarization (pyannote, default)
audio diarize meeting.wav

# End-to-end Sortformer (CoreML, Neural Engine)
audio diarize meeting.wav --engine sortformer

# RTTM output for evaluation
audio diarize meeting.wav --rttm

# Target speaker extraction (pyannote only)
audio diarize meeting.wav --target-speaker enrollment.wav

# Score against reference
audio diarize meeting.wav --score-against reference.rttm

embed-speaker

Extrae un vector de embedding de hablante a partir de audio.

audio embed-speaker <file> [options]

Opción	Descripción
`<file>`	Archivo de audio con la voz del hablante
`--engine`	Motor de inferencia: `mlx` (por defecto), `coreml` (WeSpeaker 256-dim) o `camplusplus` (CAM++ CoreML 192-dim)
`--json`	Salida en JSON

denoise

Elimina el ruido de fondo usando DeepFilterNet3 en el Neural Engine.

audio denoise <file> [options]

Opción	Por defecto	Descripción
`<file>`		Archivo de audio de entrada
`--output, -o`	`input_clean.wav`	Ruta del archivo de salida
`--model, -m`		ID de modelo de HuggingFace

Ejemplo:

audio denoise noisy-recording.wav -o clean.wav