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

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

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