Skip to content

new985211/CapsWriter-Offline

BranchesTags
 
 

Repository files navigation

CapsWriter Offline v2.6 — Linux 离线语音转文字

国内用户可以看gitee仓库

CapsWriter Offline 是一个客户端-服务端架构的离线语音识别工具。支持麦克风实时录入和音视频文件转录，无需网络。

┌──────────────┐    WebSocket     ┌──────────────┐
│  Client      │ ◄──────────────► │  Server      │
│  (录音/快捷键) │   AudioMessage   │  (ASR 推理)   │
│  Python 3.11 │   RecognitionMsg │  Python 3.11 │
└──────────────┘                  └──────────────┘
  • 服务端: 纯 CPU ONNX/GGUF 推理，支持 4 种 ASR 引擎
  • 客户端: 麦克风录音、快捷键监听、文件转录、热词替换、LLM 后处理
  • 通信: WebSocket + JSON，音频为 base64 float32 16kHz mono PCM

架构支持

架构 平台 状态
x86_64 (amd64) Intel/AMD Linux ✅ 完整支持
aarch64 (arm64) 飞腾/鲲鹏/树莓派 Linux ✅ 完整支持

setup.sh 通过 uname -m 自动识别 CPU 架构，选择对应的离线安装包。

快速开始

环境要求

  • 操作系统: Ubuntu 20.04+ / Kylin V10 / Debian 11+
  • Python: 3.11（项目自带离线安装包，无需预装）
  • RAM: 4GB+（SenseVoice 约需 2GB）
  • 磁盘: 1GB+（SenseVoice 模型 452MB + Python 环境约 600MB）
  • 系统依赖: ffmpeg、portaudio、libsndfile（setup.sh 自动安装）

一键部署

cd CapsWriter-Offline-v2.6

# x86_64 在线部署
bash setup.sh

# ARM64 / x86_64 完全离线部署（所有安装包已就绪）
bash setup.sh --offline --bootstrap

# 跳过系统级依赖（如已有 root 权限安装过）
bash setup.sh --offline --bootstrap --skip-system

setup.sh 自动执行 7 步：检查 Python → 安装系统依赖 → 创建虚拟环境 → 安装 Python 包 → 验证关键模块 → 验证模型文件 → 准备启动脚本。

启动

bash start_server.sh    # 终端 1 — 启动 ASR 服务端
bash start_client.sh    # 终端 2 — 启动客户端（麦克风模式）

文件转录

将音视频文件转为 SRT 字幕和 TXT 文本，支持批量处理。

# 转录单个文件
bash start_client.sh demo.mp3

# 批量转录
bash start_client.sh file1.mp3 file2.wav file3.flac

输出文件

文件 内容 默认
<文件名>.srt SRT 字幕，时间轴精确到句 ✅
<文件名>.txt 按标点分行的纯文本 ✅
<文件名>.json 字级时间戳 ✅
<文件名>.merge.txt 未切分的整段文本 ❌

支持格式: mp3, wav, mp4, mkv, flv, avi, mov 等（需 ffmpeg）。

手动修正字幕

  1. 编辑生成的 .txt 文件（改错字、调分行）
  2. 将修改后的 .txt 拖拽到客户端（或作为参数传入）
  3. 客户端会利用 .json 中的字级时间戳与修改后的文本重新对齐，生成新的 .srt

ASR 引擎选择

编辑 config_server.py 切换引擎:

class ServerConfig:
    model_type = 'sensevoice'    # 可选: 'sensevoice', 'fun_asr_nano', 'qwen_asr', 'paraformer'

引擎对比

引擎 model_type 准确率 CPU 速度 内存 自带标点 模型大小
Qwen3-ASR 1.7B qwen_asr ★★★★★ ~4× ~4GB ✅ ~2.7GB
Fun-ASR-Nano fun_asr_nano ★★★★☆ ~3× ~3GB ✅ ~1.5GB
SenseVoice Small sensevoice ★★★☆☆ 基线 ~2GB ✅ 452MB
Paraformer paraformer ★★★☆☆ ~1× ~1.5GB ❌ ~1.0GB

推荐: 默认 sensevoice 可用即用，追求准确率用 qwen_asr，平衡用 fun_asr_nano。

下载模型

模型发布页: https://github.com/HaujetZhao/CapsWriter-Offline/releases/tag/models

下载后放入 models/<引擎名>/ 目录，修改 config_server.py 的 model_type 后重启服务端。

现有模型状态:

模型 当前状态
SenseVoice Small ⚠️ 需下载
Qwen3-ASR 1.7B ⚠️ 需下载
Fun-ASR-Nano ⚠️ 需下载
ForceAligner ⚠️ 需下载（Qwen3-ASR 生成精确时间戳时需要）

客户端配置要点

编辑 config_client.py:

# 快捷键
shortcuts = [
    {'key': 'f7',  'type': 'keyboard', 'suppress': True, 'hold_mode': True,  'enabled': True},   # 按住说话
    {'key': 'f8',  'type': 'keyboard', 'suppress': True, 'hold_mode': False, 'enabled': True},   # 切换模式
]

# 文件转录
file_seg_duration = 60       # 分段长度（秒），越大内存占用越高
file_seg_overlap = 4         # 分段重叠（秒），避免切分点丢字
file_save_srt = True         # 生成 SRT 字幕
file_save_txt = True         # 生成 TXT 文本
file_save_json = True        # 生成 JSON 时间戳

