CLI 参考

audio 二进制是所有语音处理任务的主要入口。先用 make build 构建，然后从 .build/release/audio 运行。

transcribe

将音频文件转写为文字。

audio transcribe <file> [options]
选项默认值说明
<file>要转写的音频文件（WAV、M4A、MP3、CAF）
--engineqwen3ASR 引擎：qwen3、qwen3-coreml、parakeet 或 omnilingual
--model, -m0.6B模型变体：0.6B、1.7B 或完整 HuggingFace 模型 ID（仅 qwen3）
--language语言提示（可选，omnilingual 会忽略）
--window10[omnilingual] CoreML 窗口大小（秒）：5 或 10
--backendcoreml[omnilingual] 后端：coreml（Neural Engine）或 mlx（Metal GPU）
--variant300M[omnilingual mlx] 规模：300M、1B、3B 或 7B
--bits4[omnilingual mlx] 量化位宽：4 或 8
--stream启用基于 VAD 的 streaming 转写
--max-segment10最大分段时长（秒，streaming）
--partial在说话过程中输出部分结果（streaming）

示例：

# Basic transcription
audio transcribe recording.wav

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

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

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

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

# Omnilingual (MLX, any length up to 40 s)
audio transcribe recording.wav --engine omnilingual --backend mlx                              # 300M @ 4-bit
audio transcribe recording.wav --engine omnilingual --backend mlx --variant 1B                  # 1B @ 4-bit
audio transcribe recording.wav --engine omnilingual --backend mlx --variant 3B --bits 8         # 3B @ 8-bit
audio transcribe recording.wav --engine omnilingual --backend mlx --variant 7B                  # 7B @ 4-bit

# Streaming with VAD
audio transcribe recording.wav --stream --partial

align

词级强制对齐——获取每个词的精确时间戳。

audio align <file> [options]
选项默认值说明
<file>音频文件
--text, -t要对齐的文本（省略则先执行转写）
--model, -m0.6B用于转写的 ASR 模型：0.6B、1.7B 或完整 ID
--aligner-model强制对齐器模型 ID
--language语言提示

示例：

# Auto-transcribe then align
audio align recording.wav

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

speak

文本转语音合成。

audio speak "<text>" [options]
选项默认值说明
<text>要合成的文本（使用 --batch-file 时可选）
--engineqwen3TTS 引擎：qwen3 或 cosyvoice
--output, -ooutput.wav输出 WAV 文件路径
--languageenglish语言。若已设 --speaker，省略则使用该说话人的原生方言。
--stream启用 streaming 合成
--voice-sample用于声音克隆的参考音频（qwen3 和 cosyvoice 引擎均支持）
--verbose显示详细耗时信息

Qwen3-TTS 选项

选项默认值说明
--modelbase模型变体：base、customVoice 或完整 HF 模型 ID
--speaker说话人音色（需 --model customVoice）
--instruct风格指令（CustomVoice 模型）
--list-speakers列出可用说话人并退出
--temperature0.3采样温度
--top-k50Top-k 采样
--max-tokens500最大 token 数（500 ≈ 40 秒音频）
--batch-file每行一条文本的批处理输入文件
--batch-size4并行生成的最大 batch 大小
--first-chunk-frames3流式首个 chunk 的 codec 帧数
--chunk-frames25每个流式 chunk 的 codec 帧数

CosyVoice3 选项

选项默认值说明
--speakers多说话人对话的说话人映射：s1=alice.wav,s2=bob.wav
--cosy-instruct风格指令（覆盖默认值）。控制 CosyVoice3 的语音风格。
--turn-gap0.2对话轮次之间的静默间隔（秒）
--crossfade0.0轮次之间的交叉淡化重叠（秒）
--model-idHuggingFace 模型 ID

示例：

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

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

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

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

# Multi-speaker dialogue
audio 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
audio speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

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

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

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

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

kokoro

使用 Kokoro-82M 在 Neural Engine（CoreML）上的轻量级文本转语音。非自回归——单次前向传播，延迟约 45ms。

