Referência da CLI

O binário audio é o ponto de entrada principal para todas as tarefas de processamento de fala. Compile com make build, depois execute a partir de .build/release/audio.

transcribe

Transcreve arquivos de áudio para texto.

audio transcribe <file> [options]

Opção	Padrão	Descrição
`<file>`		Arquivo de áudio para transcrever (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	Engine de ASR: `qwen3`, `qwen3-coreml`, `parakeet` ou `omnilingual`
`--model, -m`	`0.6B`	Variante do modelo: `0.6B`, `1.7B` ou ID completo do modelo no HuggingFace (apenas qwen3)
`--language`		Dica de idioma (opcional, ignorada pelo omnilingual)
`--window`	`10`	`[omnilingual]` Tamanho da janela CoreML em segundos: `5` ou `10`
`--backend`	`coreml`	`[omnilingual]` Backend: `coreml` (Neural Engine) ou `mlx` (GPU Metal)
`--variant`	`300M`	`[omnilingual mlx]` Tamanho: `300M`, `1B`, `3B` ou `7B`
`--bits`	`4`	`[omnilingual mlx]` Bits de quantização: `4` ou `8`
`--stream`		Ativa transcrição em streaming com VAD
`--max-segment`	`10`	Duração máxima do segmento em segundos (streaming)
`--partial`		Emite resultados parciais durante a fala (streaming)

Exemplos:

# Transcrição básica
audio transcribe recording.wav

# Usar modelo maior
audio transcribe recording.wav --model 1.7B

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

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

# Omnilingual (CoreML, 1.672 idiomas)
audio transcribe recording.wav --engine omnilingual                              # janela de 10 s
audio transcribe recording.wav --engine omnilingual --window 5                     # janela de 5 s

# Omnilingual (MLX, qualquer duração até 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 com VAD
audio transcribe recording.wav --stream --partial

align

Alinhamento forçado por palavra — obtenha timestamps precisos para cada palavra.

audio align <file> [options]

Opção	Padrão	Descrição
`<file>`		Arquivo de áudio
`--text, -t`		Texto para alinhar (se omitido, transcreve primeiro)
`--model, -m`	`0.6B`	Modelo de ASR para transcrição: `0.6B`, `1.7B` ou ID completo
`--aligner-model`		ID do modelo do alinhador forçado
`--language`		Dica de idioma

Exemplos:

# Transcrever automaticamente e depois alinhar
audio align recording.wav

# Alinhar com texto conhecido
audio align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

Síntese de texto para fala.

audio speak "<text>" [options]

Opção	Padrão	Descrição
`<text>`		Texto para sintetizar (opcional se usar `--batch-file`)
`--engine`	`qwen3`	Engine de TTS: `qwen3` ou `cosyvoice`
`--output, -o`	`output.wav`	Caminho do arquivo WAV de saída
`--language`	`english`	Idioma. Omita para usar o dialeto nativo do locutor quando `--speaker` estiver definido.
`--stream`		Ativa síntese em streaming
`--voice-sample`		Áudio de referência para clonagem de voz (funciona com os engines `qwen3` e `cosyvoice`)
`--verbose`		Mostra informações detalhadas de timing

Opções do Qwen3-TTS

Opção	Padrão	Descrição
`--model`	`base`	Variante do modelo: `base`, `customVoice` ou ID completo de modelo HF
`--speaker`		Voz do locutor (requer `--model customVoice`)
`--instruct`		Instrução de estilo (modelo CustomVoice)
`--list-speakers`		Lista os locutores disponíveis e sai
`--temperature`	`0.3`	Temperatura de amostragem
`--top-k`	`50`	Amostragem top-k
`--max-tokens`	`500`	Máximo de tokens (500 = ~40s de áudio)
`--batch-file`		Arquivo com um texto por linha para síntese em lote
`--batch-size`	`4`	Tamanho máximo do lote para geração paralela
`--first-chunk-frames`	`3`	Frames de codec no primeiro chunk em streaming
`--chunk-frames`	`25`	Frames de codec por chunk em streaming

Opções do CosyVoice3

Opção	Padrão	Descrição
`--speakers`		Mapeamento de locutores para diálogo multi-locutor: `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		Instrução de estilo (sobrescreve o padrão). Controla o estilo de voz do CosyVoice3.
`--turn-gap`	`0.2`	Intervalo de silêncio entre turnos de diálogo em segundos
`--crossfade`	`0.0`	Sobreposição de crossfade entre turnos em segundos
`--model-id`		ID do modelo no HuggingFace

Exemplos:

# TTS básico
audio speak "Hello, world!" --output hello.wav

# Clonagem de voz (Qwen3-TTS)
audio speak "Hello in your voice" --voice-sample reference.wav -o cloned.wav

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

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

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

# Tags de emoção/estilo inline
audio speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Combinado: diálogo + emoções + clonagem de voz
audio speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# Instrução de estilo personalizada
audio speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# Síntese em streaming
audio speak "Long text here..." --stream

# Síntese em lote a partir de arquivo
audio speak --batch-file texts.txt --batch-size 4

kokoro

Texto para fala leve usando Kokoro-82M no Neural Engine (CoreML). Não-autorregressivo — um único forward pass, latência ~45ms.

audio kokoro "<text>" [options]

Opção	Padrão	Descrição
`<text>`		Texto para sintetizar
`--voice`	`af_heart`	Preset de voz (50 disponíveis em 10 idiomas)
`--language`	`en`	Código de idioma: en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	Caminho do arquivo WAV de saída
`--list-voices`		Lista todas as vozes disponíveis e sai
`--model, -m`		ID do modelo no HuggingFace

Exemplos:

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

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

# Listar todas as 50 vozes
audio kokoro --list-voices

respond

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

audio respond [options]

Opção	Padrão	Descrição
`--input, -i`		Arquivo WAV de áudio de entrada (24kHz mono) (obrigatório)
`--output, -o`	`response.wav`	Arquivo WAV de resposta de saída
`--voice`	`NATM0`	Preset de voz (ex. NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	Preset: `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		Texto de system prompt personalizado (sobrescreve o preset)
`--max-steps`	`200`	Máximo de passos de geração a 12.5Hz (~16s)
`--stream`		Emite chunks de áudio durante a geração
`--compile`		Ativa o transformer compilado (warmup + fusão de kernels)
`--list-voices`		Lista os presets de voz disponíveis
`--list-prompts`		Lista os presets de system prompt disponíveis
`--transcript`		Imprime o texto do monólogo interno do modelo
`--json`		Saída como JSON (transcript, latência, caminho do áudio)
`--verbose`		Mostra informações detalhadas de timing

Ajustes de amostragem

Opção	Padrão	Descrição
`--audio-temp`	`0.8`	Temperatura de amostragem de áudio
`--text-temp`	`0.7`	Temperatura de amostragem de texto
`--audio-top-k`	`250`	Candidatos top-k de áudio
`--repetition-penalty`	`1.2`	Penalidade de repetição de áudio (1.0 = desativado)
`--text-repetition-penalty`	`1.2`	Penalidade de repetição de texto (1.0 = desativado)
`--repetition-window`	`30`	Janela da penalidade de repetição em frames
`--silence-early-stop`	`15`	Frames de silêncio antes do early stop (0 = desativado)
`--entropy-threshold`	`0`	Limiar de entropia de texto para early stop (0 = desativado)
`--entropy-window`	`10`	Passos consecutivos de baixa entropia antes do early stop

Exemplos:

# Fala-a-fala básico
audio respond --input question.wav

# Usar voz feminina com transformer compilado
audio respond -i question.wav --voice NATF1 --compile

# Resposta em streaming e mostrar transcript
audio respond -i question.wav --stream --transcript --verbose

vad

Detecção de atividade de voz offline usando segmentação Pyannote.

audio vad <file> [options]

Opção	Descrição
`<file>`	Arquivo de áudio para analisar
`--model, -m`	ID do modelo no HuggingFace
`--onset`	Limiar de onset (início da fala)
`--offset`	Limiar de offset (fim da fala)
`--min-speech`	Duração mínima de fala em segundos
`--min-silence`	Duração mínima de silêncio em segundos
`--json`	Saída como JSON

vad-stream

Detecção de atividade de voz em streaming usando Silero VAD v5. Processa áudio em chunks de 32ms.

audio vad-stream <file> [options]

Opção	Descrição
`<file>`	Arquivo de áudio para analisar
`--engine`	Engine de VAD: `mlx` (padrão) ou `coreml`
`--model, -m`	ID do modelo no HuggingFace (selecionado automaticamente pelo engine)
`--onset`	Limiar de onset
`--offset`	Limiar de offset
`--min-speech`	Duração mínima de fala em segundos
`--min-silence`	Duração mínima de silêncio em segundos
`--json`	Saída como JSON

diarize

Diarização de falantes — identifica quem falou quando.

audio diarize <file> [options]

Opção	Padrão	Descrição
`<file>`		Arquivo de áudio para analisar
`--engine`	`pyannote`	Engine de diarização: `pyannote` (segmentação + chaining de falantes) ou `sortformer` (CoreML ponta-a-ponta)
`--target-speaker`		Áudio de enrollment para extração de falante alvo (apenas pyannote)
`--embedding-engine`	`mlx`	Engine de embedding de falante: `mlx` ou `coreml` (apenas pyannote)
`--vad-filter`		Pré-filtro com Silero VAD (apenas pyannote)
`--rttm`		Saída no formato RTTM
`--json`		Saída como JSON
`--score-against`		Arquivo RTTM de referência para calcular DER

Exemplos:

# Diarização básica (pyannote, padrão)
audio diarize meeting.wav

# Sortformer ponta-a-ponta (CoreML, Neural Engine)
audio diarize meeting.wav --engine sortformer

# Saída RTTM para avaliação
audio diarize meeting.wav --rttm

# Extração de falante alvo (apenas pyannote)
audio diarize meeting.wav --target-speaker enrollment.wav

# Avaliar contra referência
audio diarize meeting.wav --score-against reference.rttm

embed-speaker

Extrai um vetor de embedding de falante a partir do áudio.

audio embed-speaker <file> [options]

Opção	Descrição
`<file>`	Arquivo de áudio contendo a voz do falante
`--engine`	Engine de inferência: `mlx` (padrão), `coreml` (WeSpeaker 256-dim) ou `camplusplus` (CAM++ CoreML 192-dim)
`--json`	Saída como JSON

denoise

Remove o ruído de fundo usando DeepFilterNet3 no Neural Engine.

audio denoise <file> [options]

Opção	Padrão	Descrição
`<file>`		Arquivo de áudio de entrada
`--output, -o`	`input_clean.wav`	Caminho do arquivo de saída
`--model, -m`		ID do modelo no HuggingFace

Exemplo:

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