# 通用
language = 'auto'            # 识别语言: 'auto' / 'chinese' / 'english'
paste = True                 # 粘贴模式（推荐开启）
enable_tray = False          # Linux 关闭托盘图标

Linux 下快捷键: 支持 F7（按住说话）/ F8（单击切换）。鼠标侧键在 ARM64 平台可能不可用，默认禁用。 Wayland 用户: pynput 需要 X11 环境。请切换到 Xorg 会话登录，或在 config_client.py 中禁用键盘快捷键监听。

项目结构

CapsWriter-Offline-v2.6/
├── config_client.py              # 客户端配置
├── config_server.py              # 服务端配置（引擎选择）
├── setup.sh                      # ★ 多架构一键部署脚本
├── start_server.sh / start_client.sh
├── hot.txt / hot-rule.txt        # 客户端热词（音素 RAG + 正则）
├── hot-server.txt                # 服务端热词
│
├── deps/ / deps-arm64/           # Python wheel 离线源
├── sysdeps/ / sysdeps-arm64/     # 系统 .deb 离线包
├── cpython-*-x86_64*.tar.gz      # x86_64 Python 运行时（离线引导用）
├── cpython-*-aarch64*.tar.gz     # ARM64 Python 运行时（离线引导用）
├── uv-*.tar.gz                   # uv 包管理器（离线引导用）
│
├── models/                       # ASR 模型文件
│   ├── SenseVoice-Small/         # 452MB — 默认引擎
│   ├── Fun-ASR-Nano/             # 模型下载链接 →
│   ├── Qwen3-ASR/                # 模型下载链接 →
│   └── ...
│
├── core/                         # 源码
├── LLM/                          # LLM 角色配置
└── docs/                         # 文档

常见问题

部署相关

Q: bash setup.sh 报 "虚拟环境不存在" 或 Python 模块找不到？

# 重新运行完整部署
bash setup.sh --offline --bootstrap

Q: ModuleNotFoundError: No module named 'typer' / 'rich' / 'srt'？

Python 依赖安装不完整。运行以下命令补装:

source .venv/bin/activate
pip install -r requirements.txt

或离线安装:

source .venv/bin/activate
pip install --no-index --find-links=deps/ -r requirements.txt

Q: runtime/python/bin/python3.11 报 "可执行文件格式错误"？

runtime/ 中的 Python 是 arm64 架构，无法在 x86_64 上运行:

rm -rf runtime/
bash setup.sh --bootstrap   # 从正确的 cpython 归档重新解压

转录准确率

Q: 转录准确率很差（尤其是歌曲/音乐）？

可能原因及解决方案:

  1. 模型太小: 默认 SenseVoice Small 对复杂音频效果有限，考虑切换到 Qwen3-ASR（config_server.py 中设置 model_type = 'qwen_asr'）
  2. 音乐/歌曲: ASR 模型训练数据是语音，不是唱歌。推荐使用人声分离工具（如 UVR 或 Demucs）先将人声从乐器中分离，再转录
  3. 音频质量: 128kbps MP3 压缩损失较多细节，优先使用原始 WAV/FLAC

Q: 纯语音内容准确率也不高？

  • 确认音频为 16kHz 采样率单声道（ffmpeg 会自动转换）
  • 确认 config_server.py 中 model_type 设置正确
  • 查看 logs/server_latest.log 确认模型正常加载，无错误输出
  • 尝试切换 language 配置: 'chinese' / 'english'（默认 'auto' 会自动检测）

运行时问题

Q: 端口 6016 冲突？

ss -tlnp | grep 6016   # 查看占用进程
kill <PID>              # 结束冲突进程

Q: pynput 无法捕获按键 (Wayland)？

echo $XDG_SESSION_TYPE   # 查看会话类型
# x11  → 正常工作
# wayland → 切换到 Xorg 登录，或在 config_client.py 中禁用快捷键监听

Q: FFmpeg 未找到？

# 在线安装
sudo apt install ffmpeg -y

# 离线安装（sysdeps/ 中已包含）
sudo dpkg -i sysdeps/ffmpeg_*.deb 2>/dev/null  # x86_64
sudo dpkg -i sysdeps-arm64/ffmpeg_*.deb 2>/dev/null  # ARM64
sudo apt install -f -y

离线部署到目标机

x86_64 目标机

# 将整个项目目录复制到目标机，然后:
cd CapsWriter-Offline-v2.6
sudo dpkg -i sysdeps/*.deb 2>/dev/null; sudo apt install -f -y
bash setup.sh --offline --bootstrap
bash start_server.sh    # 终端 1
bash start_client.sh    # 终端 2

ARM64 目标机

cd CapsWriter-Offline-v2.6
sudo dpkg -i sysdeps-arm64/*.deb 2>/dev/null; sudo apt install -f -y
bash setup.sh --offline --bootstrap
bash start_server.sh    # 终端 1
bash start_client.sh    # 终端 2

开机自启

# 启用用户级 systemd 服务
systemctl --user enable capswriter-server capswriter-client
sudo loginctl enable-linger $USER

更多文档

许可证

本项目基于 HaujetZhao/CapsWriter-Offline 进行 Linux 平台适配。原始项目: https://github.com/HaujetZhao/CapsWriter-Offline

如果觉得好用，欢迎点个 Star 或者打赏支持：

sponsor

About

CapsWriter 的离线版，一个好用的 PC 端的语音输入工具

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

CapsWriter-Offline-v2.6-Linux-offline.zip Latest
Jun 7, 2026

Packages

 
 
 

Contributors

Languages

  • Python 98.9%
  • Other 1.1%