# Rust_whisper

**Repository Path**: joqson/rust_whisper

## Basic Information

- **Project Name**: Rust_whisper
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Whisper 分布式语音转字幕系统

利用手机/PC 的本地算力，分布式地将视频音频转录为 SRT 字幕文件。

## 系统架构

```
┌──────────────────────────────────────────────────────────┐
│                     Rust Server (:3000)                   │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │ 视频扫描 │  │ 音频提取  │  │ 任务调度  │  │ Web 管理  │ │
│  │ (本地/   │  │ (FFmpeg)  │  │ (SQLite) │  │ (浏览器)  │ │
│  │  SFTP)  │  │           │  │          │  │          │ │
│  └─────────┘  └──────────┘  └──────────┘  └──────────┘ │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTP API
          ┌────────────┼────────────┐
          │            │            │
    ┌─────┴─────┐ ┌────┴────┐ ┌────┴─────┐
    │ PC Client │ │ Android │ │ Android  │
    │ (Rust)    │ │ Phone 1 │ │ Phone 2  │
    │ whisper   │ │ whisper │ │ whisper  │
    │ .cpp      │ │ .cpp    │ │ .cpp     │
    └───────────┘ └─────────┘ └──────────┘
```

## 功能特性

- **分布式转录**：多台手机/PC 同时工作，各自认领不同任务
- **本地推理**：使用 whisper.cpp 在设备端运行，无需上传音频到云端
- **多 chunk 转录**：长音频自动分割为 30 秒 chunk 逐段转录，合并为完整 SRT
- **断点续传**：每个 chunk 完成后保存 checkpoint，中断后从断点继续
- **模型热切换**：Android 端支持切换 tiny/small/medium 模型，无需重启
- **后台运行**：Android 前台服务 + WakeLock + 电池优化白名单
- **开机自启**：设备重启后自动恢复转录服务
- **Web 管理**：浏览器查看任务状态、客户端列表、工作目录管理
- **SFTP 支持**：浏览远程服务器目录，下载视频转录
- **SRT 回传**：转录完成后自动生成 SRT 字幕文件
- **实时日志**：Android 端 logcat 输出下载/转录/上传全流程日志，支持心跳监控

## 快速开始

### 方式一：一键打包安装（推荐）

```bash
# 1. 编译 + 打包
bash package.sh

# 2. 安装到本机
cd dist/whisper-distributed-1.0.0
sudo bash install.sh

# 3. 修改配置
sudo nano /etc/whisper/env

# 4. 启动
whisper-server-start    # 启动服务端
whisper-client-start    # 启动客户端
```

### 方式二：从源码编译

```bash
# 编译服务端 + 客户端
cargo build --release -p whisper-server -p whisper-client

# 编译 Android APK
cd android && ./setup.sh && ./gradlew assembleDebug
```

### 方式三：部署到其他机器

```bash
# 打包
bash package.sh

# 传输
scp dist/whisper-distributed-1.0.0.tar.gz user@server:~/

# 在目标机器上安装
tar xzf whisper-distributed-1.0.0.tar.gz
cd whisper-distributed-1.0.0
sudo bash install.sh
```

## 配置文件

所有配置统一在 `/etc/whisper/env`，安装后自动创建：

```bash
# ===== 服务端配置 =====
VIDEO_DIR=/home/user/Videos          # 视频扫描目录
AUDIO_TMP_DIR=/var/lib/whisper/audio # 音频临时目录
DB_PATH=/var/lib/whisper/data/data.db # 数据库路径
LISTEN_ADDR=0.0.0.0:3000             # 监听地址
SCAN_INTERVAL_SECS=60                # 扫描间隔（秒）
AUDIO_CLEANUP_HOURS=24               # 音频清理时间（小时）
ADMIN_PASSWORD=admin                  # 管理员密码（务必修改！）

# ===== 客户端配置 =====
CLIENT_SERVER_URL=http://localhost:3000    # 服务端地址
CLIENT_MODEL_PATH=/var/lib/whisper/models/ggml-small.bin  # 模型路径
CLIENT_TOKENIZER_PATH=/var/lib/whisper/models/tokenizer.json # Tokenizer 路径
CLIENT_LANGUAGE=en                         # 语言（zh=中文, ja=日语）
CLIENT_POLL_INTERVAL=10                    # 轮询间隔（秒）
```

修改配置后重启服务即可生效。

## 启动命令

| 命令 | 说明 |
|------|------|
| `whisper-server-start` | 启动服务端（读取 /etc/whisper/env） |
| `whisper-client-start` | 启动客户端（读取 /etc/whisper/env） |

### Android 客户端

```bash
# 安装 APK
adb install android/whisper-client.apk

# 推送模型到手机内部存储（推荐，避免权限问题）
adb push ggml-tiny.en.bin /sdcard/Download/ggml-tiny.en.bin
adb push ggml-small.bin /sdcard/Download/ggml-small.bin

# 或者直接推送到应用私有目录（无需权限）
adb push ggml-tiny.en.bin /data/local/tmp/
adb shell run-as com.example.whisper cp /data/local/tmp/ggml-tiny.en.bin files/ggml-tiny.en.bin
```

在手机上填写 Server URL（如 `http://192.168.1.100:3000`）和 Model Path，点击 Start。

