Référence CLI

Le binaire speech est le point d'entrée principal pour toutes les tâches de traitement de la parole. Compilez avec make build, puis exécutez depuis .build/release/speech.

transcribe

Transcrit des fichiers audio en texte.

speech transcribe <fichier> [options]

Option	Par défaut	Description
`<fichier>`		Fichier audio à transcrire (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	Moteur ASR : `qwen3`, `qwen3-coreml`, `parakeet`, `nemotron` ou `omnilingual`
`--model, -m`	`0.6B`	Variante de modèle : `0.6B`, `1.7B` ou ID HuggingFace complet (qwen3 uniquement)
`--language`		Indication de langue (optionnel, ignoré par omnilingual)
`--window`	`10`	`[omnilingual]` Taille de fenêtre CoreML en secondes : `5` ou `10`
`--backend`	`coreml`	`[omnilingual]` Backend : `coreml` (Neural Engine) ou `mlx` (GPU Metal)
`--variant`	`300M`	`[omnilingual mlx]` Taille : `300M`, `1B`, `3B` ou `7B`
`--bits`	`4`	`[omnilingual mlx]` Bits de quantification : `4` ou `8`
`--stream`		Active la transcription en streaming avec VAD
`--max-segment`	`10`	Durée maximale d'un segment en secondes (streaming)
`--partial`		Émet des résultats partiels pendant la parole (streaming)

Exemples :

# Transcription de base
speech transcribe recording.wav

# Utiliser un modèle plus grand
speech transcribe recording.wav --model 1.7B

# Encodeur CoreML (Neural Engine + décodeur MLX)
speech transcribe recording.wav --engine qwen3-coreml

# Utiliser le moteur Parakeet (CoreML)
speech transcribe recording.wav --engine parakeet

# Omnilingual (CoreML, 1 672 langues)
speech transcribe recording.wav --engine omnilingual                              # fenêtre de 10 s
speech transcribe recording.wav --engine omnilingual --window 5                     # fenêtre de 5 s

# Omnilingual (MLX, toute longueur jusqu'à 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 avec VAD
speech transcribe recording.wav --stream --partial

align

Alignement forcé au niveau du mot — obtenez des horodatages précis pour chaque mot.

speech align <fichier> [options]

Option	Par défaut	Description
`<fichier>`		Fichier audio
`--text, -t`		Texte à aligner (si omis, transcrit d'abord)
`--model, -m`	`0.6B`	Modèle ASR pour la transcription : `0.6B`, `1.7B` ou ID complet
`--aligner-model`		ID du modèle d'aligneur forcé
`--language`		Indication de langue

Exemples :

# Transcription automatique puis alignement
speech align recording.wav

# Alignement avec texte connu
speech align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

Synthèse vocale (texte vers parole).

speech speak "<texte>" [options]

Option	Par défaut	Description
`<texte>`		Texte à synthétiser (optionnel avec `--batch-file`)
`--engine`	`qwen3`	Moteur TTS : `qwen3` ou `cosyvoice`
`--output, -o`	`output.wav`	Chemin du fichier WAV de sortie
`--language`	`english`	Langue. Omettez pour utiliser le dialecte natif du locuteur quand `--speaker` est défini.
`--stream`		Active la synthèse en streaming
`--voice-sample`		Audio de référence pour le clonage vocal (fonctionne avec les moteurs `qwen3` et `cosyvoice`)
`--verbose`		Affiche les informations détaillées de chronométrage

Options Qwen3-TTS

Option	Par défaut	Description
`--model`	`base`	Variante du modèle : `base`, `customVoice` ou ID HF complet
`--speaker`		Voix du locuteur (nécessite `--model customVoice`)
`--instruct`		Instruction de style (modèle CustomVoice)
`--list-speakers`		Liste les locuteurs disponibles et quitte
`--temperature`	`0.3`	Température d'échantillonnage
`--top-k`	`50`	Échantillonnage top-k
`--max-tokens`	`500`	Nombre maximal de tokens (500 = ~40 s d'audio)
`--batch-file`		Fichier avec un texte par ligne pour la synthèse par lot
`--batch-size`	`4`	Taille de lot maximale pour la génération parallèle
`--first-chunk-frames`	`3`	Trames de codec dans le premier bloc streamé
`--chunk-frames`	`25`	Trames de codec par bloc streamé

Options CosyVoice3

Option	Par défaut	Description
`--speakers`		Mappage de locuteurs pour le dialogue multi-locuteurs : `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		Instruction de style (surcharge la valeur par défaut). Contrôle le style vocal pour CosyVoice3.
`--turn-gap`	`0.2`	Silence entre les tours de dialogue en secondes
`--crossfade`	`0.0`	Fondu enchaîné entre les tours en secondes
`--model-id`		ID de modèle HuggingFace

Exemples :

# TTS de base
speech speak "Hello, world!" --output hello.wav

# Clonage vocal (Qwen3-TTS)
speech speak "Hello in your voice" --voice-sample reference.wav -o cloned.wav

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

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

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

# Balises inline d'émotion/style
speech speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Combiné : dialogue + émotions + clonage vocal
speech speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# Instruction de style personnalisée
speech speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# Synthèse en streaming
speech speak "Long text here..." --stream

# Synthèse par lot depuis un fichier
speech speak --batch-file texts.txt --batch-size 4

kokoro

Synthèse vocale légère utilisant Kokoro-82M sur Neural Engine (CoreML). Non-autoregressif — passe avant unique, latence ~45 ms.

speech kokoro "<texte>" [options]

Option	Par défaut	Description
`<texte>`		Texte à synthétiser
`--voice`	`af_heart`	Préréglage de voix (50 disponibles sur 10 langues)
`--language`	`en`	Code de langue : en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	Chemin du fichier WAV de sortie
`--list-voices`		Liste toutes les voix disponibles et quitte
`--model, -m`		ID de modèle HuggingFace

Exemples :

# Kokoro TTS de base
speech kokoro "Hello, world!" --voice af_heart -o hello.wav

# Voix française
speech kokoro "Bonjour le monde" --voice ff_siwis --language fr -o bonjour.wav

# Liste les 50 voix
speech kokoro --list-voices

respond

Dialogue parole-à-parole full-duplex utilisant PersonaPlex 7B.

speech respond [options]

Option	Par défaut	Description
`--input, -i`		Fichier WAV audio d'entrée (mono 24 kHz) (requis)
`--output, -o`	`response.wav`	Fichier WAV de réponse en sortie
`--voice`	`NATM0`	Préréglage de voix (par ex. NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	Préréglage : `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		Texte de prompt système personnalisé (surcharge le préréglage)
`--max-steps`	`200`	Étapes max de génération à 12,5 Hz (~16 s)
`--stream`		Émet des blocs audio pendant la génération
`--compile`		Active le transformeur compilé (préchauffage + fusion de noyaux)
`--list-voices`		Liste les préréglages de voix disponibles
`--list-prompts`		Liste les préréglages de prompt système disponibles
`--transcript`		Affiche le monologue intérieur du modèle
`--json`		Sortie au format JSON (transcription, latence, chemin audio)
`--verbose`		Affiche les informations détaillées de chronométrage

Surcharges d'échantillonnage

Option	Par défaut	Description
`--audio-temp`	`0.8`	Température d'échantillonnage audio
`--text-temp`	`0.7`	Température d'échantillonnage texte
`--audio-top-k`	`250`	Candidats top-k audio
`--repetition-penalty`	`1.2`	Pénalité de répétition audio (1.0 = désactivé)
`--text-repetition-penalty`	`1.2`	Pénalité de répétition texte (1.0 = désactivé)
`--repetition-window`	`30`	Fenêtre de pénalité de répétition en trames
`--silence-early-stop`	`15`	Trames de silence avant arrêt anticipé (0 = désactivé)
`--entropy-threshold`	`0`	Seuil d'entropie texte pour arrêt anticipé (0 = désactivé)
`--entropy-window`	`10`	Étapes consécutives à faible entropie avant arrêt anticipé

Exemples :

# Parole-à-parole de base
speech respond --input question.wav

# Utiliser une voix féminine avec transformeur compilé
speech respond -i question.wav --voice NATF1 --compile

# Streamer la réponse et afficher la transcription
speech respond -i question.wav --stream --transcript --verbose

vad

Détection d'activité vocale hors ligne utilisant la segmentation Pyannote.

speech vad <fichier> [options]

Option	Description
`<fichier>`	Fichier audio à analyser
`--model, -m`	ID de modèle HuggingFace
`--onset`	Seuil de début (début de parole)
`--offset`	Seuil de fin (fin de parole)
`--min-speech`	Durée minimale de parole en secondes
`--min-silence`	Durée minimale de silence en secondes
`--json`	Sortie au format JSON

vad-stream

Détection d'activité vocale en streaming utilisant Silero VAD v5. Traite l'audio par blocs de 32 ms.

speech vad-stream <fichier> [options]

Option	Description
`<fichier>`	Fichier audio à analyser
`--engine`	Moteur VAD : `mlx` (par défaut) ou `coreml`
`--model, -m`	ID de modèle HuggingFace (sélection auto selon le moteur)
`--onset`	Seuil de début
`--offset`	Seuil de fin
`--min-speech`	Durée minimale de parole en secondes
`--min-silence`	Durée minimale de silence en secondes
`--json`	Sortie au format JSON

wake

Détection de mots-clés sur appareil avec le KWS Zipformer (3,49 M paramètres, CoreML INT8, 26× temps réel, anglais uniquement).

speech wake <fichier> [options]

Option	Description
`<fichier>`	Fichier audio à analyser
`--keywords`	Un ou plusieurs mots-clés. Formats : `"hey soniqo"`, `"hey soniqo:0.15:0.5"` ou `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"` (style sherpa-onnx avec pièces BPE explicites)
`--keywords-file`	Fichier de mots-clés, une entrée par ligne
`--model, -m`	ID de modèle HuggingFace. Par défaut : `aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	Sortie au format JSON

diarize

Diarisation de locuteurs — identifier qui a parlé quand.

speech diarize <fichier> [options]

Option	Par défaut	Description
`<fichier>`		Fichier audio à analyser
`--engine`	`pyannote`	Moteur de diarisation : `pyannote` (segmentation + chaînage de locuteurs) ou `sortformer` (CoreML bout en bout)
`--target-speaker`		Audio d'enrôlement pour l'extraction du locuteur cible (pyannote uniquement)
`--embedding-engine`	`mlx`	Moteur d'empreinte de locuteur : `mlx` ou `coreml` (pyannote uniquement)
`--vad-filter`		Pré-filtrage avec Silero VAD (pyannote uniquement)
`--rttm`		Sortie au format RTTM
`--json`		Sortie au format JSON
`--score-against`		Fichier RTTM de référence pour calculer le DER

Exemples :

# Diarisation de base (pyannote, par défaut)
speech diarize meeting.wav

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

# Sortie RTTM pour l'évaluation
speech diarize meeting.wav --rttm

# Extraction de locuteur cible (pyannote uniquement)
speech diarize meeting.wav --target-speaker enrollment.wav

# Score par rapport à une référence
speech diarize meeting.wav --score-against reference.rttm

embed-speaker

Extrait un vecteur d'empreinte de locuteur depuis l'audio.

speech embed-speaker <fichier> [options]

Option	Description
`<fichier>`	Fichier audio contenant la voix du locuteur
`--engine`	Moteur d'inférence : `mlx` (par défaut), `coreml` (WeSpeaker 256 dim) ou `camplusplus` (CAM++ CoreML 192 dim)
`--json`	Sortie au format JSON

denoise

Supprime le bruit de fond en utilisant DeepFilterNet3 sur Neural Engine.

speech denoise <fichier> [options]

Option	Par défaut	Description
`<fichier>`		Fichier audio d'entrée
`--output, -o`	`input_clean.wav`	Chemin du fichier de sortie
`--model, -m`		ID de modèle HuggingFace

Exemple :

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