Referência da CLI

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

transcribe

Transcreve arquivos de áudio para texto.

speech 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`, `nemotron`, `omnilingual`, `cohere`, `voxtral`, `moss`, `whisper`
`--model, -m`	`0.6B`	Variante do modelo: `0.6B`, `1.7B` ou ID completo do modelo no HuggingFace (apenas qwen3) `[whisper]`: `default`, `turbo`, or full CoreML HuggingFace repo ID. `[cohere/voxtral]`: INT5 (padrão), INT8, FP16, um ID de modelo do Hugging Face ou um diretório local. `[moss coreml]`: `int8` (padrão) ou `fp16`; `[moss mlx]`: `int5` (padrão) ou `int8`. Também aceita um repositório Hugging Face compatível ou diretório local.
`--max-tokens`	CoreML: `512` MLX: `5120`	`[moss]` Número máximo de tokens de transcrição gerados.
`--kv-cache`	`fp16`	`[moss mlx]` Precisão do cache KV dinâmico: `fp16` ou `int8`.
`--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) `[moss]` CoreML usa um estado fixo de 1.024 tokens; MLX oferece contexto dinâmico de 131.072 tokens.
`--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
speech transcribe recording.wav

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

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

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

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

# Omnilingual (MLX, qualquer duração até 40 s)
speech transcribe recording.wav --engine omnilingual --backend mlx                              # 300M @ 4-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 1B                  # 1B @ 4-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 3B --bits 8         # 3B @ 8-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 7B                  # 7B @ 4-bit

# Cohere Transcribe 2B (MLX, INT5 padrão)
speech transcribe recording.wav --engine cohere
speech transcribe recording.wav --engine cohere --model int8 --language de

# Voxtral Mini 3B (MLX, INT5 padrão)
speech transcribe recording.wav --engine voxtral
speech transcribe recording.wav --engine voxtral --model int8 --language fr

# MOSS Transcribe Diarize (CoreML para formato curto)
speech transcribe recording.wav --engine moss
speech transcribe recording.wav --engine moss --model fp16

# MOSS Transcribe Diarize (contexto MLX offline de 128K; INT5 padrão)
speech transcribe meeting.wav --engine moss --backend mlx
speech transcribe meeting.wav --engine moss --backend mlx --model int8 --kv-cache int8

# Whisper Large-v3 Turbo (CoreML)
speech transcribe recording.wav --engine whisper
speech transcribe recording.wav --engine whisper --model turbo --language de

# Streaming com VAD
speech transcribe recording.wav --stream --partial

align

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

speech 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
speech align recording.wav

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

speak

Síntese de texto para fala.

speech speak "<text>" [options]

Opção	Padrão	Descrição
`<text>`		Texto para sintetizar (opcional se usar `--batch-file`)
`--engine`	`qwen3`	Motor TTS: `qwen3`, `cosyvoice`, `voxcpm2`, `indextts2`, `f5`, `higgs`, `indic-mio`, `magpie` ou `magpie-coreml`
`--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 `qwen3`, `cosyvoice`, `voxcpm2`, `f5`, `higgs` e `indextts2`)
`--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

Opções do IndexTTS2

IndexTTS2 é um motor de clonagem de voz zero-shot baseado em um bundle MLX expandido. Ele requer --voice-sample e atualmente executa apenas síntese em lote.

Opção	Padrão	Descrição
`--indextts2-model-id`	`aufklarer/IndexTTS2-MLX-fp16`	ID do modelo HuggingFace. O padrão é `aufklarer/IndexTTS2-MLX-fp16`.
`--indextts2-bundle-dir`		Carrega um bundle expandido local em vez de baixar do Hugging Face.
`--indextts2-emotion-audio`		Áudio opcional de referência de emoção/estilo. O padrão é a referência do falante.
`--indextts2-emotion`		Preset opcional ou vetor de emoção com 8 valores. Presets incluem `eager`, `happy`, `excited` e `calm`.
`--indextts2-emotion-weight`	`1.0`	Escala `--indextts2-emotion`; mantenha moderado quando a identidade do falante importar.
`--indextts2-speaking-rate`	`1.0`	Multiplicador de velocidade de fala de `0.5` a `1.5`; valores acima de `1.0` são mais rápidos.
`--indextts2-max-pause`		Limite opcional para pausas internas longas de baixa energia, em segundos.
`--indextts2-s2mel-steps`	`15`	Passos de fluxo S2Mel (padrão 15, validado de ouvido; 25 replica exatamente o upstream)

F5-TTS Options

Opção	Padrão	Descrição
`--f5-reference-text`		Transcrição de referência: o texto de --voice-sample (obrigatória)
`--f5-steps`	`16`	Passos de flow matching (padrão 16; 32 para fidelidade máxima)
`--f5-cfg-strength`	`2.0`	Intensidade do guidance sem classificador
`--f5-sway`	`-1.0`	Coeficiente de amostragem sway
`--f5-speed`	`1.0`	Multiplicador de velocidade de fala
`--f5-seed`	`0`	Semente para saída determinística
`--f5-target-rms`	`0.1`	Alvo de normalização RMS da referência
`--f5-model-id`		ID de modelo do Hugging Face
`--f5-bundle-dir`		Carregar um bundle deste diretório local

Higgs TTS 3 Options

Opção	Padrão	Descrição
`--higgs-ref-text`		Transcrição de referência: o texto de --voice-sample (melhora a clonagem)
`--higgs-temperature`	`0.8`	Temperatura de amostragem (padrão 0.8)
`--higgs-top-p`		Limiar de amostragem nucleus (desligado por padrão)
`--higgs-top-k`		Corte top-k (desligado por padrão)
`--higgs-max-new-tokens`	`2048`	Máximo de quadros de áudio gerados (25 por segundo)
`--higgs-seed`	`0`	Semente para saída determinística
`--higgs-model-id`		ID de modelo do Hugging Face
`--higgs-bundle-dir`		Carregar um bundle deste diretório local

Exemplos:

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

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

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

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

# Diálogo multi-locutor
speech 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
speech speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Combinado: diálogo + emoções + clonagem de voz
speech 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
speech speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

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

# Síntese em lote a partir de arquivo
speech 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.

speech 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
speech kokoro "Hello, world!" --voice af_heart -o hello.wav

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

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

respond

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

speech 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
speech respond --input question.wav

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

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

vad

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

speech 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.

speech 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

wake

Detecção de palavras-chave no dispositivo usando o KWS Zipformer (3,49M parâmetros, CoreML INT8, 26× tempo real, apenas inglês).

speech wake <file> [options]

Opção	Descrição
`<file>`	Arquivo de áudio para analisar
`--keywords`	Uma ou mais palavras-chave. Formatos: `"hey soniqo"`, `"hey soniqo:0.15:0.5"` ou `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"` (estilo sherpa-onnx com peças BPE explícitas)
`--keywords-file`	Arquivo de palavras-chave, uma entrada por linha
`--model, -m`	ID do modelo no HuggingFace. Padrão: `aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	Saída como JSON

diarize

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

speech diarize <file> [options]

Opção	Padrão	Descrição
`<file>`		Arquivo de áudio para analisar
`--engine`	`pyannote`	Engine de diarização: `pyannote`, `community1` (CoreML + PLDA/VBx nativo) ou `sortformer`
`--community1-compute-units`	`ane`	Unidades de computação CoreML do Community-1: `ane`, `cpu`, `gpu` ou `all`
`--num-speakers`		Número exato conhecido de falantes para Community-1
`--min-speakers`	`1`	Número mínimo de falantes para Community-1
`--max-speakers`		Número máximo de falantes para Community-1
`--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)
speech diarize meeting.wav

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

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

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

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