> **注意**：Android 11+ 需要授予"所有文件访问"权限才能读取 `/sdcard/Download/` 下的模型文件。如果权限不足，应用会自动将模型复制到内部存储。也可以用 `adb push` 直接推送到应用私有目录。

## 环境变量

### 服务端

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `VIDEO_DIR` | `/data/videos` | 视频扫描目录 |
| `AUDIO_TMP_DIR` | `/tmp/audio` | 音频临时目录 |
| `DB_PATH` | `data.db` | SQLite 数据库路径 |
| `LISTEN_ADDR` | `0.0.0.0:3000` | 监听地址 |
| `SCAN_INTERVAL_SECS` | `60` | 扫描间隔（秒） |
| `AUDIO_CLEANUP_HOURS` | `24` | 音频清理时间（小时） |
| `ADMIN_PASSWORD` | `admin` | 管理员密码 |

### 客户端

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CLIENT_SERVER_URL` | `http://localhost:3000` | 服务端地址 |
| `CLIENT_MODEL_PATH` | `./ggml-small.bin` | whisper 模型文件路径 |
| `CLIENT_TOKENIZER_PATH` | `./tokenizer.json` | tokenizer.json 路径 |
| `CLIENT_LANGUAGE` | `en` | 语言代码 |
| `CLIENT_POLL_INTERVAL` | `10` | 轮询间隔（秒） |

## API 接口

### 客户端接口（无需认证）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/client/register` | 客户端注册 |
| POST | `/api/client/heartbeat` | 心跳 |
| GET | `/api/task/next` | 领取下一个任务 |
| POST | `/api/task/submit` | 提交字幕 |
| POST | `/api/task/fail` | 报告任务失败 |
| POST | `/api/task/progress` | 上报进度 |
| GET | `/download/audio/{task_id}` | 下载音频文件 |

### 管理接口（需认证）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 任务概览页 |
| GET | `/browser` | SFTP 浏览页 |
| GET | `/api/client/list` | 客户端列表 |
| GET | `/api/workdir` | 当前工作目录 |
| GET | `/api/workdirs` | 工作目录列表 |
| POST | `/api/workdir` | 切换工作目录 |
| POST | `/api/scan` | 手动触发扫描 |
| POST | `/api/task/retry` | 重试失败任务 |
| POST | `/api/dedup` | 去重任务 |

## 项目结构

```
Rust_whisper/
├── server/                     # Rust 服务端
│   ├── src/
│   │   ├── main.rs             # 入口 + 路由
│   │   ├── config.rs           # 环境变量配置
│   │   ├── app.rs              # AppState
│   │   ├── models.rs           # 数据模型
│   │   ├── db/                 # 数据库操作
│   │   ├── handlers/           # HTTP 处理器
│   │   └── tasks/              # 任务管理
│   ├── templates/              # HTML 模板
│   └── static/                 # 静态资源
├── client/                     # Rust PC 客户端
│   └── src/
│       ├── main.rs             # 入口
│       ├── task_fetcher.rs     # 任务领取
│       ├── audio_downloader.rs # 音频下载
│       ├── transcriber.rs      # whisper.cpp 转录
│       ├── uploader.rs         # SRT 上传
│       └── retry.rs            # 重试逻辑
├── android/                    # Android 客户端
│   ├── app/src/main/
│   │   ├── java/.../           # Kotlin 代码
│   │   ├── cpp/                # NDK/JNI (whisper.cpp)
│   │   └── res/                # 资源文件
│   ├── setup.sh                # 初始化脚本
│   └── README.md               # Android 详细说明
├── start_server.sh             # 服务端启动脚本（开发用）
├── start_client.sh             # 客户端启动脚本（开发用）
├── package.sh                  # 一键打包脚本
├── UBUNTU_SETUP.md             # Ubuntu 部署指南
└── Cargo.toml                  # Workspace 配置
```

## 性能参考

| 设备 | 模型 | 30 秒音频耗时 | 30 分钟音频耗时 |
|------|------|--------------|----------------|
| Ryzen 5600X | ggml-small | ~5s | ~2min |
| Snapdragon 8 Gen2 | ggml-small | ~20s | ~8min |
| Snapdragon 8 Gen1 | ggml-small | ~30s | ~12min |
| Snapdragon 778G | ggml-tiny | ~15s | ~6min |
| Xiaomi 14 (8 Gen3) | ggml-small | ~10min/chunk | ~60min (17 chunks) |
| Xiaomi 14 (8 Gen3) | ggml-tiny | ~2min/chunk | ~12min (17 chunks) |

> **建议**：手机端优先使用 `ggml-tiny.en.bin`（75MB），速度比 small 快 5-8 倍。英文内容用 `tiny.en`，多语言用 `tiny`。

## 模型下载

| 模型 | 大小 | 语言 | 链接 |
|------|------|------|------|
| ggml-tiny.bin | 75MB | 多语言 | [下载](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin) |
| ggml-tiny.en.bin | 75MB | 仅英文 | [下载](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin) |
| ggml-small.bin | 244MB | 多语言 | [下载](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin) |
| ggml-small.en.bin | 244MB | 仅英文 | [下载](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.en.bin) |
| ggml-medium.bin | 769MB | 多语言 | [下载](https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin) |

## 许可证

MIT