audio kokoro "<text>" [options]
选项默认值说明
<text>要合成的文本
--voiceaf_heart音色预设（10 种语言共 50 种）
--languageen语言代码：en、es、fr、hi、it、ja、pt、zh、ko、de
--output, -okokoro_output.wav输出 WAV 文件路径
--list-voices列出所有可用音色并退出
--model, -mHuggingFace 模型 ID

示例：

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

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

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

respond

基于 PersonaPlex 7B 的 full-duplex 语音到语音对话。

audio respond [options]
选项默认值说明
--input, -i输入 WAV 音频文件（24kHz 单声道）（必填）
--output, -oresponse.wav输出响应 WAV 文件
--voiceNATM0音色预设（例如 NATM0、NATF1、VARF0）
--system-promptassistant预设：assistant、focused、customer-service、teacher
--system-prompt-text自定义系统提示词（覆盖预设）
--max-steps20012.5Hz 下的最大生成步数（约 16 秒）
--stream在生成过程中输出音频 chunks
--compile启用编译后的 transformer（预热 + kernel 融合）
--list-voices列出可用音色预设
--list-prompts列出可用系统提示词预设
--transcript打印模型的内心独白文本
--json以 JSON 输出（转录文本、延迟、音频路径）
--verbose显示详细耗时信息

采样覆盖

选项默认值说明
--audio-temp0.8音频采样温度
--text-temp0.7文本采样温度
--audio-top-k250音频 top-k 候选数
--repetition-penalty1.2音频重复惩罚（1.0 = 禁用）
--text-repetition-penalty1.2文本重复惩罚（1.0 = 禁用）
--repetition-window30重复惩罚窗口（帧数）
--silence-early-stop15提前停止前的静默帧数（0 = 禁用）
--entropy-threshold0用于提前停止的文本熵阈值（0 = 禁用）
--entropy-window10提前停止前连续低熵步数

示例：

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

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

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

vad

使用 Pyannote 分段的离线语音活动检测。

audio vad <file> [options]
选项说明
<file>要分析的音频文件
--model, -mHuggingFace 模型 ID
--onset起始阈值（语音开始）
--offset结束阈值（语音结束）
--min-speech最小语音时长（秒）
--min-silence最小静默时长（秒）
--json以 JSON 输出

vad-stream

使用 Silero VAD v5 的 streaming 语音活动检测。以 32ms chunks 处理音频。

audio vad-stream <file> [options]
选项说明
<file>要分析的音频文件
--engineVAD 引擎：mlx（默认）或 coreml
--model, -mHuggingFace 模型 ID（由引擎自动选择）
--onset起始阈值
--offset结束阈值
--min-speech最小语音时长（秒）
--min-silence最小静默时长（秒）
--json以 JSON 输出

diarize

说话人分离——识别谁在什么时间说话。

audio diarize <file> [options]
选项默认值说明
<file>要分析的音频文件
--enginepyannote说话人分离引擎：pyannote（分段 + 说话人串联）或 sortformer（端到端 CoreML）
--target-speaker用于目标说话人提取的注册音频（仅 pyannote）
--embedding-enginemlx说话人 embedding 引擎：mlx 或 coreml（仅 pyannote）
--vad-filter用 Silero VAD 预过滤（仅 pyannote）
--rttm以 RTTM 格式输出
--json以 JSON 输出
--score-against用于计算 DER 的参考 RTTM 文件

示例：

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

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

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

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

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

embed-speaker

从音频中提取说话人 embedding 向量。

audio embed-speaker <file> [options]
选项说明
<file>包含说话人声音的音频文件
--engine推理引擎：mlx（默认）、coreml（WeSpeaker 256 维）或 camplusplus（CAM++ CoreML 192 维）
--json以 JSON 输出

denoise

使用 Neural Engine 上的 DeepFilterNet3 去除背景噪声。

audio denoise <file> [options]
选项默认值说明
<file>输入音频文件
--output, -oinput_clean.wav输出文件路径
--model, -mHuggingFace 模型 ID

示例：

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