⚠ Translation out of date. See the English CLI reference for Nemotron 3 support.

⚠ 翻译已过期

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

CLI 参考

Breeze TTS 2 · BreezeTTS

英语/中文语音合成，支持声音设计、参考音频克隆与风格控制以及流式音频（MLX BF16/8-bit，24 kHz；仅限研究和非商业用途）.

speech speak "The quick brown fox jumps over the lazy dog." --engine breeze \
  --instruct "A clear, calm English narrator." --stream -o design.wav

--breeze-model-id: aufklarer/Breeze-TTS-2-MLX-8bit
--breeze-bundle-dir
--breeze-cache-limit-mib: 可选的进程级可复用 MLX 缓存上限，单位为 MiB；0 禁用缓存。
--breeze-reference-text
--breeze-temperature: 0.9
--breeze-top-k: 50
--breeze-top-p: 1
--breeze-cfg-scale: 4
--breeze-max-frames: 750
--breeze-seed: 42
--first-chunk-frames: 3
--chunk-frames: 25

Apple 原生运行时 · PocketTTS

PocketTTS 为 speech-swift 添加原生 CoreML 语音合成。所有阶段默认仅使用 CPU。英语 Alba 预设以 24 kHz 流式输出，每帧 1,920 个采样（80 毫秒）。

Swift 与 CLI 用法

speech speak "Hello world." --engine pocket --stream \
  --pocket-bundle-dir /path/to/bundle --pocket-seed 42 -o hello.wav
# --pocket-model-id, --pocket-max-frames, --list-speakers

speech 命令是本地语音处理的入口。

通过 Homebrew 安装

在搭载 Apple Silicon 且运行 macOS 15 或更新版本的 Mac 上，使用 Homebrew 安装 CLI：

brew install speech
speech --help

要更新现有安装，请运行 brew upgrade speech。

另一种方式：从源码构建

在 speech-swift 源码目录中运行 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`, `moss-nano`, `fireredtts3`, `moss-voicegenerator`
`--output, -o`	`output.wav`	输出 WAV 文件路径
`--language`	`english`	语言。若已设 `--speaker`，省略则使用该说话人的原生方言。
`--stream`		启用 streaming 合成
`--voice-sample`		用于语音克隆的参考音频（适用于 `qwen3`、`cosyvoice`、`voxcpm2`, `f5`, `higgs`, `breeze` 和 `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

指令语音合成选项

实验性: 请从 main 源码构建原生 SDK 支持。Homebrew 等预编译 CLI 发行版可能尚未包含这些引擎。

