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, omnilingual, cohere, voxtral, moss, whisper |
--model, -m | 0.6B | Variante de modèle : 0.6B, 1.7B ou ID HuggingFace complet (qwen3 uniquement) [whisper]: default, turbo, or full CoreML HuggingFace repo ID.[cohere/voxtral]: INT5 (par défaut), INT8, FP16, un identifiant de modèle Hugging Face ou un dossier local. [moss coreml] : int8 (par défaut) ou fp16 ; [moss mlx] : int5 (par défaut) ou int8. Un dépôt Hugging Face compatible ou un répertoire local est aussi accepté. |
--max-tokens | CoreML: 512MLX: 5120 | [moss] Nombre maximal de tokens de transcription générés. |
--kv-cache | fp16 | [moss mlx] Précision du cache KV dynamique : fp16 ou int8. |
--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)[moss] CoreML utilise un état fixe de 1 024 tokens ; MLX fournit un contexte dynamique de 131 072 tokens. |
--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
# Cohere Transcribe 2B (MLX, INT5 par défaut)
speech transcribe recording.wav --engine cohere
speech transcribe recording.wav --engine cohere --model int8 --language de
# Voxtral Mini 3B (MLX, INT5 par défaut)
speech transcribe recording.wav --engine voxtral
speech transcribe recording.wav --engine voxtral --model int8 --language fr
# MOSS Transcribe Diarize (CoreML, format court)
speech transcribe recording.wav --engine moss
speech transcribe recording.wav --engine moss --model fp16
# MOSS Transcribe Diarize (contexte MLX hors ligne 128K ; INT5 par défaut)
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 avec VAD
speech transcribe recording.wav --stream --partialalign
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, cosyvoice, voxcpm2, indextts2, f5, higgs, indic-mio, magpie ou magpie-coreml |
--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 qwen3, cosyvoice, voxcpm2, f5, higgs et indextts2) | |
--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 |
Options IndexTTS2
IndexTTS2 est un moteur de clonage vocal zero-shot basé sur un bundle MLX étendu. Il nécessite --voice-sample et fonctionne actuellement en synthèse batch uniquement.
| Option | Par défaut | Description |
|---|---|---|
--indextts2-model-id | aufklarer/IndexTTS2-MLX-fp16 | ID de modèle HuggingFace. Par défaut aufklarer/IndexTTS2-MLX-fp16. |
--indextts2-bundle-dir | Charge un bundle étendu local au lieu de télécharger depuis Hugging Face. | |
--indextts2-emotion-audio | Audio optionnel de référence d’émotion/style. Par défaut, la référence du locuteur est utilisée. | |
--indextts2-emotion | Preset optionnel ou vecteur d’émotion à 8 valeurs. Les presets incluent eager, happy, excited et calm. | |
--indextts2-emotion-weight | 1.0 | Met à l’échelle --indextts2-emotion ; gardez une valeur modérée si l’identité du locuteur compte. |
--indextts2-speaking-rate | 1.0 | Multiplicateur de débit de 0.5 à 1.5 ; les valeurs au-dessus de 1.0 sont plus rapides. |
--indextts2-max-pause | Plafond optionnel, en secondes, pour les longues pauses internes de faible énergie. | |
--indextts2-s2mel-steps | 15 | Pas de flux S2Mel (15 par défaut, validé à l'oreille ; 25 reproduit exactement l'upstream) |
F5-TTS Options
| Option | Par défaut | Description |
|---|---|---|
--f5-reference-text | Transcription de référence : le texte de --voice-sample (obligatoire) | |
--f5-steps | 16 | Pas de flow matching (16 par défaut ; 32 pour une fidélité maximale) |
--f5-cfg-strength | 2.0 | Force du guidage sans classifieur |
--f5-sway | -1.0 | Coefficient d'échantillonnage sway |
--f5-speed | 1.0 | Multiplicateur de débit de parole |
--f5-seed | 0 | Graine pour une sortie déterministe |
--f5-target-rms | 0.1 | Cible de normalisation RMS de la référence |
--f5-model-id | ID de modèle Hugging Face | |
--f5-bundle-dir | Charger un bundle depuis ce répertoire local |
Higgs TTS 3 Options
| Option | Par défaut | Description |
|---|---|---|
--higgs-ref-text | Transcription de référence : le texte de --voice-sample (améliore le clonage) | |
--higgs-temperature | 0.8 | Température d'échantillonnage (0.8 par défaut) |
--higgs-top-p | Seuil d'échantillonnage nucleus (désactivé par défaut) | |
--higgs-top-k | Coupure top-k (désactivée par défaut) | |
--higgs-max-new-tokens | 2048 | Trames audio générées au maximum (25 par seconde) |
--higgs-seed | 0 | Graine pour une sortie déterministe |
--higgs-model-id | ID de modèle Hugging Face | |
--higgs-bundle-dir | Charger un bundle depuis ce répertoire local |
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 4kokoro
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-voicesrespond
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 --verbosevad
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, community1 (CoreML + PLDA/VBx natif) ou sortformer |
--community1-compute-units | ane | Unités de calcul CoreML de Community-1 : ane, cpu, gpu ou all |
--num-speakers | Nombre exact connu de locuteurs pour Community-1 | |
--min-speakers | 1 | Nombre minimal de locuteurs pour Community-1 |
--max-speakers | Nombre maximal de locuteurs pour Community-1 | |
--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.rttmembed-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 | mlx (par défaut) ou coreml pour WeSpeaker 256 dim ; redimnet2 pour l'identité persistante CoreML 192 dim ; camplusplus pour 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.wavcompose
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.wavtranscribe-batch
Transcrit un répertoire de fichiers audio ; le modèle n'est chargé qu'une fois.
speech transcribe-batch <input-dir> [options]| Option | Par défaut | Description |
|---|---|---|
<input-dir> | Répertoire des fichiers audio à transcrire (WAV, FLAC, etc.) | |
--output-dir | Répertoire de sortie des transcriptions | |
--engine | qwen3 | Moteur ASR (mêmes valeurs que transcribe) |
--jsonl | Sortie en JSON lines, une par fichier |
restore
Restaure la voix (débruitage + déréverbération) avec Sidon — CoreML, sortie 48 kHz.
speech restore <audio-file> [options]| Option | Par défaut | Description |
|---|---|---|
--output, -o | input_restored.wav | Chemin du WAV de sortie (48 kHz) |
--variant | fp16 | Variante de précision / bundle |
separate
Sépare un morceau en pistes (vocals, drums, bass, other).
speech separate <input> [options]| Option | Par défaut | Description |
|---|---|---|
--stems | vocals,drums,bass,other | Pistes à extraire : vocals, drums, bass, other |
--engine | umx | Moteur : umx (défaut) ou htdemucs (meilleure qualité) |
--output-dir | Répertoire de sortie des transcriptions |
upsample
Super-résolution audio avec FlashSR — AudioSR distillé en une étape, sortie 48 kHz.
speech upsample <audio-file> [options]| Option | Par défaut | Description |
|---|---|---|
--output, -o | hr.wav | Chemin du WAV de sortie (48 kHz) |
--variant | int4 | Variante de précision / bundle |
--seed | Graine pour une sortie déterministe |
qwen3-tts-coreml
Synthèse vocale avec Qwen3-TTS sur CoreML (Neural Engine).
speech qwen3-tts-coreml "<text>" [options]| Option | Par défaut | Description |
|---|---|---|
--output, -o | output.wav | Chemin du WAV de sortie |
--language | english | Langue de sortie |
--model | ID de modèle Hugging Face |
vibevoice
Synthèse vocale avec Microsoft VibeVoice (MLX).
speech vibevoice "<text>" --voice-cache <cache> [options]| Option | Par défaut | Description |
|---|---|---|
--voice-cache, -v | Cache vocal créé par vibevoice-encode-voice (obligatoire) | |
--steps | Pas d'inférence DPM-Solver (plus de pas, meilleure qualité) | |
--cfg | 1.3 | Force du guidage sans classifieur |
--long-form | Synthèse longue par segments pour les textes longs |
vibevoice-encode-voice
Crée un cache vocal VibeVoice à partir d'un enregistrement de référence et de sa transcription.
speech vibevoice-encode-voice <input> "<transcript>" [options]| Option | Par défaut | Description |
|---|---|---|
<input> | Fichier audio de référence | |
<transcript> | Transcription de l'audio de référence (anglais uniquement) | |
--output, -o | Cache vocal de sortie (.safetensors) |
translate
Traduit du texte vers la langue cible avec MADLAD-400 (MLX).
speech translate "<text>" --to <lang> [options]| Option | Par défaut | Description |
|---|---|---|
--to, -t | Code de langue cible (ISO 639-1, p. ex. es, zh, ja) | |
--stream | Diffuser les tokens pendant le décodage | |
--model | ID de modèle Hugging Face |
avatar-motion
Génère des trames de coefficients de mouvement d'avatar NVIDIA Audio2Face-3D à partir d'audio vocal.
speech avatar-motion <input> [options]| Option | Par défaut | Description |
|---|---|---|
--output, -o | avatar-motion.jsonl | Chemin du JSONL de sortie |
--model | …James-MLX | Bundle d'identité d'avatar (James par défaut ; Claire et Mark disponibles) |
--verbose | Afficher les temps et le nombre de trames |