⚠ 翻译已过期

VoiceChat 工具调用和性能说明正在更新。最新信息请参阅英文版。

CLI 参考

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

transcribe

将音频文件转写为文字。

speech transcribe <file> [options]

选项	默认值	说明
`<file>`		要转写的音频文件（WAV、M4A、MP3、CAF）
`--engine`	`qwen3`	ASR 引擎：`qwen3`, `qwen3-coreml`, `parakeet`, `nemotron`, `omnilingual`, `cohere`, `voxtral`, `moss`, `whisper`
`--model, -m`	`0.6B`	模型变体：`0.6B`、`1.7B` 或完整 HuggingFace 模型 ID（仅 qwen3） `[whisper]`: `default`, `turbo`, or full CoreML HuggingFace repo ID. `[cohere/voxtral]`: INT5（默认）、INT8、FP16、Hugging Face 模型 ID 或本地目录. `[moss coreml]`：`int8`（默认）或 `fp16`；`[moss mlx]`：`int5`（默认）或 `int8`。也可使用兼容的 Hugging Face 仓库 ID 或本地目录。
`--max-tokens`	CoreML: `512` MLX: `5120`	`[moss]` 生成的最大转写 token 数。
`--kv-cache`	`fp16`	`[moss mlx]` 动态 KV 缓存精度：`fp16` 或 `int8`。
`--language`		语言提示（可选，omnilingual 会忽略）
`--window`	`10`	`[omnilingual]` CoreML 窗口大小（秒）：`5` 或 `10`
`--backend`	`coreml`	`[omnilingual]` 后端：`coreml`（Neural Engine）或 `mlx`（Metal GPU） `[moss]` CoreML 使用固定的 1,024-token 状态；MLX 提供动态 131,072-token 上下文。
`--variant`	`300M`	`[omnilingual mlx]` 规模：`300M`、`1B`、`3B` 或 `7B`
`--bits`	`4`	`[omnilingual mlx]` 量化位宽：`4` 或 `8`
`--stream`		启用基于 VAD 的 streaming 转写
`--max-segment`	`10`	最大分段时长（秒，streaming）
`--partial`		在说话过程中输出部分结果（streaming）

示例：

# 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

# Cohere Transcribe 2B (MLX，默认 INT5)
speech transcribe recording.wav --engine cohere
speech transcribe recording.wav --engine cohere --model int8 --language de

# Voxtral Mini 3B (MLX，默认 INT5)
speech transcribe recording.wav --engine voxtral
speech transcribe recording.wav --engine voxtral --model int8 --language fr

# MOSS Transcribe Diarize（CoreML 短音频）
speech transcribe recording.wav --engine moss
speech transcribe recording.wav --engine moss --model fp16

# MOSS Transcribe Diarize（MLX 128K 离线上下文；默认 INT5）
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 with VAD
speech transcribe recording.wav --stream --partial

align

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

speech align <file> [options]

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

示例：

# 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

文本转语音合成。

speech speak "<text>" [options]

选项	默认值	说明
`<text>`		要合成的文本（使用 `--batch-file` 时可选）
`--engine`	`qwen3`	TTS 引擎：`qwen3`、`cosyvoice`、`voxcpm2`、`indextts2`、`indic-mio`、`magpie` 或 `magpie-coreml`
`--output, -o`	`output.wav`	输出 WAV 文件路径
`--language`	`english`	语言。若已设 `--speaker`，省略则使用该说话人的原生方言。
`--stream`		启用 streaming 合成
`--voice-sample`		用于语音克隆的参考音频（适用于 `qwen3`、`cosyvoice`、`voxcpm2`, `f5`, `higgs` 和 `indextts2`）
`--verbose`		显示详细耗时信息

Qwen3-TTS 选项

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

CosyVoice3 选项

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

IndexTTS2 选项

IndexTTS2 是基于扩展 MLX bundle 的零样本语音克隆引擎。它需要 --voice-sample，目前仅支持批量合成。

选项	默认值	说明
`--indextts2-model-id`	`aufklarer/IndexTTS2-MLX-fp16`	HuggingFace 模型 ID。默认值为 `aufklarer/IndexTTS2-MLX-fp16`。
`--indextts2-bundle-dir`		加载本地扩展 bundle，而不是从 Hugging Face 下载。
`--indextts2-emotion-audio`		可选情绪/风格参考音频。默认使用说话人参考。
`--indextts2-emotion`		可选 preset 或 8 值情绪向量。Preset 包括 `eager`、`happy`、`excited` 和 `calm`。
`--indextts2-emotion-weight`	`1.0`	缩放 `--indextts2-emotion`；若重视说话人身份，请保持适中。
`--indextts2-speaking-rate`	`1.0`	语速倍率 `0.5` 到 `1.5`；大于 `1.0` 更快。
`--indextts2-max-pause`		可选的长内部低能量停顿上限，单位为秒。
`--indextts2-s2mel-steps`	`15`	S2Mel 流匹配步数(默认 15,经听感验证;25 与上游完全一致)

