VoiceStudio

环境要求

• Node 20+ 与 Bun（从源码运行时需要）
• Python 3.11+（从源码运行时需要；首次启动自动通过 uv 配置依赖）
• Docker（使用容器方式运行时需要）
• 系统要求：macOS 13.3+ / Windows 10 或 11 / Linux AppImage 需 x86_64 且 glibc 2.39+
• 首次启动需联网，用于创建托管 Python 环境并下载默认模型

安装与启动步骤

1. 1选择部署方式

   README 提供四种方式：桌面安装包、Docker 镜像、源码运行、远程后端。按你的系统任选一种即可。

2. 2下载桌面安装包

   到最新 Release 页面下载：macOS 用 Apple Silicon DMG，Windows 用 x64 MSI（可选当前用户版免管理员），Linux 用 AppImage。

3. 3Docker 一键启动

   官方镜像仅支持 linux/amd64。命令会后台启动容器、映射本机 3900 端口并挂载数据卷 omnivoice-data。

   docker run -d -p 127.0.0.1:3900:3900 -v omnivoice-data:/app/omnivoice_data --name voicestudio palashdeb/omnivoice-studio:stable

   复制

4. 4克隆源码仓库

   从源码运行前先装好 Node 20+/Bun 与 Python 3.11+，再克隆仓库并进入目录。

   git clone https://github.com/debpalash/VoiceStudio.git
   cd VoiceStudio

   复制

5. 5安装依赖

   使用 Bun 安装前端依赖；桌面启动器会在首次运行时自动通过 uv 配置 Python 依赖。

   bun install

   复制

6. 6启动桌面应用

   运行桌面启动器，首次启动会自动创建 Python 环境并下载默认模型，耗时较长请耐心等待。

   bun run desktop

   复制

7. 7改用浏览器界面

   如果不想用桌面窗口，可用浏览器 UI 模式启动同一套服务。

   bun run dev

   复制

8. 8排查启动失败

   在应用内执行 设置 → 关于 → 运行自检，或直接跑诊断命令定位问题。

   uv run python backend/main.py --diagnose --deep

   复制

如何确认成功

Docker 方式执行 docker ps 看到 voicestudio 容器为 Up 且映射 3900 端口，即可访问本机 3900。

常见问题

注意事项

• 项目正在进行 Electron 重写，请勿提交桌面应用相关的 issue 和 PR。
• 本地工作流无需账号、API key、订阅或用量计量。
• 首次启动会创建托管 Python 环境并下载默认模型，后续启动直接复用。
• 发布镜像仅提供 linux/amd64，ARM64 主机使用前请确认架构要求。