实现 (PR #541): main

已发布的 MLX 模型包: aufklarer/FireRedTTS3-Instruct-MLX-fp32 · aufklarer/MOSS-VoiceGenerator-MLX-bf16

提供一个文本参数、--instruct，以及模型包目录或兼容模型 ID，二者只能选一。不支持参考音频、固定说话人和批量输入。

文本和指令两个字段各限 32,768 个 UTF-8 字节。包含模板的完整输入提示词渲染后不得超过 4,096 个令牌。超过任一限制都会被拒绝。

FireRedTTS3-Instruct 保留 Float32 模型和解码器权重。它返回完整缓冲音频，请勿使用 --stream。--language 接受英语和中文别名。达到生成上限会报错，不会将截断音频视为成功。

MOSS-VoiceGenerator 保留 BF16 语言模型权重和 FP32 合成编解码器。使用 --stream 输出增量 PCM。请省略 --language，将语言要求写入 --instruct。结束前会排空全部十六个码本。

指令遵循质量尚未评分。短文本测量仅描述受测配置；现有模型的延迟回归认证仍无定论。

选项	默认值	说明
`--fireredtts3-bundle-dir`	—	兼容的本地导出模型包；与模型 ID 选项二选一。
`--fireredtts3-model-id`	—	已发布的兼容 MLX 模型包 ID；与本地目录二选一。
`--fireredtts3-flow-steps`	10	每个声学块的流匹配步数。
`--fireredtts3-max-patches`	400	生成上限；未完成便达到上限会报错。
`--moss-voicegenerator-bundle-dir`	—	兼容的本地导出模型包；与模型 ID 选项二选一。
`--moss-voicegenerator-model-id`	—	已发布的兼容 MLX 模型包 ID；与本地目录二选一。
`--moss-voicegenerator-max-frames`	750	生成上限；未完成便达到上限会报错。
`--moss-voicegenerator-chunk-frames`	3	每个 PCM 块的完整编解码帧数（1–32）。
`--seed`	2 / 42	请求种子：FireRedTTS3 默认为 2，MOSS-VoiceGenerator 默认为 42。

FireRedTTS3-Instruct · MOSS-VoiceGenerator

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 输出
`--smart-turn`	在结束片段之前用 Smart Turn 确认每一次停顿；句中停顿会合并为一个片段
`--turn-threshold`	Smart Turn 完成阈值（默认 `0.5`）
`--turn-max-silence`	被否决的停顿之后，无论如何都结束片段的静音秒数（默认 `2.0`）

turn

使用 Smart Turn v3.2（8M 参数，CoreML，23 种语言）进行话轮结束检测。对录音的最后 8 秒打分，打印说话人已说完的概率、完成/未完成的判定以及推理耗时。

speech turn <file> [options]

选项	说明
`<file>`	包含一轮用户话语的音频文件（任意采样率）；使用最后 8 秒
`--threshold`	达到或超过此概率即视为话轮已完成（默认 `0.5`）
`--model, -m`	HuggingFace 模型 ID。默认 `aufklarer/Smart-Turn-v3.2-CoreML`
`--model-dir`	包含 `smart_turn.mlmodelc` 和 `config.json` 的本地目录；跳过下载
`--json`	以 JSON 输出

# Probability, verdict and inference time for one utterance
speech turn utterance.wav

# Custom threshold, JSON output
speech turn utterance.wav --threshold 0.7 --json

# Streaming VAD with Smart Turn confirming each pause
speech vad-stream call.wav --smart-turn --turn-threshold 0.6 --turn-max-silence 1.5

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`	精度 / 包变体
`--compute-units`		两个阶段的 Core ML 分配:ane、gpu、cpu、all(默认:声码器 gpu,预测器自动)

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

Swift 支持 0.6B/256 和 1.7B/1024 模型包，默认仍为 0.6B。实验性 1.7B 模型包默认使用 CPU，并要求通过 --speaker-embedding 提供预先生成的 2048 通道 Float32 .npy 说话人嵌入。GPU/ANE 和 iOS 仍需单独验证。

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

选项	默认值	说明
`--output, -o`	`output.wav`	输出 WAV 文件路径
`--language`	`english`	输出语言
`--model`		Hugging Face 模型 ID
`--model-directory`	—	本地已编译模型包；优先于下载 `--model`。
`--speaker-embedding`	—	与模型维度匹配的 Float32 `.npy` 说话人嵌入（1024 或 2048）。

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

⚠ Translation out of date — the Clef CLI section awaits translation. English reference.

clef

Choose from allowed answers using Clef-flash locally on Apple Silicon. Development preview.

speech clef decide request.json
speech clef decide request.json --model-dir /path/to/Clef-flash-9B-MLX-4bit
speech clef decide request.json --offline --max-tokens 4096

The request contains text in state and an ordered questions array. Each field has an id and a type: choice with a choices map, noul for true/false, or score with ordered levels. Output is JSON with probabilities, selected answers, token count, model-load time, and decision time.

By default, the command downloads aufklarer/Clef-flash-9B-MLX-4bit. Use --model-dir for existing files or --offline for the cache. The token limit defaults to 4096 and accepts 1–16384. See the Clef guide for a complete request and measured memory use.

gliner

使用 GLiNER2.5-Decide (MLX) 按给定标签对文本分类并抽取实体片段。开发预览版：尚未包含在正式发布中。省略文本时从 stdin 读取。

speech gliner classify "<text>" --labels <a,b,c> [options]
speech gliner extract "<text>" --labels <a,b,c> [options]

选项	默认值	说明
`--variant`	int8	要下载的已发布权重：fp32、fp16 或 int8
`--model`		覆盖 Hugging Face 仓库
`--model-dir`		使用本地模型目录，不下载
`--labels`		逗号分隔的候选标签（1 到 255 个，不可重复）
`--description`		标签描述，格式为 label=text；可重复
`--task`	action	写入 schema 提示的任务名（仅 classify）
`--threshold`	0.5	片段最低分数（仅 extract）
`--evaluate-layers`		逐层计算编码器，以降低峰值内存
`--json`		输出 JSON：全部概率或带 UTF-16 偏移的片段，以及耗时

avatar-motion

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

speech avatar-motion <input> [options]

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

MOSS-TTS-Nano

使用 --voice-sample 克隆声音，无需参考音频的转录文本。单声道参考会复制为立体声、重采样至 48 kHz，并补齐至 80 ms 边界。参考音频只需编码一次，后续请求可复用其编码。

speech speak "Hello world." --engine moss-nano -o hello.wav
speech speak "The weather is nice today." --engine moss-nano \
  --voice-sample reference.wav --moss-nano-seed 1 -o cloned.wav
speech speak "Hello world." --engine moss-nano --stream --play -o streamed.wav

`--moss-nano-model`	aufklarer/MOSS-TTS-Nano-100M-CoreML	模型仓库或本地目录
`--moss-nano-compute-units`	cpu	cpu 或 gpu
`--moss-nano-max-frames`	300	最大 80 ms 帧数；必须自然结束
`--moss-nano-seed`	0	可复现的 Swift 采样种子

MOSS-TTS-Nano

Voxtral TTS

Voxtral 4B TTS 2603 通过 VoxtralTTS 模块在 Apple Silicon 上本地运行，提供 20 种预设声音、9 种语言和 24 kHz 单声道语音。

speech speak "Hello, welcome to Voxtral." --engine voxtral --voxtral-voice casual_male --stream --voxtral-chunk-frames 3 -o hello.wav
speech speak --engine voxtral --list-speakers
speech speak "Bonjour." --engine voxtral --voxtral-voice fr_female --voxtral-max-frames 500 --voxtral-seed 0 -o bonjour.wav

仅支持预设音色，不支持参考音频克隆。SDK、CLI、WebSocket 和 HTTP PCM 均可在生成过程中输出音频。输入文本须一次性完整提供。模型权重采用 CC BY-NC 4.0 许可。

阅读 Voxtral TTS 指南

Fish Audio Drama 3

Drama 3 的实验性原生 MLX 支持通过 FishAudioDrama3Model 提供。350 亿参数的混合注意力 MoE 主干、时序音频解码塔和 Fish DAC 编解码器输出 44.1 kHz 单声道音频。4 位检查点已在 Apple M5 Pro 上通过纯文本生成、参考语音克隆和 CLI 输出的波形及独立 ASR 验证。8 位和 BF16 版本尚未验证。

默认内存模式为 balanced。在阶段边界处，若空闲 MLX 缓存超过 512 MiB，则清理缓存；这不是总内存上限。全局分配器限制保持不变。使用 --fish-drama3-memory-mode unrestricted 或 memoryOptions: .unrestricted 可恢复预先加载和原有缓存行为。

纯文本生成会延迟加载 794.4 MiB 的参考音频编码器权重。首次编码参考音频时加载并保留这些权重，因此在此之前请保留 codec.safetensors。预先计算的参考编码无需编码器。

请提供完整文本。语音克隆需要参考录音及其准确转录。支持 0–15 号说话人标签和内联情感控制。可通过 generateStreaming、generateStream 和 --stream 获取 PCM 流式输出。默认每块 3 个编解码帧，约 139 毫秒音频。尚不支持长文本自动分块和流式文本输入。达到帧数上限时会抛出错误。

speech speak "Hello from Drama 3." --engine fish-drama3 --fish-drama3-bundle-dir /path/to/bundle -o hello.wav
speech speak "Hello from Drama 3." --engine fish-drama3 --stream --fish-drama3-chunk-frames 3 -o streamed.wav
speech speak "Hello in the reference voice." --engine fish-drama3 --voice-sample reference.wav --fish-drama3-reference-text "The exact reference transcript." --seed 42 -o cloned.wav

import FishAudioTTS
let model = try await FishAudioDrama3Model.fromBundle(bundleURL, memoryOptions: .balanced)
let pcm = try await model.generate(text: "Hello from Drama 3.", options: .init(seed: 42))

选项	默认值
`--fish-drama3-model-id`	`mlx-community/fish-audio-drama-3-4bit`
`--fish-drama3-bundle-dir`	`—`
`--fish-drama3-reference-text`	`—`
`--fish-drama3-max-frames`	`2048`
`--fish-drama3-temperature`	`1`
`--fish-drama3-top-k`	`30`
`--fish-drama3-top-p`	`0.9`
`--voice-sample`	`—`
`--seed`	`0`
`--stream`	`false`
`--fish-drama3-chunk-frames`	`3`
`--fish-drama3-memory-mode`	`balanced`

基于 Fish Audio 构建。模型包保留社区许可证和 NOTICE。

4 位性能测试