F5-TTS 选项

选项	默认值	说明
`--f5-reference-text`		参考文字稿:--voice-sample 的文本内容(必填)
`--f5-steps`	`16`	流匹配步数(默认 16;32 为最高保真)
`--f5-cfg-strength`	`2.0`	无分类器引导强度
`--f5-sway`	`-1.0`	Sway 采样系数
`--f5-speed`	`1.0`	语速倍率
`--f5-seed`	`0`	随机种子,保证结果可复现
`--f5-target-rms`	`0.1`	参考音频 RMS 归一化目标
`--f5-model-id`		Hugging Face 模型 ID
`--f5-bundle-dir`		从本地目录加载模型包

Higgs TTS 3 选项

选项	默认值	说明
`--higgs-ref-text`		参考文字稿:--voice-sample 的文本内容(可提升克隆质量)
`--higgs-temperature`	`0.8`	采样温度(默认 0.8)
`--higgs-top-p`		核采样阈值(默认关闭)
`--higgs-top-k`		Top-k 采样截断(默认关闭)
`--higgs-max-new-tokens`	`2048`	最大生成音频帧数(每秒 25 帧)
`--higgs-seed`	`0`	随机种子,保证结果可复现
`--higgs-model-id`		Hugging Face 模型 ID
`--higgs-bundle-dir`		从本地目录加载模型包

示例：

# 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

# Voice cloning (IndexTTS2)
speech speak "Hello in your voice" --engine indextts2 \
    --voice-sample reference.wav --indextts2-speaking-rate 1.35 \
    --indextts2-max-pause 0.05 -o indextts2.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

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

speech kokoro "<text>" [options]

选项	默认值	说明
`<text>`		要合成的文本
`--voice`	`af_heart`	音色预设（10 种语言共 50 种）
`--language`	`en`	语言代码：en、es、fr、hi、it、ja、pt、zh、ko、de
`--output, -o`	`kokoro_output.wav`	输出 WAV 文件路径
`--list-voices`		列出所有可用音色并退出
`--model, -m`		HuggingFace 模型 ID

示例：

# 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

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

speech respond [options]

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

采样覆盖

选项	默认值	说明
`--audio-temp`	`0.8`	音频采样温度
`--text-temp`	`0.7`	文本采样温度
`--audio-top-k`	`250`	音频 top-k 候选数
`--repetition-penalty`	`1.2`	音频重复惩罚（1.0 = 禁用）
`--text-repetition-penalty`	`1.2`	文本重复惩罚（1.0 = 禁用）
`--repetition-window`	`30`	重复惩罚窗口（帧数）
`--silence-early-stop`	`15`	提前停止前的静默帧数（0 = 禁用）
`--entropy-threshold`	`0`	用于提前停止的文本熵阈值（0 = 禁用）
`--entropy-window`	`10`	提前停止前连续低熵步数

示例：

# 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

voice-chat

与 Soniqo 进行实时全双工对话，由 NVIDIA Nemotron VoiceChat 11B 驱动。默认的 protected-head INT5 bundle 会在首次使用时下载；麦克风模式提供 Apple AEC、流式 RNN-T 字幕、直观的实时指标、自适应 8→2→1 步语音细化，以及有界输入重新同步，避免长时间静默追赶。

speech voice-chat [options]

选项	默认值	说明
`--model, -m`	`aufklarer/VoiceChat-11B-Perception-MLX-int5`	Hugging Face 模型 ID 或完整本地 bundle。
`--revision`	`main`	Hub revision。
`--system-prompt`		覆盖 system prompt。
`--mcp-config`		MCP 工具服务器的通用 JSON 配置。
`--mcp-server`	全部已配置服务器	选择一个服务器；可重复指定。
`--mcp-write-policy`	`allow`	写入策略：立即执行的 `allow`、模型确认的 `confirm` 或 `deny`。
`--mcp-timeout-seconds`	`15`	MCP 工具调用超时；服务器启动至少允许 60 秒。
`--greet`		让模型先问候。
`--no-aec`		禁用 Apple 声学回声消除。
`--no-transcript`		禁用实时 RNN-T 用户字幕。
`--no-rnnt-turn-taking`		禁用 NVIDIA RNN-T 轮次控制安全兜底。
`--prebuffer-frames`	`3`	播放前缓冲的 80 ms 输出帧数。
`--max-buffered-frames`	`8`	丢弃过时音频前最多排队的 80 ms 麦克风帧数。
`--max-seconds`		在指定秒数后停止实时采集。
`--input`		读取音频文件而非麦克风。
`--output, -o`		写入完整上下文的 22.05 kHz WAV。
`--tail-seconds`	`6`	文件输入后追加的静音时长。
`--force-turn-at-end`		在文件末尾强制 BOS；仅限回归测试。
`--plain`		使用仅追加输出，而不是固定重绘的终端面板。
`--debug-timeline`		显示短语与生成发音结束的相对时间戳，以及模型解码的工具调用生命周期事件。
`--terminal-width`	`120`	终端显示宽度。
`--temperature`	`0`	文本温度；0 表示 greedy。
`--text-top-p`	`1`	文本 top-p。
`--guidance`	`0.2`	EAR-TTS guidance 强度。
`--speech-top-p`	`0.95`	EAR-TTS top-p。
`--speech-noise`	`0.001`	EAR-TTS sampling noise。
`--speech-iterations`	`8`	每帧 EAR-TTS MaskGIT 迭代次数。
`--realtime-speech-iterations`	`2`	为保护实时速度而临时使用的语音细化步数。
`--live-speech-context-seconds`	`20`	实时模式保留的近期 EAR-TTS 历史；0 表示保留全部历史。