embed-speaker

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

speech embed-speaker <file> [options]

Opção	Descrição
`<file>`	Arquivo de áudio contendo a voz do falante
`--engine`	`mlx` (padrão) ou `coreml` para WeSpeaker 256-dim; `redimnet2` para identidade persistente CoreML 192-dim; `camplusplus` para CAM++ CoreML 192-dim
`--json`	Saída como JSON

denoise

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

speech 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:

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

compose

Generate 30 s of music from a text prompt using MAGNeT on MLX.

speech compose <prompt> [options]

Option	Default	Description
`<prompt>`		Text prompt describing the music to generate (e.g. "happy rock")
`--output, -o`	`magnet.wav`	Output WAV path (32 kHz mono)
`--variant`	`small-int4`	Model variant: `small-int4`, `small-int8`, `medium-int4`, or `medium-int8`. Resolves to `aufklarer/MAGNeT-{Small,Medium}-30secs-MLX-{4,8}bit`.
`--temperature`	`3.0`	Sampling temperature, annealed linearly per stage.
`--top-p`	`0.9`	Nucleus sampling threshold.
`--cfg-max`	`10.0`	Max classifier-free guidance coefficient.
`--cfg-min`	`1.0`	Min CFG coefficient (annealed alongside the mask schedule).
`--steps`	`20,10,10,10`	Comma-separated decoding iterations per codebook (4 values).
`--seed`		Random seed for reproducible output.

