CLI-Referenz

Die speech-Binary ist der zentrale Einstiegspunkt für alle Sprachverarbeitungs-Aufgaben. Baue mit make build und führe sie dann aus .build/release/speech aus.

transcribe

Transkribiere Audiodateien zu Text.

speech transcribe <file> [options]

Option	Standard	Beschreibung
`<file>`		Zu transkribierende Audiodatei (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	ASR-Engine: `qwen3`, `qwen3-coreml`, `parakeet`, `nemotron` oder `omnilingual`
`--model, -m`	`0.6B`	Modellvariante: `0.6B`, `1.7B` oder vollständige HuggingFace-Modell-ID (nur qwen3)
`--language`		Sprachhinweis (optional, wird von omnilingual ignoriert)
`--window`	`10`	`[omnilingual]` CoreML-Fenstergröße in Sekunden: `5` oder `10`
`--backend`	`coreml`	`[omnilingual]` Backend: `coreml` (Neural Engine) oder `mlx` (Metal-GPU)
`--variant`	`300M`	`[omnilingual mlx]` Größe: `300M`, `1B`, `3B` oder `7B`
`--bits`	`4`	`[omnilingual mlx]` Quantisierungs-Bits: `4` oder `8`
`--stream`		Streaming-Transkription mit VAD aktivieren
`--max-segment`	`10`	Maximale Segmentdauer in Sekunden (Streaming)
`--partial`		Teilergebnisse während der Spracheingabe ausgeben (Streaming)

Beispiele:

# Basic transcription
speech transcribe recording.wav

# Use larger model
speech transcribe recording.wav --model 1.7B

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

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

# Use Nemotron Streaming (CoreML, English with native punctuation)
speech transcribe recording.wav --engine nemotron                                 # batch
speech transcribe recording.wav --engine nemotron --stream --partial              # streaming

# Omnilingual (CoreML, 1,672 languages)
speech transcribe recording.wav --engine omnilingual                              # 10 s window
speech transcribe recording.wav --engine omnilingual --window 5                     # 5 s window

# Omnilingual (MLX, any length up to 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 with VAD
speech transcribe recording.wav --stream --partial

align

Wortgenaues Forced Alignment — erhalte präzise Zeitstempel für jedes Wort.

speech align <file> [options]

Option	Standard	Beschreibung
`<file>`		Audiodatei
`--text, -t`		Zu alignierender Text (wenn nicht angegeben, wird zuerst transkribiert)
`--model, -m`	`0.6B`	ASR-Modell zur Transkription: `0.6B`, `1.7B` oder vollständige ID
`--aligner-model`		Modell-ID des Forced Aligners
`--language`		Sprachhinweis

Beispiele:

# Auto-transcribe then align
speech align recording.wav

# Align with known text
speech align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

Text-zu-Sprache-Synthese.

speech speak "<text>" [options]

Option	Standard	Beschreibung
`<text>`		Zu synthetisierender Text (optional bei Verwendung von `--batch-file`)
`--engine`	`qwen3`	TTS-Engine: `qwen3` oder `cosyvoice`
`--output, -o`	`output.wav`	Pfad der ausgegebenen WAV-Datei
`--language`	`english`	Sprache. Weglassen, um den nativen Dialekt des Sprechers zu verwenden, wenn `--speaker` gesetzt ist.
`--stream`		Streaming-Synthese aktivieren
`--voice-sample`		Referenzaudio für Stimmklonen (funktioniert sowohl mit `qwen3`- als auch mit `cosyvoice`-Engines)
`--verbose`		Detaillierte Zeitinformationen anzeigen

Qwen3-TTS-Optionen

Option	Standard	Beschreibung
`--model`	`base`	Modellvariante: `base`, `customVoice` oder vollständige HF-Modell-ID
`--speaker`		Sprecher-Stimme (erfordert `--model customVoice`)
`--instruct`		Stilanweisung (CustomVoice-Modell)
`--list-speakers`		Verfügbare Sprecher auflisten und beenden
`--temperature`	`0.3`	Sampling-Temperatur
`--top-k`	`50`	Top-k-Sampling
`--max-tokens`	`500`	Maximale Tokens (500 = ~40 s Audio)
`--batch-file`		Datei mit einem Text pro Zeile für Batch-Synthese
`--batch-size`	`4`	Maximale Batch-Größe für parallele Generierung
`--first-chunk-frames`	`3`	Codec-Frames im ersten gestreamten Chunk
`--chunk-frames`	`25`	Codec-Frames pro gestreamtem Chunk

CosyVoice3-Optionen

Option	Standard	Beschreibung
`--speakers`		Sprecher-Mapping für Mehrsprecher-Dialog: `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		Stilanweisung (überschreibt Standard). Steuert den Stimm-Stil für CosyVoice3.
`--turn-gap`	`0.2`	Pause zwischen Dialog-Turns in Sekunden
`--crossfade`	`0.0`	Crossfade-Überlappung zwischen Turns in Sekunden
`--model-id`		HuggingFace-Modell-ID

Beispiele:

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

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

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

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

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

# Inline emotion/style tags
speech speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Combined: dialogue + emotions + voice cloning
speech speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# Custom style instruction
speech speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# Streaming synthesis
speech speak "Long text here..." --stream

# Batch synthesis from file
speech speak --batch-file texts.txt --batch-size 4

kokoro

Leichtgewichtige Text-zu-Sprache-Synthese mit Kokoro-82M auf der Neural Engine (CoreML). Nicht-autoregressiv — ein einziger Forward-Pass, ~45 ms Latenz.

speech kokoro "<text>" [options]

Option	Standard	Beschreibung
`<text>`		Zu synthetisierender Text
`--voice`	`af_heart`	Stimmvoreinstellung (50 verfügbar in 10 Sprachen)
`--language`	`en`	Sprachcode: en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	Pfad der ausgegebenen WAV-Datei
`--list-voices`		Alle verfügbaren Stimmen auflisten und beenden
`--model, -m`		HuggingFace-Modell-ID

Beispiele:

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

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

# List all 50 voices
speech kokoro --list-voices

respond

Vollduplex-Sprache-zu-Sprache-Dialog mit PersonaPlex 7B.

speech respond [options]

Option	Standard	Beschreibung
`--input, -i`		Eingabe-WAV-Datei (24 kHz Mono) (erforderlich)
`--output, -o`	`response.wav`	Ausgabe-WAV-Datei der Antwort
`--voice`	`NATM0`	Stimmvoreinstellung (z. B. NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	Voreinstellung: `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		Eigener System-Prompt-Text (überschreibt Voreinstellung)
`--max-steps`	`200`	Maximale Generierungsschritte bei 12,5 Hz (~16 s)
`--stream`		Audio-Chunks während der Generierung ausgeben
`--compile`		Kompilierten Transformer aktivieren (Warmup + Kernel-Fusion)
`--list-voices`		Verfügbare Stimmvoreinstellungen auflisten
`--list-prompts`		Verfügbare System-Prompt-Voreinstellungen auflisten
`--transcript`		Inneren Monolog des Modells als Text ausgeben
`--json`		Ausgabe als JSON (Transkript, Latenz, Audio-Pfad)
`--verbose`		Detaillierte Zeitinformationen anzeigen

Sampling-Überschreibungen

Option	Standard	Beschreibung
`--audio-temp`	`0.8`	Audio-Sampling-Temperatur
`--text-temp`	`0.7`	Text-Sampling-Temperatur
`--audio-top-k`	`250`	Audio-Top-k-Kandidaten
`--repetition-penalty`	`1.2`	Audio-Wiederholungspenalty (1.0 = deaktiviert)
`--text-repetition-penalty`	`1.2`	Text-Wiederholungspenalty (1.0 = deaktiviert)
`--repetition-window`	`30`	Wiederholungspenalty-Fenster in Frames
`--silence-early-stop`	`15`	Stille-Frames vor frühem Abbruch (0 = deaktiviert)
`--entropy-threshold`	`0`	Text-Entropie-Schwelle für frühen Abbruch (0 = deaktiviert)
`--entropy-window`	`10`	Aufeinanderfolgende Schritte mit niedriger Entropie vor frühem Abbruch

Beispiele:

# Basic speech-to-speech
speech respond --input question.wav

# Use a female voice with compiled transformer
speech respond -i question.wav --voice NATF1 --compile

# Stream response and show transcript
speech respond -i question.wav --stream --transcript --verbose

vad

Offline-Sprachaktivitätserkennung mit Pyannote-Segmentierung.

speech vad <file> [options]

Option	Beschreibung
`<file>`	Zu analysierende Audiodatei
`--model, -m`	HuggingFace-Modell-ID
`--onset`	Onset-Schwelle (Sprachbeginn)
`--offset`	Offset-Schwelle (Sprachende)
`--min-speech`	Minimale Sprachdauer in Sekunden
`--min-silence`	Minimale Stille-Dauer in Sekunden
`--json`	Ausgabe als JSON

vad-stream

Streaming-Sprachaktivitätserkennung mit Silero VAD v5. Verarbeitet Audio in 32-ms-Chunks.

speech vad-stream <file> [options]

Option	Beschreibung
`<file>`	Zu analysierende Audiodatei
`--engine`	VAD-Engine: `mlx` (Standard) oder `coreml`
`--model, -m`	HuggingFace-Modell-ID (automatisch je nach Engine)
`--onset`	Onset-Schwelle
`--offset`	Offset-Schwelle
`--min-speech`	Minimale Sprachdauer in Sekunden
`--min-silence`	Minimale Stille-Dauer in Sekunden
`--json`	Ausgabe als JSON

wake

Schlüsselworterkennung auf dem Gerät mit dem KWS Zipformer (3,49 Mio. Parameter, CoreML INT8, 26× Echtzeit, nur Englisch).

speech wake <file> [options]

Option	Beschreibung
`<file>`	Zu analysierende Audiodatei
`--keywords`	Ein oder mehrere Schlüsselwörter. Formate: `"hey soniqo"`, `"hey soniqo:0.15:0.5"` oder `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"` (sherpa-onnx-Stil mit expliziten BPE-Stücken)
`--keywords-file`	Schlüsselwortdatei, ein Eintrag pro Zeile
`--model, -m`	HuggingFace-Modell-ID. Standard: `aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	Ausgabe als JSON

diarize

Sprecherdiarisierung — identifiziert, wer wann gesprochen hat.

speech diarize <file> [options]

Option	Standard	Beschreibung
`<file>`		Zu analysierende Audiodatei
`--engine`	`pyannote`	Diarisierungs-Engine: `pyannote` (Segmentierung + Sprecher-Clustering) oder `sortformer` (durchgängiges CoreML)
`--target-speaker`		Enrollment-Audio zur Zielsprecher-Extraktion (nur pyannote)
`--embedding-engine`	`mlx`	Sprechereinbettungs-Engine: `mlx` oder `coreml` (nur pyannote)
`--vad-filter`		Mit Silero VAD vorfiltern (nur pyannote)
`--rttm`		Ausgabe im RTTM-Format
`--json`		Ausgabe als JSON
`--score-against`		RTTM-Referenzdatei zur DER-Berechnung

Beispiele:

# Basic diarization (pyannote, default)
speech diarize meeting.wav

# End-to-end Sortformer (CoreML, Neural Engine)
speech diarize meeting.wav --engine sortformer

# RTTM output for evaluation
speech diarize meeting.wav --rttm

# Target speaker extraction (pyannote only)
speech diarize meeting.wav --target-speaker enrollment.wav

# Score against reference
speech diarize meeting.wav --score-against reference.rttm

embed-speaker

Extrahiert einen Sprechereinbettungs-Vektor aus Audio.

speech embed-speaker <file> [options]

Option	Beschreibung
`<file>`	Audiodatei mit der Stimme des Sprechers
`--engine`	Inferenz-Engine: `mlx` (Standard), `coreml` (WeSpeaker 256-dim) oder `camplusplus` (CAM++ CoreML 192-dim)
`--json`	Ausgabe als JSON

denoise

Entfernt Hintergrundgeräusche mit DeepFilterNet3 auf der Neural Engine.

speech denoise <file> [options]

Option	Standard	Beschreibung
`<file>`		Eingabe-Audiodatei
`--output, -o`	`input_clean.wav`	Ausgabe-Dateipfad
`--model, -m`		HuggingFace-Modell-ID

Beispiel:

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