示例:

speech voice-chat

speech voice-chat --model /path/to/complete-bundle --prebuffer-frames 3

speech voice-chat --input question.wav --output response.wav

speech voice-chat --mcp-config Examples/VoiceChatMCP/apple-reminders.json

文件模式是不依赖音频硬件的可复现路径。--force-turn-at-end 仅用于受控回归测试，不得作为自然轮次切换延迟报告。

Apple Reminders 演示只启用 list_reminders、create_reminder 和 update_reminder；列表发现由适配器私下完成。一次扁平化读取覆盖所有列表，更新时只使用用户说出的名称并在运行时解析私有 ID。面板会将函数解码耗时、token 步数和 token/s 与音频 RTF 分开显示。

audio-translate

基于 Kyutai Hibiki Zero-3B 的流式语音到语音翻译。FR / ES / PT / DE → EN,单一二进制,无需云端。完整指南 →

speech audio-translate <input.wav> [options]

选项	默认值	说明
`<input>`		源音频 WAV 文件(单声道,内部重采样到 24 kHz)(必填)
`--output, -o`	`translated.wav`	输出 24 kHz 英语 WAV 文件
`--source-lang`	`fr`	源语言提示(`fr`、`es`、`pt`、`de`)。自动检测,仅作元数据。FR 与 ES 为严格端到端金丝雀;PT 与 DE 为尽力支持。
`--quantization`	`4bit`	变体:`4bit`(约 2.7 GB)或 `8bit`(约 3.9 GB)
`--model-id`		覆盖 HuggingFace 模型 ID(优先于 `--quantization`)
`--compile`		翻译前先运行时序 Transformer 预热
`--verbose`		打印各阶段耗时(Mimi 编码、生成、Mimi 解码)
`--transcript`		打印模型内心独白的原始 SPM token ID(SPM 解码接入为后续工作)

环境变量

变量	作用
`HIBIKI_GREEDY=1`	文本与目标音频均强制 argmax 解码。结果可复现 — 严格 CI 金丝雀使用此模式。
`HIBIKI_MODEL_ID`	运行时覆盖默认的 `aufklarer/Hibiki-Zero-3B-MLX-4bit` 仓库。

示例:

# Translate a French clip to English
speech audio-translate input_fr.wav -o out_en.wav --source-lang fr

# Spanish, 8-bit, verbose
speech audio-translate input_es.wav -o out.wav --source-lang es --quantization 8bit --verbose

# Deterministic mode (matches the CI regression canaries)
HIBIKI_GREEDY=1 speech audio-translate input_fr.wav -o out.wav --source-lang fr

vad

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

speech vad <file> [options]

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

vad-stream

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

speech vad-stream <file> [options]

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

wake

使用 KWS Zipformer 进行设备端关键词识别（3.49M 参数，CoreML INT8，26× 实时，仅支持英语）。

speech wake <file> [options]