Examples:

# Default: small-int4, ~10 s wall on M-series for a 30 s clip
speech compose "happy rock" -o happy_rock.wav

# Larger model — better prompt following, slower
speech compose "lo-fi hip hop with mellow piano" --variant medium-int4 -o lofi.wav

# Reproducible
speech compose "energetic EDM with synth lead" --seed 42 -o edm.wav

transcribe-batch

Transcreve um diretório de arquivos de áudio; o modelo é carregado uma única vez.

speech transcribe-batch <input-dir> [options]

Opção	Padrão	Descrição
`<input-dir>`		Diretório de arquivos de áudio a transcrever (WAV, FLAC etc.)
`--output-dir`		Diretório de saída das transcrições
`--engine`	`qwen3`	Motor ASR (mesmos valores de transcribe)
`--jsonl`		Saída em JSON lines, uma por arquivo

restore

Restaura a voz (remoção de ruído + de reverberação) com Sidon — CoreML, saída a 48 kHz.

speech restore <audio-file> [options]

Opção	Padrão	Descrição
`--output, -o`	`input_restored.wav`	Caminho do WAV de saída (48 kHz)
`--variant`	`fp16`	Variante de precisão / bundle

separate

Separa uma faixa musical em stems (vocals, drums, bass, other).

speech separate <input> [options]

Opção	Padrão	Descrição
`--stems`	`vocals,drums,bass,other`	Faixas a extrair: vocals, drums, bass, other
`--engine`	`umx`	Motor: umx (padrão) ou htdemucs (maior qualidade)
`--output-dir`		Diretório de saída das transcrições

upsample

Super-resolução de áudio com FlashSR — AudioSR destilado de um passo, saída a 48 kHz.

speech upsample <audio-file> [options]

Opção	Padrão	Descrição
`--output, -o`	`hr.wav`	Caminho do WAV de saída (48 kHz)
`--variant`	`int4`	Variante de precisão / bundle
`--seed`		Semente para saída determinística

qwen3-tts-coreml

Texto para fala com Qwen3-TTS em CoreML (Neural Engine).

speech qwen3-tts-coreml "<text>" [options]

Opção	Padrão	Descrição
`--output, -o`	`output.wav`	Caminho do WAV de saída
`--language`	`english`	Idioma de saída
`--model`		ID de modelo do Hugging Face

vibevoice

Texto para fala com Microsoft VibeVoice (MLX).

speech vibevoice "<text>" --voice-cache <cache> [options]

Opção	Padrão	Descrição
`--voice-cache, -v`		Cache de voz criado com vibevoice-encode-voice (obrigatório)
`--steps`		Passos de inferência DPM-Solver (mais passos, melhor qualidade)
`--cfg`	`1.3`	Intensidade do guidance sem classificador
`--long-form`		Síntese longa em blocos para textos extensos

vibevoice-encode-voice

Cria um cache de voz do VibeVoice a partir de uma gravação de referência e sua transcrição.

speech vibevoice-encode-voice <input> "<transcript>" [options]

Opção	Padrão	Descrição
`<input>`		Arquivo de áudio de referência
`<transcript>`		Transcrição do áudio de referência (somente inglês)
`--output, -o`		Cache de voz de saída (.safetensors)

translate

Traduz texto para o idioma alvo com MADLAD-400 (MLX).

speech translate "<text>" --to <lang> [options]

Opção	Padrão	Descrição
`--to, -t`		Código do idioma alvo (ISO 639-1, ex.: es, zh, ja)
`--stream`		Transmitir tokens durante a decodificação
`--model`		ID de modelo do Hugging Face

avatar-motion

Gera quadros de coeficientes de movimento de avatar NVIDIA Audio2Face-3D a partir de áudio de fala.

speech avatar-motion <input> [options]

Opção	Padrão	Descrição
`--output, -o`	`avatar-motion.jsonl`	Caminho do JSONL de saída
`--model`	`…James-MLX`	Bundle de identidade do avatar (James padrão; Claire e Mark disponíveis)
`--verbose`		Mostrar tempos e contagem de quadros