# voice2clip

**Repository Path**: MineLX/voice2clip

## Basic Information

- **Project Name**: voice2clip
- **Description**: bridge for voice-text models
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Voice2Clip — 轻量级常驻内存语音转录服务

按下全局快捷键录音，再按一次即可把语音实时转录成文本并**自动粘贴到当前光标位置**。
完全离线运行、模型常驻内存、全程不落盘，隐私安全。

```
快捷键 → 录音(纯内存 buffer) → SenseVoiceSmall(ONNX) 转录 → xclip 剪贴板 → Ctrl+V
```

## 特性

- **纯内存转录**：麦克风流式写入 `numpy` 缓冲，音频从不写盘，转录后立即释放并 `gc.collect()`。
- **可插拔 ASR**：默认 `SenseVoiceSmall-ONNX`（内存约 0.5GB，CPU 上毫秒级转录），可扩展 Vosk / Faster-Whisper 等。
- **模型常驻**：一次加载，后续调用零加载，响应迅速。
- **常驻服务**：systemd 用户服务，开机自启、崩溃自动重启，空闲 CPU 接近 0。
- **离线优先**：模型与推理均在本地完成，无任何网络依赖。

## 快速开始

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -e .            # 可编辑安装, 生成 voice2clip 命令
pip install -r requirements.txt   # 若不用可编辑安装, 也可走 requirements
bash scripts/download_model.sh      # 下载 model_quant.onnx + tokens.json
voice2clip -c config.yaml run       # 常驻服务(也可 python -m voice2clip ...)
```

> 安装后可直接用 `voice2clip` 命令，等价于 `python -m voice2clip`。
> 默认全局热键为**右 Ctrl**（见 `config.yaml`）。

按右 Ctrl 开始录音，再按一次停止并粘贴结果。

## 目录结构

```
voice2clip/
├── voice2clip/              # 核心包
│   ├── cli.py / __main__.py # 入口(run / transcribe)
│   ├── config.py            # 配置加载
│   ├── service.py           # 常驻服务编排(录音开关→转录→粘贴)
│   ├── recorder.py          # 纯内存麦克风录音
│   ├── clipboard.py         # xclip + xdotool 粘贴
│   ├── hotkey.py            # python-xlib 全局快捷键(X11)
│   └── asr/
│       ├── base.py          # 后端抽象 + 注册表
│       ├── frontend.py      # Kaldi fbank + LFR 特征提取(纯内存)
│       ├── sensevoice.py    # SenseVoiceSmall ONNX 后端
│       ├── vosk.py          # Vosk(小模型, 低内存)可插拔后端
│       └── stub.py          # 无模型联调后端
├── config.yaml              # 配置示例
├── requirements.txt
├── scripts/download_model.sh
├── systemd/voice2clip.service
└── docs/DEPLOYMENT.md       # 完整部署说明
```

## 测试

已验证：模型初始化内存约 `0.4~0.6GB`，纯内存 WAV→特征→ONNX 推理→解码→文本 全链路可用；
`toggle → 录音 → 转录 → 粘贴` 闭环工作正常。

## 部署

详见 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)：虚拟环境、模型放置、systemd 用户服务安装步骤。

## License

MIT