Tham khảo CLI

Tệp thực thi speech là điểm vào chính cho mọi tác vụ xử lý giọng nói. Biên dịch bằng make build, sau đó chạy từ .build/release/speech.

transcribe

Chuyển tệp âm thanh thành văn bản.

speech transcribe <file> [options]

Tùy chọn	Mặc định	Mô tả
`<file>`		Tệp âm thanh để chuyển thành văn bản (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	Engine ASR: `qwen3`, `qwen3-coreml`, `parakeet`, `nemotron` hoặc `omnilingual`
`--model, -m`	`0.6B`	Biến thể mô hình: `0.6B`, `1.7B` hoặc ID mô hình HuggingFace đầy đủ (chỉ qwen3)
`--language`		Gợi ý ngôn ngữ (tùy chọn, bị bỏ qua bởi omnilingual)
`--window`	`10`	`[omnilingual]` Kích thước cửa sổ CoreML tính bằng giây: `5` hoặc `10`
`--backend`	`coreml`	`[omnilingual]` Backend: `coreml` (Neural Engine) hoặc `mlx` (Metal GPU)
`--variant`	`300M`	`[omnilingual mlx]` Kích thước: `300M`, `1B`, `3B` hoặc `7B`
`--bits`	`4`	`[omnilingual mlx]` Số bit lượng tử hóa: `4` hoặc `8`
`--stream`		Bật chuyển âm thanh thành văn bản kiểu streaming với VAD
`--max-segment`	`10`	Thời lượng tối đa của một đoạn, tính bằng giây (streaming)
`--partial`		Phát kết quả từng phần trong khi đang nói (streaming)

Ví dụ:

# Chuyển âm thanh thành văn bản cơ bản
speech transcribe recording.wav

# Dùng mô hình lớn hơn
speech transcribe recording.wav --model 1.7B

# Bộ mã hóa CoreML (Neural Engine + bộ giải mã MLX)
speech transcribe recording.wav --engine qwen3-coreml

# Dùng engine Parakeet (CoreML)
speech transcribe recording.wav --engine parakeet

# Dùng Nemotron Streaming (CoreML, tiếng Anh có dấu câu gốc)
speech transcribe recording.wav --engine nemotron                                 # theo lô
speech transcribe recording.wav --engine nemotron --stream --partial              # streaming

# Omnilingual (CoreML, 1.672 ngôn ngữ)
speech transcribe recording.wav --engine omnilingual                              # cửa sổ 10 s
speech transcribe recording.wav --engine omnilingual --window 5                     # cửa sổ 5 s

# Omnilingual (MLX, độ dài bất kỳ tới 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 kèm VAD
speech transcribe recording.wav --stream --partial

align

Căn chỉnh cưỡng bức ở cấp từ — lấy dấu thời gian chính xác cho từng từ.

speech align <file> [options]

Tùy chọn	Mặc định	Mô tả
`<file>`		Tệp âm thanh
`--text, -t`		Văn bản để căn chỉnh (nếu bỏ qua thì sẽ chuyển âm thanh thành văn bản trước)
`--model, -m`	`0.6B`	Mô hình ASR dùng cho chuyển âm thanh: `0.6B`, `1.7B` hoặc ID đầy đủ
`--aligner-model`		ID mô hình aligner cưỡng bức
`--language`		Gợi ý ngôn ngữ

Ví dụ:

# Tự chuyển âm thanh thành văn bản rồi căn chỉnh
speech align recording.wav

# Căn chỉnh với văn bản đã biết
speech align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

Tổng hợp văn bản thành giọng nói.

speech speak "<text>" [options]

Tùy chọn	Mặc định	Mô tả
`<text>`		Văn bản cần tổng hợp (tùy chọn nếu dùng `--batch-file`)
`--engine`	`qwen3`	Engine TTS: `qwen3`, `cosyvoice`, `voxcpm2` hoặc `magpie`
`--output, -o`	`output.wav`	Đường dẫn tệp WAV đầu ra
`--language`	`english`	Ngôn ngữ. Bỏ qua để dùng phương ngữ gốc của người nói khi đã đặt `--speaker`.
`--stream`		Bật tổng hợp dạng streaming
`--voice-sample`		Âm thanh tham chiếu để nhân bản giọng nói (hoạt động với cả engine `qwen3` và `cosyvoice`)
`--verbose`		Hiển thị thông tin thời gian chi tiết

Tùy chọn Qwen3-TTS

Tùy chọn	Mặc định	Mô tả
`--model`	`base`	Biến thể mô hình: `base`, `customVoice` hoặc ID mô hình HF đầy đủ
`--speaker`		Giọng người nói (yêu cầu `--model customVoice`)
`--instruct`		Chỉ thị về phong cách (mô hình CustomVoice)
`--list-speakers`		Liệt kê các giọng có sẵn rồi thoát
`--temperature`	`0.3`	Nhiệt độ lấy mẫu
`--top-k`	`50`	Lấy mẫu Top-k
`--max-tokens`	`500`	Số token tối đa (500 = ~40s âm thanh)
`--batch-file`		Tệp chứa mỗi dòng một văn bản để tổng hợp theo lô
`--batch-size`	`4`	Kích thước lô tối đa để tạo song song
`--first-chunk-frames`	`3`	Số frame codec trong chunk streaming đầu tiên
`--chunk-frames`	`25`	Số frame codec mỗi chunk streaming

Tùy chọn CosyVoice3

Tùy chọn	Mặc định	Mô tả
`--speakers`		Ánh xạ người nói cho hội thoại nhiều người: `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		Chỉ thị về phong cách (ghi đè mặc định). Điều khiển phong cách giọng nói cho CosyVoice3.
`--turn-gap`	`0.2`	Khoảng lặng giữa các lượt trong hội thoại, tính bằng giây
`--crossfade`	`0.0`	Crossfade chồng giữa các lượt, tính bằng giây
`--model-id`		ID mô hình HuggingFace

Tùy chọn VoxCPM2

Tùy chọn	Mặc định	Mô tả
`--voxcpm2-variant`	`bf16`	Biến thể lượng tử hóa: `bf16`, `int8` hoặc `int4`. Tương ứng với `aufklarer/VoxCPM2-MLX-<variant>`.
`--voxcpm2-instruct`		Mô tả giọng nói bằng ngôn ngữ tự nhiên (thiết kế giọng), ví dụ "một phụ nữ trẻ, ấm áp và dịu dàng".
`--voxcpm2-ref-audio`		Tệp âm thanh tham chiếu để nhân bản (16 kHz mono, sẽ được lấy mẫu lại nội bộ).
`--voxcpm2-prompt-audio` / `--voxcpm2-prompt-text`		Cặp "nhân bản tối ưu" — đoạn tham chiếu + bản chép của nó để nhân bản giữ nguyên ngữ điệu.
`--voxcpm2-cfg-value`	`2.0`	Tỉ lệ classifier-free guidance cho bộ lấy mẫu diffusion.
`--voxcpm2-timesteps`	`10`	Số bước solver Euler trên mỗi patch âm thanh được tạo.
`--voxcpm2-max-tokens`	`2000`	Số patch tối đa trước khi buộc dừng.
`--voxcpm2-min-tokens`	`2`	Số patch tối thiểu trước khi cho phép đầu dừng kích hoạt.
`--seed`		Seed RNG của MLX trước khi tổng hợp (kết quả nhất quán giữa các lần chạy).

Tùy chọn Magpie

NVIDIA Magpie-TTS Multilingual 357M, 9 ngôn ngữ với 5 giọng dựng sẵn. Chọn backend bằng --engine magpie (MLX, mặc định) hoặc --engine magpie-coreml (CoreML cho mô hình lớn với MLX đảm nhiệm LocalTransformer + embedding âm thanh). Xem hướng dẫn Magpie để biết chi tiết phân tách G2P theo từng ngôn ngữ. Không hỗ trợ nhân bản giọng nói: --voice-sample, --speaker và --instruct sẽ bị từ chối kèm thông báo hữu ích trỏ tới --magpie-speaker.

Tùy chọn	Mặc định	Mô tả
`--magpie-variant`	`int4`	Chỉ dùng cho MLX. Lượng tử hóa: `int4` (247 MB) hoặc `int8` (411 MB). Tương ứng với `aufklarer/Magpie-TTS-Multilingual-357M-MLX-<variant>`. Engine CoreML dùng bundle CoreML INT8 và bỏ qua cờ này.
`--magpie-speaker`	`sofia`	Giọng dựng sẵn: `sofia`, `aria`, `jason`, `leo` hoặc `john`. Bản sắc giọng đồng nhất trên cả 9 ngôn ngữ và cả hai backend.
`--magpie-temperature`	`0.6`	Nhiệt độ lấy mẫu (0 = greedy). Dùng `0.6` cho tiếng Nhật — greedy bị kẹt ở cụm đầu tiên.
`--magpie-top-k`	`80`	Bộ lọc top-k cho lấy mẫu.
`--magpie-max-frames`	`500`	Giới hạn cứng số frame codec (~23 s).
`--magpie-min-frames`	`4`	Số frame tối thiểu trước khi cho phép EOS.
`--magpie-prephonemized`		Coi đầu vào là luồng IPA / phoneme; bỏ qua G2P theo từng ngôn ngữ.
`--list-speakers`		In 5 giọng dựng sẵn rồi thoát.

Lưu ý về magpie-coreml: NanoCodec đi kèm được trace ở cửa sổ cố định 64 frame, vì vậy --stream bị từ chối. --language ja tự định tuyến sang backend MLX kèm ghi chú trên stderr (bundle CoreML chưa kèm tài nguyên tokenizer JA). Engine CoreML tải lười bundle MLX ở lần tổng hợp đầu tiên để vận hành LocalTransformer và trung bình hóa embedding âm thanh; triển khai thuần CoreML đang được theo dõi như một mục tiếp theo.

Ví dụ:

# TTS cơ bản
speech speak "Hello, world!" --output hello.wav

# Nhân bản giọng (Qwen3-TTS)
speech speak "Hello in your voice" --voice-sample reference.wav -o cloned.wav

# Nhân bản giọng (CosyVoice)
speech speak "Hello in your voice" --engine cosyvoice --voice-sample reference.wav -o cloned.wav

# CosyVoice đa ngôn ngữ
speech speak "Hallo Welt" --engine cosyvoice --language german -o hallo.wav

# Hội thoại nhiều người nói
speech speak "[S1] Hello there! [S2] Hey, how are you?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o dialogue.wav

# Thẻ cảm xúc/phong cách inline
speech speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# Kết hợp: hội thoại + cảm xúc + nhân bản giọng
speech speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# Chỉ thị phong cách tùy chỉnh
speech speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# Magpie TTS đa ngôn ngữ — cùng giọng Aria trên 9 ngôn ngữ
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
# Tiếng Nhật cần lấy mẫu ngẫu nhiên
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

# Backend Magpie CoreML (tăng tốc ANE, 8 ngôn ngữ, không streaming)
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
# Tiếng Nhật tự định tuyến sang MLX (bundle CoreML không có tokenizer JA)
speech speak "こんにちは。" --engine magpie-coreml --language ja -o ja.wav

# Tổng hợp dạng streaming
speech speak "Long text here..." --stream

# Tổng hợp theo lô từ tệp
speech speak --batch-file texts.txt --batch-size 4

# VoxCPM2 — đầu ra studio 48 kHz
speech speak "Hello there." --engine voxcpm2 --voxcpm2-variant int8 -o hi.wav

# VoxCPM2 — thiết kế giọng nói
speech speak "Welcome to the show." --engine voxcpm2 \
    --voxcpm2-instruct "A young woman, warm and gentle voice." -o design.wav

# VoxCPM2 — nhân bản từ một tham chiếu
speech speak "This is a cloned voice." --engine voxcpm2 \
    --voice-sample speaker.wav -o clone.wav

kokoro

TTS nhẹ dùng Kokoro-82M trên Neural Engine (CoreML). Không tự hồi quy — một lần forward duy nhất, độ trễ ~45ms.

speech kokoro "<text>" [options]

Tùy chọn	Mặc định	Mô tả
`<text>`		Văn bản cần tổng hợp
`--voice`	`af_heart`	Giọng dựng sẵn (50 giọng trên 10 ngôn ngữ)
`--language`	`en`	Mã ngôn ngữ: en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	Đường dẫn tệp WAV đầu ra
`--list-voices`		Liệt kê tất cả giọng có sẵn rồi thoát
`--model, -m`		ID mô hình HuggingFace

Ví dụ:

# Kokoro TTS cơ bản
speech kokoro "Hello, world!" --voice af_heart -o hello.wav

# Giọng Pháp
speech kokoro "Bonjour le monde" --voice ff_siwis --language fr -o bonjour.wav

# Liệt kê toàn bộ 50 giọng
speech kokoro --list-voices

respond

Hội thoại giọng nói tới giọng nói full-duplex bằng PersonaPlex 7B.

speech respond [options]

Tùy chọn	Mặc định	Mô tả
`--input, -i`		Tệp WAV âm thanh đầu vào (24kHz mono) (bắt buộc)
`--output, -o`	`response.wav`	Tệp WAV phản hồi đầu ra
`--voice`	`NATM0`	Giọng dựng sẵn (ví dụ NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	Preset: `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		Văn bản system prompt tùy chỉnh (ghi đè preset)
`--max-steps`	`200`	Số bước tạo tối đa ở 12.5Hz (~16s)
`--stream`		Phát các chunk âm thanh trong khi tạo
`--compile`		Bật transformer đã biên dịch (warmup + kernel fusion)
`--list-voices`		Liệt kê các giọng dựng sẵn
`--list-prompts`		Liệt kê các preset system prompt
`--transcript`		In văn bản độc thoại nội tâm của mô hình
`--json`		Xuất dạng JSON (bản chép, độ trễ, đường dẫn âm thanh)
`--verbose`		Hiển thị thông tin thời gian chi tiết

Ghi đè lấy mẫu

Tùy chọn	Mặc định	Mô tả
`--audio-temp`	`0.8`	Nhiệt độ lấy mẫu cho âm thanh
`--text-temp`	`0.7`	Nhiệt độ lấy mẫu cho văn bản
`--audio-top-k`	`250`	Top-k ứng viên cho âm thanh
`--repetition-penalty`	`1.2`	Phạt lặp lại cho âm thanh (1.0 = tắt)
`--text-repetition-penalty`	`1.2`	Phạt lặp lại cho văn bản (1.0 = tắt)
`--repetition-window`	`30`	Cửa sổ phạt lặp lại tính bằng frame
`--silence-early-stop`	`15`	Số frame im lặng trước khi dừng sớm (0 = tắt)
`--entropy-threshold`	`0`	Ngưỡng entropy văn bản để dừng sớm (0 = tắt)
`--entropy-window`	`10`	Số bước entropy thấp liên tiếp trước khi dừng sớm

Ví dụ:

# Giọng nói tới giọng nói cơ bản
speech respond --input question.wav

# Dùng giọng nữ với transformer đã biên dịch
speech respond -i question.wav --voice NATF1 --compile

# Stream phản hồi và hiển thị bản chép
speech respond -i question.wav --stream --transcript --verbose

vad

Phát hiện hoạt động giọng nói ngoại tuyến dùng phân đoạn Pyannote.

speech vad <file> [options]

Tùy chọn	Mô tả
`<file>`	Tệp âm thanh cần phân tích
`--model, -m`	ID mô hình HuggingFace
`--onset`	Ngưỡng onset (bắt đầu giọng nói)
`--offset`	Ngưỡng offset (kết thúc giọng nói)
`--min-speech`	Thời lượng giọng nói tối thiểu, tính bằng giây
`--min-silence`	Thời lượng im lặng tối thiểu, tính bằng giây
`--json`	Xuất dạng JSON

vad-stream

Phát hiện hoạt động giọng nói dạng streaming dùng Silero VAD v5. Xử lý giọng nói theo các chunk 32ms.

speech vad-stream <file> [options]

Tùy chọn	Mô tả
`<file>`	Tệp âm thanh cần phân tích
`--engine`	Engine VAD: `mlx` (mặc định) hoặc `coreml`
`--model, -m`	ID mô hình HuggingFace (tự chọn theo engine)
`--onset`	Ngưỡng onset
`--offset`	Ngưỡng offset
`--min-speech`	Thời lượng giọng nói tối thiểu, tính bằng giây
`--min-silence`	Thời lượng im lặng tối thiểu, tính bằng giây
`--json`	Xuất dạng JSON

wake

Phát hiện từ đánh thức / từ khóa trên thiết bị bằng KWS Zipformer (3.49M tham số, CoreML INT8, 26× thời gian thực, chỉ tiếng Anh).

speech wake <file> [options]

Tùy chọn	Mô tả
`<file>`	Tệp âm thanh cần phân tích
`--keywords`	Một hoặc nhiều từ khóa. Định dạng: `"hey soniqo"` (BPE greedy), `"hey soniqo:0.15:0.5"` (kèm ngưỡng/boost), hoặc `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"` (mảnh BPE rõ ràng kiểu sherpa-onnx)
`--keywords-file`	Tệp từ khóa, mỗi mục một dòng (cú pháp giống `--keywords`); dùng `#` cho chú thích
`--model, -m`	ID mô hình HuggingFace. Mặc định là `aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	Xuất dạng JSON

# Cụm từ đơn giản, mặc định đã tinh chỉnh
speech wake recording.wav --keywords "hey soniqo"

# Mảnh BPE rõ ràng cho các cụm mà tokenizer greedy hiểu sai
speech wake recording.wav --keywords "LIGHT UP|▁ L IGHT ▁UP:0.25:2.0"

# Nhiều cụm từ + đầu ra JSON
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

Phân tách người nói — xác định ai nói lúc nào.

speech diarize <file> [options]

Tùy chọn	Mặc định	Mô tả
`<file>`		Tệp âm thanh cần phân tích
`--engine`	`pyannote`	Engine phân tách: `pyannote` (phân đoạn + nối chuỗi người nói) hoặc `sortformer` (end-to-end CoreML)
`--target-speaker`		Âm thanh đăng ký để trích xuất người nói mục tiêu (chỉ pyannote)
`--embedding-engine`	`mlx`	Engine tạo embedding người nói: `mlx` hoặc `coreml` (chỉ pyannote)
`--vad-filter`		Lọc trước bằng Silero VAD (chỉ pyannote)
`--rttm`		Xuất ở định dạng RTTM
`--json`		Xuất dạng JSON
`--score-against`		Tệp RTTM tham chiếu để tính DER

Ví dụ:

# Phân tách cơ bản (pyannote, mặc định)
speech diarize meeting.wav

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

# Xuất RTTM để đánh giá
speech diarize meeting.wav --rttm

# Trích xuất người nói mục tiêu (chỉ pyannote)
speech diarize meeting.wav --target-speaker enrollment.wav

# Chấm điểm so với tham chiếu
speech diarize meeting.wav --score-against reference.rttm

embed-speaker

Trích xuất vector embedding người nói từ âm thanh.

speech embed-speaker <file> [options]

Tùy chọn	Mô tả
`<file>`	Tệp âm thanh chứa giọng người nói
`--engine`	Engine suy luận: `mlx` (mặc định), `coreml` (WeSpeaker 256 chiều) hoặc `camplusplus` (CAM++ CoreML 192 chiều)
`--json`	Xuất dạng JSON

denoise

Loại bỏ tiếng ồn nền bằng DeepFilterNet3 trên Neural Engine.

speech denoise <file> [options]

Tùy chọn	Mặc định	Mô tả
`<file>`		Tệp âm thanh đầu vào
`--output, -o`	`input_clean.wav`	Đường dẫn tệp đầu ra
`--model, -m`		ID mô hình HuggingFace

Ví dụ:

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

compose

Tạo 30 giây nhạc từ một prompt văn bản dùng MAGNeT trên MLX.

speech compose <prompt> [options]

Tùy chọn	Mặc định	Mô tả
`<prompt>`		Prompt văn bản mô tả bản nhạc cần tạo (ví dụ "happy rock")
`--output, -o`	`magnet.wav`	Đường dẫn WAV đầu ra (32 kHz mono)
`--variant`	`small-int4`	Biến thể mô hình: `small-int4`, `small-int8`, `medium-int4` hoặc `medium-int8`. Tương ứng với `aufklarer/MAGNeT-{Small,Medium}-30secs-MLX-{4,8}bit`.
`--temperature`	`3.0`	Nhiệt độ lấy mẫu, giảm tuyến tính theo từng stage.
`--top-p`	`0.9`	Ngưỡng nucleus sampling.
`--cfg-max`	`10.0`	Hệ số classifier-free guidance tối đa.
`--cfg-min`	`1.0`	Hệ số CFG tối thiểu (giảm dần cùng lịch trình mask).
`--steps`	`20,10,10,10`	Số bước giải mã trên mỗi codebook, cách nhau bởi dấu phẩy (4 giá trị).
`--seed`		Seed ngẫu nhiên để đầu ra có thể tái lập.

Ví dụ:

# Mặc định: small-int4, ~10 s trên chip dòng M cho đoạn 30 s
speech compose "happy rock" -o happy_rock.wav

# Mô hình lớn hơn — bám prompt tốt hơn, chậm hơn
speech compose "lo-fi hip hop with mellow piano" --variant medium-int4 -o lofi.wav

# Có thể tái lập
speech compose "energetic EDM with synth lead" --seed 42 -o edm.wav