# iVox

[![npm](https://img.shields.io/npm/v/@xdfnet/ivox)](https://npm.im/@xdfnet/ivox)
[![npm](https://img.shields.io/npm/dt/@xdfnet/ivox)](https://npm.im/@xdfnet/ivox)
[![macOS](https://img.shields.io/badge/platform-macOS%20Apple%20Silicon-333)](https://github.com/xdfnet/iVox)
[![License](https://img.shields.io/npm/l/@xdfnet/ivox)](LICENSE)

让 AI CLI 说话。iVox 是 macOS 本地语音播报守护进程，常驻后台、本地模型、零网络依赖。

当你用 Claude Code、Codex 或 Pi 写代码时，Agent 停下来等你确认？iVox 会在它完成时播报，让你不用盯着屏幕等。去倒杯咖啡，听到声音再回来。

## 为什么是 iVox

- **100% 本地** — Qwen3-TTS 模型本地推理，不传任何数据到云端
- **一条命令** — `npm i -g @xdfnet/ivox && ivox setup`，五分钟内搞定
- **无缝接入** — 自动检测 Claude Code / Codex / Pi，一键接入 Stop hook
- **极低延迟** — daemon 常驻 + 模型预热，播报首包不到 200ms
- **多音色** — 内置 4 个中文音色，支持火山引擎自定义音色克隆

## 安装

```bash
npm i -g @xdfnet/ivox
ivox setup
```

`setup` 会自动完成：Python 环境、模型下载（~1.2GB）、配置生成、Hook 接入、服务注册。

要求：macOS Apple Silicon，Python 3.10+，磁盘空间 ~3GB。

## 使用

```bash
ivox                    # 查看服务状态
ivox speak "你好"       # 播报
ivox speak -s codex "用 Codex 音色"
ivox logs               # 查看日志
ivox restart            # 重启服务
ivox update             # 升级到最新版
```

## 音色

```bash
ivox voice list         # 列出音色
ivox voice clone ...    # 从火山引擎导入
```

内置音色：米仔（默认）、甜妹桃子、大易、湾湾小何。

## 目录结构

```
~/.config/ivox/
├── config.json          # 配置
├── ivox.log             # 运行日志
├── models/              # Qwen3-TTS 本地模型
├── py/                  # Python worker + venv
└── voices/              # 参考音频
```

## License

[MIT](LICENSE) © 2026 xdfnet
