# Omlx Tts

> 通过本机 oMLX 的 Qwen3-TTS 模型生成可播放的语音回复或朗读音频。当用户说“用语音回答”“读给我听”“说给我听”、要求文字转语音或切换朗读音色时使用。不用于语音识别、声音克隆或实时语音通话。

- Skill: `sukris/omlx-tts` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add sukris/omlx-tts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sukris/omlx-tts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sukris (https://skillmd.com/u/sukris)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sukris/omlx-tts

---


# oMLX 语音回复

使用技能目录中的 `scripts/speak.py` 调用本机 `POST /v1/audio/speech`，返回 WAV。仅需 Python 3 标准库和已运行的 oMLX，不另建服务。

- 默认模型：`Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit`；默认音色：`vivian`。
- 当前已确认音色：`vivian`、`serena`、`uncle_fu`、`dylan`、`eric`、`ryan`、`aiden`、`ono_anna`、`sohee`。可用 `--voice` 切换。
- 从 `${OMLX_BASE_PATH:-~/.omlx}/settings.json` 读取端口和 API 密钥；只向 `127.0.0.1` 发请求。不要展示或复制密钥到命令、产物或日志。
- 用户给出朗读原文时保留原意和内容；要求语音回答问题时先组织适合听的回答，再合成。不要把 Markdown 标记、无关代码或内部执行日志读出来。
- 只有用户要求语音输出，或对当前对话设定持续语音回复偏好时，才生成语音；不擅自把普通文字回复改成音频。

日常语音使用 `--play`，不传 `--output`：音频存入系统临时目录，播放成功后连同该次临时目录自动删除。`<skill-dir>` 指本 SKILL.md 所在目录：

```bash
python3 <skill-dir>/scripts/speak.py \
  --voice vivian --play --text '你好，这是语音回复。'
```

长文本可以通过标准输入传入；若创建临时文本文件，用后删除。用 `--language` 指定语言，默认 `Chinese`。`--model` 仅用于用户选择的其他兼容 TTS 模型，不自动下载或替换模型。

只有用户明确要求保存或下载音频时才传 `--output /absolute/path/to/outputs/语音回复.wav`，使用当前任务允许的交付目录及唯一文件名。显式输出文件不会自动删除，可与 `--play` 同用。

用户要求“读给我听”“说给我听”或语音回答时使用 `--play`，通过 macOS 自带的 `/usr/bin/afplay` 从当前输出设备播放，并等待播放进程结束。用户仅要音频文件或明确要求不播放时省略该选项。不修改系统音量或输出设备。

在沙盒内遇到 `AudioQueueStart failed (-66680)` 时，可能是音频设备访问受限；可通过执行工具的正常权限流程，在沙盒外对已经生成的文件运行 `/usr/bin/afplay /absolute/path/to/audio.wav` 一次。不要重新生成音频或绕过审批。以这次播放进程的退出状态报告结果。若原脚本输出 `temporary: true`，这次播放成功后删除该音频及其所在的本次 `omlx-tts-*` 临时目录；不删除显式保存的文件。最终仍无法播放时保留该临时文件供重试，向用户说明路径和未清理状态，不静默留下文件。

临时语音播放成功并删除后，只给简短文字回复，不嵌入已删除文件的播放器。显式保存的音频才根据绝对路径嵌入 `![语音回复](/absolute/path/to/audio.wav)`。只有收到 `playback_completed: true`（或已确认外部 afplay 成功退出）才能报告播放命令完成，这不能证明用户实际听到了声音。不声称接入实时通话，也不未经试听评价音质。

连接失败时说明 oMLX 服务不可达；模型缺失或加载失败时报告实际错误，不把下载成功当作推理成功。不自动重启服务、修改配置或循环重试。脚本不覆盖已有输出文件。

CustomVoice 使用预设音色，不能借此实现参考录音克隆。自然语言音色设计、克隆及情绪控制不属于此技能已验证能力。