CLI Referansı

speech ikili dosyası, tüm konuşma işleme görevleri için ana giriş noktasıdır. make build ile derleyin, ardından .build/release/speech üzerinden çalıştırın.

transcribe

Ses dosyalarını metne dönüştürür.

speech transcribe <file> [options]

Seçenek	Varsayılan	Açıklama
`<file>`		Metne dönüştürülecek ses dosyası (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	ASR motoru: `qwen3`, `qwen3-coreml`, `parakeet`, `nemotron` veya `omnilingual`
`--model, -m`	`0.6B`	Model varyantı: `0.6B`, `1.7B` veya tam HuggingFace model kimliği (yalnızca qwen3)
`--language`		Dil ipucu (isteğe bağlı, omnilingual tarafından yok sayılır)
`--window`	`10`	`[omnilingual]` Saniye cinsinden CoreML pencere boyutu: `5` veya `10`
`--backend`	`coreml`	`[omnilingual]` Arka uç: `coreml` (Neural Engine) veya `mlx` (Metal GPU)
`--variant`	`300M`	`[omnilingual mlx]` Boyut: `300M`, `1B`, `3B` veya `7B`
`--bits`	`4`	`[omnilingual mlx]` Nicemleme biti: `4` veya `8`
`--stream`		VAD ile akışlı transkripsiyonu etkinleştir
`--max-segment`	`10`	Maksimum segment süresi (saniye, streaming)
`--partial`		Konuşma sırasında kısmi sonuçları yay (streaming)

Örnekler:

# Temel transkripsiyon
speech transcribe recording.wav

# Daha büyük modeli kullan
speech transcribe recording.wav --model 1.7B

# CoreML kodlayıcı (Neural Engine + MLX kod çözücü)
speech transcribe recording.wav --engine qwen3-coreml

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

# Nemotron Streaming'i kullan (CoreML, yerel noktalama işaretli İngilizce)
speech transcribe recording.wav --engine nemotron                                 # toplu
speech transcribe recording.wav --engine nemotron --stream --partial              # streaming

# Omnilingual (CoreML, 1.672 dil)
speech transcribe recording.wav --engine omnilingual                              # 10 sn pencere
speech transcribe recording.wav --engine omnilingual --window 5                     # 5 sn pencere

# Omnilingual (MLX, 40 sn'ye kadar herhangi bir uzunluk)
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

# VAD ile streaming
speech transcribe recording.wav --stream --partial

align

Sözcük düzeyinde zorunlu hizalama — her sözcük için kesin zaman damgaları elde edin.

speech align <file> [options]

Seçenek	Varsayılan	Açıklama
`<file>`		Ses dosyası
`--text, -t`		Hizalanacak metin (atlanırsa önce transkribe edilir)
`--model, -m`	`0.6B`	Transkripsiyon için ASR modeli: `0.6B`, `1.7B` veya tam kimlik
`--aligner-model`		Zorunlu hizalayıcı model kimliği
`--language`		Dil ipucu

Örnekler:

# Otomatik transkribe edip sonra hizala
speech align recording.wav

# Bilinen metinle hizala
speech align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

Metinden konuşma sentezi.

speech speak "<text>" [options]

Seçenek	Varsayılan	Açıklama
`<text>`		Sentezlenecek metin (`--batch-file` kullanılıyorsa isteğe bağlı)
`--engine`	`qwen3`	TTS motoru: `qwen3`, `cosyvoice`, `voxcpm2` veya `magpie`
`--output, -o`	`output.wav`	Çıktı WAV dosya yolu
`--language`	`english`	Dil. `--speaker` ayarlandığında konuşmacının yerel lehçesini kullanmak için boş bırakın.
`--stream`		Akışlı sentezi etkinleştir
`--voice-sample`		Ses klonlama için referans ses (hem `qwen3` hem de `cosyvoice` motorlarıyla çalışır)
`--verbose`		Ayrıntılı zamanlama bilgisi göster

Qwen3-TTS Seçenekleri

Seçenek	Varsayılan	Açıklama
`--model`	`base`	Model varyantı: `base`, `customVoice` veya tam HF model kimliği
`--speaker`		Konuşmacı sesi (`--model customVoice` gerektirir)
`--instruct`		Stil yönergesi (CustomVoice modeli)
`--list-speakers`		Mevcut konuşmacıları listele ve çık
`--temperature`	`0.3`	Örnekleme sıcaklığı
`--top-k`	`50`	Top-k örnekleme
`--max-tokens`	`500`	Maksimum token (500 = ~40s ses)
`--batch-file`		Toplu sentez için satır başına bir metin içeren dosya
`--batch-size`	`4`	Paralel üretim için maksimum toplu boyut
`--first-chunk-frames`	`3`	İlk akış parçasındaki codec çerçeve sayısı
`--chunk-frames`	`25`	Akış parçası başına codec çerçeve sayısı

CosyVoice3 Seçenekleri

Seçenek	Varsayılan	Açıklama
`--speakers`		Çok konuşmacılı diyalog için konuşmacı eşlemesi: `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		Stil yönergesi (varsayılanı geçersiz kılar). CosyVoice3 için ses stilini denetler.
`--turn-gap`	`0.2`	Diyalog sıraları arasındaki sessizlik boşluğu (saniye)
`--crossfade`	`0.0`	Sıralar arasındaki crossfade örtüşmesi (saniye)
`--model-id`		HuggingFace model kimliği

VoxCPM2 Seçenekleri

Seçenek	Varsayılan	Açıklama
`--voxcpm2-variant`	`bf16`	Nicemleme varyantı: `bf16`, `int8` veya `int4`. `aufklarer/VoxCPM2-MLX-<variant>`'a karşılık gelir.
`--voxcpm2-instruct`		Doğal dilde ses açıklaması (ses tasarımı), örn. "genç bir kadın, sıcak ve nazik".
`--voxcpm2-ref-audio`		Klonlama için referans ses dosyası (16 kHz mono, dahili olarak yeniden örneklenir).
`--voxcpm2-prompt-audio` / `--voxcpm2-prompt-text`		"Nihai klonlama" çifti — prozodi koruyan klonlama için referans klip + transkripti.
`--voxcpm2-cfg-value`	`2.0`	Diffusion örnekleyici için classifier-free guidance ölçeği.
`--voxcpm2-timesteps`	`10`	Üretilen ses yaması başına Euler çözücü adımı.
`--voxcpm2-max-tokens`	`2000`	Zorunlu durdurmadan önceki maksimum yama sayısı.
`--voxcpm2-min-tokens`	`2`	Durdurma başlığının ateşlemesine izin verilmeden önceki minimum yama sayısı.
`--seed`		Sentezden önce MLX RNG'ı tohumla (çalıştırmalar arasında deterministik).

Magpie Seçenekleri

NVIDIA Magpie-TTS Multilingual 357M, 9 dilde 5 önceden hazırlanmış konuşmacı. Arka ucu --engine magpie (MLX, varsayılan) veya --engine magpie-coreml (büyük modeller için CoreML, LocalTransformer + ses embedding'lerini MLX yönetir) ile seçin. Dile özgü tam G2P dökümü için Magpie kılavuzuna bakın. Ses klonlama desteklenmez: --voice-sample, --speaker ve --instruct, --magpie-speaker'ı işaret eden yardımcı bir hatayla reddedilir.

Seçenek	Varsayılan	Açıklama
`--magpie-variant`	`int4`	Yalnızca MLX. Nicemleme: `int4` (247 MB) veya `int8` (411 MB). `aufklarer/Magpie-TTS-Multilingual-357M-MLX-<variant>`'a karşılık gelir. CoreML motoru INT8 CoreML paketini kullanır ve bu bayrağı yok sayar.
`--magpie-speaker`	`sofia`	Önceden hazırlanmış konuşmacı: `sofia`, `aria`, `jason`, `leo` veya `john`. Kimlik 9 dilin ve her iki arka ucun tamamında tutarlıdır.
`--magpie-temperature`	`0.6`	Örnekleme sıcaklığı (0 = greedy). Japonca için `0.6` kullanın — greedy ilk ifadede takılır.
`--magpie-top-k`	`80`	Örnekleme için top-k filtresi.
`--magpie-max-frames`	`500`	Codec çerçeve sayısı için sabit üst sınır (~23 sn).
`--magpie-min-frames`	`4`	EOS'a izin verilmeden önceki minimum çerçeve sayısı.
`--magpie-prephonemized`		Girdiyi IPA / fonem akışı olarak ele al; dile özgü G2P'yi atla.
`--list-speakers`		5 önceden hazırlanmış konuşmacıyı yazdır ve çık.

magpie-coreml uyarıları: Birlikte gelen NanoCodec, sabit 64 çerçevelik bir pencerede izlenir, bu nedenle --stream reddedilir. --language ja, stderr notuyla otomatik olarak MLX arka ucuna yönlendirilir (CoreML paketi henüz JA tokenizer kaynaklarını içermiyor). CoreML motoru, LocalTransformer'ı çalıştırmak ve ses embedding'lerini ortalamak için ilk sentezde MLX paketini tembelce yükler; saf CoreML dağıtımı bir takip öğesi olarak izlenmektedir.

Örnekler:

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

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

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

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

# Çok konuşmacılı diyalog
speech speak "[S1] Hello there! [S2] Hey, how are you?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o dialogue.wav

# Satır içi duygu/stil etiketleri
speech speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Birleşik: diyalog + duygular + ses klonlama
speech speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# Özel stil yönergesi
speech speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# Magpie çok dilli TTS — 9 dilde aynı Aria sesi
speech speak "Hello, world." --engine magpie --magpie-speaker aria \
    --magpie-temperature 0 -o en.wav
speech speak "Hola mundo." --engine magpie --language es --magpie-speaker aria \
    --magpie-temperature 0 -o es.wav
# Japonca stokastik örnekleme gerektirir
speech speak "こんにちは世界、これは音声合成システムです。" \
    --engine magpie --language ja --magpie-temperature 0.6 \
    --magpie-top-k 80 --seed 42 -o ja.wav
speech speak --engine magpie --list-speakers

# Magpie CoreML arka ucu (ANE hızlandırmalı, 8 dil, streaming yok)
speech speak "Hello world." --engine magpie-coreml --magpie-speaker aria -o en.wav
speech speak "Hola mundo." --engine magpie-coreml --language es \
    --magpie-speaker leo -o es.wav
# Japonca otomatik olarak MLX'e yönlendirilir (CoreML paketinde JA tokenizer yok)
speech speak "こんにちは。" --engine magpie-coreml --language ja -o ja.wav

# Akışlı sentez
speech speak "Long text here..." --stream

# Dosyadan toplu sentez
speech speak --batch-file texts.txt --batch-size 4

# VoxCPM2 — 48 kHz stüdyo çıktısı
speech speak "Hello there." --engine voxcpm2 --voxcpm2-variant int8 -o hi.wav

# VoxCPM2 — ses tasarımı
speech speak "Welcome to the show." --engine voxcpm2 \
    --voxcpm2-instruct "A young woman, warm and gentle voice." -o design.wav

# VoxCPM2 — tek referansla klonlama
speech speak "This is a cloned voice." --engine voxcpm2 \
    --voice-sample speaker.wav -o clone.wav

kokoro

Neural Engine (CoreML) üzerinde Kokoro-82M kullanan hafif metinden konuşmaya. Otomatik gerilemesiz — tek ileri geçiş, ~45ms gecikme.

speech kokoro "<text>" [options]

Seçenek	Varsayılan	Açıklama
`<text>`		Sentezlenecek metin
`--voice`	`af_heart`	Ses ön ayarı (10 dilde 50 mevcut)
`--language`	`en`	Dil kodu: en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	Çıktı WAV dosya yolu
`--list-voices`		Tüm mevcut sesleri listele ve çık
`--model, -m`		HuggingFace model kimliği

Örnekler:

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

# Fransızca ses
speech kokoro "Bonjour le monde" --voice ff_siwis --language fr -o bonjour.wav

# 50 sesin tümünü listele
speech kokoro --list-voices

respond

PersonaPlex 7B kullanarak tam çift yönlü konuşmadan konuşmaya diyalog.

speech respond [options]

Seçenek	Varsayılan	Açıklama
`--input, -i`		Giriş ses WAV dosyası (24kHz mono) (zorunlu)
`--output, -o`	`response.wav`	Çıktı yanıt WAV dosyası
`--voice`	`NATM0`	Ses ön ayarı (örn. NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	Ön ayar: `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		Özel sistem prompt metni (ön ayarı geçersiz kılar)
`--max-steps`	`200`	12.5Hz'de maksimum üretim adımı (~16sn)
`--stream`		Üretim sırasında ses parçalarını yay
`--compile`		Derlenmiş transformer'ı etkinleştir (ısınma + çekirdek füzyonu)
`--list-voices`		Mevcut ses ön ayarlarını listele
`--list-prompts`		Mevcut sistem prompt ön ayarlarını listele
`--transcript`		Modelin iç monolog metnini yazdır
`--json`		JSON olarak çıktı ver (transkript, gecikme, ses yolu)
`--verbose`		Ayrıntılı zamanlama bilgisi göster

Örnekleme Geçersiz Kılmaları

Seçenek	Varsayılan	Açıklama
`--audio-temp`	`0.8`	Ses örnekleme sıcaklığı
`--text-temp`	`0.7`	Metin örnekleme sıcaklığı
`--audio-top-k`	`250`	Ses top-k aday sayısı
`--repetition-penalty`	`1.2`	Ses tekrar cezası (1.0 = devre dışı)
`--text-repetition-penalty`	`1.2`	Metin tekrar cezası (1.0 = devre dışı)
`--repetition-window`	`30`	Çerçeve cinsinden tekrar cezası penceresi
`--silence-early-stop`	`15`	Erken durdurmadan önceki sessizlik çerçeve sayısı (0 = devre dışı)
`--entropy-threshold`	`0`	Erken durdurma için metin entropi eşiği (0 = devre dışı)
`--entropy-window`	`10`	Erken durdurmadan önceki ardışık düşük entropi adımları

Örnekler:

# Temel konuşmadan konuşmaya
speech respond --input question.wav

# Derlenmiş transformer ile kadın sesi kullan
speech respond -i question.wav --voice NATF1 --compile

# Yanıtı stream et ve transkripti göster
speech respond -i question.wav --stream --transcript --verbose

vad

Pyannote segmentasyonu kullanarak çevrimdışı ses etkinliği algılama.

speech vad <file> [options]

Seçenek	Açıklama
`<file>`	Analiz edilecek ses dosyası
`--model, -m`	HuggingFace model kimliği
`--onset`	Onset eşiği (konuşma başlangıcı)
`--offset`	Offset eşiği (konuşma sonu)
`--min-speech`	Saniye cinsinden minimum konuşma süresi
`--min-silence`	Saniye cinsinden minimum sessizlik süresi
`--json`	JSON olarak çıktı ver

vad-stream

Silero VAD v5 kullanan akışlı ses etkinliği algılama. Konuşmayı 32ms parçalar halinde işler.

speech vad-stream <file> [options]

Seçenek	Açıklama
`<file>`	Analiz edilecek ses dosyası
`--engine`	VAD motoru: `mlx` (varsayılan) veya `coreml`
`--model, -m`	HuggingFace model kimliği (motora göre otomatik seçilir)
`--onset`	Onset eşiği
`--offset`	Offset eşiği
`--min-speech`	Saniye cinsinden minimum konuşma süresi
`--min-silence`	Saniye cinsinden minimum sessizlik süresi
`--json`	JSON olarak çıktı ver

wake

KWS Zipformer (3.49M parametre, CoreML INT8, 26× gerçek zamanlı, yalnızca İngilizce) kullanan cihaz içi uyandırma sözcüğü / anahtar sözcük algılama.

speech wake <file> [options]

Seçenek	Açıklama
`<file>`	Analiz edilecek ses dosyası
`--keywords`	Bir veya daha fazla anahtar sözcük. Biçimler: `"hey soniqo"` (greedy BPE), `"hey soniqo:0.15:0.5"` (eşik/boost ile) veya `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"` (sherpa-onnx tarzı açık BPE parçaları)
`--keywords-file`	Anahtar sözcük dosyası, satır başına bir giriş (`--keywords` ile aynı sözdizimi); yorumlar için `#`
`--model, -m`	HuggingFace model kimliği. Varsayılan: `aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	JSON olarak çıktı ver

# Düz ifade, ayarlanmış varsayılanlar
speech wake recording.wav --keywords "hey soniqo"

# Greedy tokenizer'ın yanlış anladığı ifadeler için açık BPE parçaları
speech wake recording.wav --keywords "LIGHT UP|▁ L IGHT ▁UP:0.25:2.0"

# Birden fazla ifade + JSON çıktı
speech wake recording.wav \
  --keywords "lovely child|▁LOVE LY ▁CHI L D:0.25:2.0" \
             "for ever|▁FOR E VER:0.25:2.0" \
  --json

diarize

Konuşmacı ayrıştırma — kimin ne zaman konuştuğunu belirleyin.

speech diarize <file> [options]

Seçenek	Varsayılan	Açıklama
`<file>`		Analiz edilecek ses dosyası
`--engine`	`pyannote`	Ayrıştırma motoru: `pyannote` (segmentasyon + konuşmacı zincirleme) veya `sortformer` (uçtan uca CoreML)
`--target-speaker`		Hedef konuşmacı çıkarımı için kayıt sesi (yalnızca pyannote)
`--embedding-engine`	`mlx`	Konuşmacı embedding motoru: `mlx` veya `coreml` (yalnızca pyannote)
`--vad-filter`		Silero VAD ile ön filtre (yalnızca pyannote)
`--rttm`		RTTM biçiminde çıktı
`--json`		JSON olarak çıktı ver
`--score-against`		DER hesaplamak için referans RTTM dosyası

Örnekler:

# Temel ayrıştırma (pyannote, varsayılan)
speech diarize meeting.wav

# Uçtan uca Sortformer (CoreML, Neural Engine)
speech diarize meeting.wav --engine sortformer

# Değerlendirme için RTTM çıktısı
speech diarize meeting.wav --rttm

# Hedef konuşmacı çıkarımı (yalnızca pyannote)
speech diarize meeting.wav --target-speaker enrollment.wav

# Referansa göre puanla
speech diarize meeting.wav --score-against reference.rttm

embed-speaker

Sesten bir konuşmacı embedding vektörü çıkarın.

speech embed-speaker <file> [options]

Seçenek	Açıklama
`<file>`	Konuşmacı sesini içeren ses dosyası
`--engine`	Çıkarım motoru: `mlx` (varsayılan), `coreml` (WeSpeaker 256 boyut) veya `camplusplus` (CAM++ CoreML 192 boyut)
`--json`	JSON olarak çıktı ver

denoise

Neural Engine üzerinde DeepFilterNet3 kullanarak arka plan gürültüsünü kaldırır.

speech denoise <file> [options]

Seçenek	Varsayılan	Açıklama
`<file>`		Giriş ses dosyası
`--output, -o`	`input_clean.wav`	Çıktı dosya yolu
`--model, -m`		HuggingFace model kimliği

Örnek:

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

compose

MLX üzerinde MAGNeT kullanarak bir metin prompt'undan 30 sn müzik üretin.

speech compose <prompt> [options]

Seçenek	Varsayılan	Açıklama
`<prompt>`		Üretilecek müziği tanımlayan metin prompt'u (örn. "happy rock")
`--output, -o`	`magnet.wav`	Çıktı WAV yolu (32 kHz mono)
`--variant`	`small-int4`	Model varyantı: `small-int4`, `small-int8`, `medium-int4` veya `medium-int8`. `aufklarer/MAGNeT-{Small,Medium}-30secs-MLX-{4,8}bit`'e karşılık gelir.
`--temperature`	`3.0`	Örnekleme sıcaklığı, aşama başına doğrusal olarak tavlanır.
`--top-p`	`0.9`	Nucleus örnekleme eşiği.
`--cfg-max`	`10.0`	Maksimum classifier-free guidance katsayısı.
`--cfg-min`	`1.0`	Minimum CFG katsayısı (mask çizelgesiyle birlikte tavlanır).
`--steps`	`20,10,10,10`	Codebook başına virgülle ayrılmış kod çözme yinelemesi (4 değer).
`--seed`		Yeniden üretilebilir çıktı için rastgele tohum.

Örnekler:

# Varsayılan: small-int4, 30 sn klip için M serisi üzerinde ~10 sn duvar
speech compose "happy rock" -o happy_rock.wav

# Daha büyük model — prompt'a daha iyi uyum, daha yavaş
speech compose "lo-fi hip hop with mellow piano" --variant medium-int4 -o lofi.wav

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