选项	说明
`<file>`	要分析的音频文件
`--keywords`	一个或多个关键词。格式：`"hey soniqo"`、`"hey soniqo:0.15:0.5"` 或 `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"`（sherpa-onnx 风格的显式 BPE 片段）
`--keywords-file`	关键词文件，每行一个条目
`--model, -m`	HuggingFace 模型 ID。默认：`aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	以 JSON 输出

diarize

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

speech diarize <file> [options]

选项	默认值	说明
`<file>`		要分析的音频文件
`--engine`	`pyannote`	说话人分离引擎：`pyannote`、`community1`（CoreML + 原生 PLDA/VBx）或 `sortformer`
`--community1-compute-units`	`ane`	Community-1 CoreML 计算单元：`ane`、`cpu`、`gpu` 或 `all`
`--num-speakers`		Community-1 的已知准确说话人数
`--min-speakers`	`1`	Community-1 的最小说话人数
`--max-speakers`		Community-1 的最大说话人数
`--target-speaker`		用于目标说话人提取的注册音频（仅 pyannote）
`--embedding-engine`	`mlx`	说话人 embedding 引擎：`mlx` 或 `coreml`（仅 pyannote）
`--vad-filter`		用 Silero VAD 预过滤（仅 pyannote）
`--rttm`		以 RTTM 格式输出
`--json`		以 JSON 输出
`--score-against`		用于计算 DER 的参考 RTTM 文件

示例：

# 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

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

speech embed-speaker <file> [options]

选项	说明
`<file>`	包含说话人声音的音频文件
`--engine`	`mlx`（默认）或 `coreml` 用于 WeSpeaker 256 维；`redimnet2` 用于持久身份 CoreML 192 维；`camplusplus` 用于 CAM++ CoreML 192 维
`--json`	以 JSON 输出

language-id

识别音频文件中的口语语言。

speech language-id <file> [options]

选项	说明
`<file>`	要分类的音频文件
`--engine`	推理引擎：mlx 或 coreml
`--model`	覆盖 Hugging Face 模型 ID
`--top`	返回的语言候选数量
`--json`	以 JSON 输出结果

speech language-id recording.wav --top 5
speech language-id recording.wav --engine coreml --json

denoise

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

speech denoise <file> [options]

选项	默认值	说明
`<file>`		输入音频文件
`--output, -o`	`input_clean.wav`	输出文件路径
`--model, -m`		HuggingFace 模型 ID

示例：

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

transcribe-batch

批量转写整个音频目录;模型只加载一次。

speech transcribe-batch <input-dir> [options]

选项	默认值	说明
`<input-dir>`		待转写音频文件目录(WAV、FLAC 等)
`--output-dir`		转写结果输出目录
`--engine`	`qwen3`	ASR 引擎(取值与 transcribe 相同)
`--jsonl`		以 JSON lines 输出结果,每个文件一行

restore

用 Sidon 修复语音(降噪 + 去混响)— CoreML,48 kHz 输出。

speech restore <audio-file> [options]

选项	默认值	说明
`--output, -o`	`input_restored.wav`	输出 WAV 文件路径(48 kHz)
`--variant`	`fp16`	精度 / 包变体

separate

将音乐分离为声部(vocals、drums、bass、other)。

speech separate <input> [options]

选项	默认值	说明
`--stems`	`vocals,drums,bass,other`	要提取的声部:vocals、drums、bass、other
`--engine`	`umx`	引擎:umx(默认)或 htdemucs(质量更高)
`--output-dir`		转写结果输出目录

upsample

用 FlashSR 做音频超分辨率 — 一步蒸馏 AudioSR,48 kHz 输出。

speech upsample <audio-file> [options]

选项	默认值	说明
`--output, -o`	`hr.wav`	输出 WAV 文件路径(48 kHz)
`--variant`	`int4`	精度 / 包变体
`--seed`		随机种子,保证结果可复现

qwen3-tts-coreml

用 CoreML 上的 Qwen3-TTS 做文本转语音(神经引擎)。

speech qwen3-tts-coreml "<text>" [options]

选项	默认值	说明
`--output, -o`	`output.wav`	输出 WAV 文件路径
`--language`	`english`	输出语言
`--model`		Hugging Face 模型 ID

vibevoice

用 Microsoft VibeVoice 做文本转语音(MLX)。

speech vibevoice "<text>" --voice-cache <cache> [options]

选项	默认值	说明
`--voice-cache, -v`		来自 vibevoice-encode-voice 的声音缓存(必填)
`--steps`		DPM-Solver 推理步数(越高质量越好)
`--cfg`	`1.3`	无分类器引导强度
`--long-form`		长文本的分块长篇合成

vibevoice-encode-voice

用参考录音加文字稿生成 VibeVoice 声音缓存。

speech vibevoice-encode-voice <input> "<transcript>" [options]

选项	默认值	说明
`<input>`		参考音频文件
`<transcript>`		参考音频的文字稿(仅英文)
`--output, -o`		输出声音缓存(.safetensors)

translate

用 MADLAD-400 将文本翻译为目标语言(MLX)。

speech translate "<text>" --to <lang> [options]

选项	默认值	说明
`--to, -t`		目标语言代码(ISO 639-1,如 es、zh、ja)
`--stream`		边解码边流式输出
`--model`		Hugging Face 模型 ID

avatar-motion

从语音音频生成 NVIDIA Audio2Face-3D 数字人动作系数帧。

speech avatar-motion <input> [options]

选项	默认值	说明
`--output, -o`	`avatar-motion.jsonl`	输出 JSONL 文件路径
`--model`	`…James-MLX`	数字人身份包(默认 James;另有 Claire 与 Mark)
`--verbose`		打印耗时与帧数