# someWhisper

**Repository Path**: somecat/some-whisper

## Basic Information

- **Project Name**: someWhisper
- **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-04-08
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视频字幕自动生成系统

基于Docker和OpenAI Whisper的视频字幕自动生成工具,支持Windows平台下Docker Desktop配合WSL2使用。

## 项目简介

本系统是一个自动化的视频字幕生成工具,能够批量处理视频文件,自动提取音频并使用微软开源的Whisper模型进行语音识别,生成多种格式的字幕文件。系统采用Docker容器化部署,确保环境一致性和易于部署。

### 核心特性

- **批量处理**: 支持批量处理指定目录下的所有视频文件
- **多格式支持**: 支持MP4、AVI、MKV、MOV、WMV、FLV等主流视频格式
- **多字幕格式**: 支持生成SRT、VTT、ASS、TXT等多种字幕格式
- **多语言识别**: 支持中文、英文等Whisper模型支持的所有语言
- **GPU加速**: 支持NVIDIA GPU加速,大幅提升处理速度
- **并发处理**: 支持多任务并发处理,提高处理效率
- **断点续传**: 支持任务中断后从断点继续处理
- **进度监控**: 实时显示处理进度和状态
- **Docker部署**: 完全容器化部署,环境隔离,易于迁移

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                    用户接口层                            │
│              (CLI命令行 / REST API)                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    应用服务层                            │
│        (任务调度 / 工作流编排 / 进度跟踪)                 │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    核心业务层                            │
│  (文件扫描 / 音频提取 / 语音识别 / 字幕生成)             │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  基础设施层                              │
│  (Docker管理 / 队列服务 / 文件存储 / 数据持久化)         │
└─────────────────────────────────────────────────────────┘
```

## 快速开始

### 前置要求

1. **操作系统**: Windows 10 2004+ 或 Windows 11
2. **WSL2**: 已安装并启用WSL2
3. **Docker Desktop**: 4.0+版本,已启用WSL2后端
4. **GPU(可选)**: NVIDIA显卡,已安装CUDA 11.8+驱动

### 安装步骤

#### 1. 安装WSL2

以管理员身份运行PowerShell,执行以下命令:

```powershell
# 下载并运行安装脚本
.\scripts\setup_wsl2.ps1

# 或手动安装
wsl --install
wsl --set-default-version 2
```

安装完成后,重启计算机。

#### 2. 安装Docker Desktop

1. 下载并安装[Docker Desktop for Windows](https://www.docker.com/products/docker-desktop)
2. 安装过程中选择"Use WSL 2 instead of Hyper-V"
3. 安装完成后启动Docker Desktop
4. 在Settings > Resources中配置资源(CPU、内存、磁盘)
5. 在Settings > General中启用"Use the WSL 2 based engine"

#### 3. 克隆项目

```bash
git clone <项目地址>
cd video-subtitle-generator
```

#### 4. 配置环境变量

复制环境变量模板并修改:

```bash
cp .dockerenv.example .dockerenv
```

编辑`.dockerenv`文件,设置输入输出目录:

```env
INPUT_DIR=D:\Videos          # Windows视频目录
OUTPUT_DIR=D:\Subtitles      # Windows字幕输出目录
MODEL_SIZE=medium            # Whisper模型大小
CONCURRENT_LIMIT=3          # 并发任务数
GPU_ENABLED=true            # 是否启用GPU
```

#### 5. 启动服务

```bash
# 构建并启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

#### 6. 检查环境

```bash
# 进入容器
docker-compose exec whisper-subtitle bash

# 检查环境
python src/main.py check-env

# 下载模型(首次使用)
python src/main.py download-model --model medium
```

### 基本使用

#### 命令行方式

```bash
# 处理单个目录
python src/main.py process \
    --input /input \
    --output /output \
    --format srt \
    --model medium \
    --language zh

# 查看任务状态
python src/main.py status

# 实时监控进度
python src/main.py monitor

# 暂停任务
python src/main.py pause --task-id <任务ID>

# 恢复任务
python src/main.py resume --task-id <任务ID>

# 取消任务
python src/main.py cancel --task-id <任务ID>
```

#### Docker方式

```bash
# 在Docker容器中执行
docker-compose exec whisper-subtitle python src/main.py process \
    --input /input \
    --output /output \
    --format srt
```

## 配置说明

### 配置文件

系统支持多层配置,优先级从高到低:

1. 命令行参数
2. 环境变量
3. 配置文件(config/default.yaml)
4. 默认值

### 主要配置项

| 配置项 | 说明 | 默认值 | 可选值 |
|--------|------|--------|--------|
| `concurrent_limit` | 最大并发任务数 | 3 | 1-10 |
| `default_model` | 默认Whisper模型 | medium | tiny/base/small/medium/large |
| `default_format` | 默认字幕格式 | srt | srt/vtt/ass/txt |
| `default_language` | 默认语言 | auto | zh/en/auto等 |
| `timeout` | 任务超时时间(秒) | 3600 | >0 |
| `max_retry` | 最大重试次数 | 3 | 0-5 |
| `gpu_enabled` | 是否启用GPU | true | true/false |
| `temp_dir` | 临时文件目录 | /tmp/whisper | 有效路径 |

### Whisper模型选择

| 模型 | 参数量 | 英文模型 | 多语言模型 | 相对速度 | 内存需求 |
|------|--------|----------|------------|----------|----------|
| tiny | 39M | ✓ | ✓ | ~32x | ~1GB |
| base | 74M | ✓ | ✓ | ~16x | ~1GB |
| small | 244M | ✓ | ✓ | ~6x | ~2GB |
| medium | 769M | ✓ | ✓ | ~2x | ~5GB |
| large | 1550M | N/A | ✓ | 1x | ~10GB |

建议:
- 快速处理: 使用tiny或base模型
- 平衡质量和速度: 使用small模型
- 高质量识别: 使用medium或large模型

## 使用示例

### 示例1: 基本使用

处理`D:\Videos`目录下的所有视频文件,生成SRT格式字幕:

```bash
python src/main.py process \
    --input /input \
    --output /output \
    --format srt
```

### 示例2: 指定模型和语言

使用medium模型,指定中文识别:

```bash
python src/main.py process \
    --input /input \
    --output /output \
    --model medium \
    --language zh
```

### 示例3: 递归处理子目录

递归扫描所有子目录,增量处理新增文件:

```bash
python src/main.py process \
    --input /input \
    --output /output \
    --recursive \
    --incremental
```

### 示例4: GPU加速

启用GPU加速,提高处理速度:

```bash
python src/main.py process \
    --input /input \
    --output /output \
    --gpu \
    --model large
```

### 示例5: 自定义并发数

设置并发数为5,同时处理5个文件:

```bash
python src/main.py process \
    --input /input \
    --output /output \
    --concurrent 5
```

## 性能指标

### 处理速度

基于1小时标准视频文件的测试结果:

| 模型 | CPU模式 | GPU模式(GTX 1080) | GPU模式(RTX 3080) |
|------|---------|-------------------|-------------------|
| tiny | ~30分钟 | ~5分钟 | ~2分钟 |
| base | ~60分钟 | ~10分钟 | ~4分钟 |
| small | ~3小时 | ~20分钟 | ~8分钟 |
| medium | ~6小时 | ~40分钟 | ~15分钟 |
| large | ~12小时 | ~80分钟 | ~30分钟 |

### 资源占用

| 模型 | CPU内存 | GPU显存 | 磁盘空间(模型) |
|------|---------|---------|----------------|
| tiny | ~1GB | ~1GB | ~75MB |
| base | ~1GB | ~1GB | ~150MB |
| small | ~2GB | ~2GB | ~500MB |
| medium | ~5GB | ~5GB | ~1.5GB |
| large | ~10GB | ~10GB | ~3GB |

## 常见问题

### Q1: Docker容器无法启动?

**A**: 检查以下几点:
1. Docker Desktop是否正常运行
2. WSL2是否已安装并启用
3. Docker Desktop是否配置使用WSL2后端
4. 是否有足够的系统资源

### Q2: GPU无法识别?

**A**: 检查以下几点:
1. 是否安装了NVIDIA显卡驱动
2. 是否安装了CUDA Toolkit 11.8+
3. Docker Desktop是否启用了GPU支持
4. 容器是否配置了NVIDIA runtime

### Q3: 处理速度很慢?

**A**: 尝试以下优化:
1. 使用更小的模型(tiny/base)
2. 启用GPU加速
3. 增加并发任务数
4. 使用SSD存储提高IO速度

### Q4: 字幕时间轴不准确?

**A**: 可能的原因:
1. 视频帧率不稳定
2. 音频采样率不标准
3. Whisper模型识别误差

建议使用medium或large模型提高准确率。

### Q5: 内存不足错误?

**A**: 解决方法:
1. 使用更小的模型
2. 减少并发任务数
3. 增加Docker内存限制
4. 处理较小的视频文件

### Q6: Windows路径无法访问?

**A**: 检查以下几点:
1. Docker Desktop文件共享设置
2. 路径格式是否正确(使用正斜杠或双反斜杠)
3. 是否有目录访问权限

## 技术栈

- **编程语言**: Python 3.10+
- **AI模型**: OpenAI Whisper
- **音视频处理**: FFmpeg
- **容器化**: Docker + Docker Compose
- **任务队列**: Redis + RQ
- **数据存储**: SQLite + SQLAlchemy
- **CLI框架**: Click
- **日志系统**: Python logging

## 项目结构

```
video-subtitle-generator/
├── docker/                  # Docker配置
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── .dockerignore
├── src/                     # 源代码
│   ├── core/               # 核心业务逻辑
│   ├── infrastructure/     # 基础设施层
│   ├── utils/              # 工具函数
│   └── main.py             # 主入口
├── config/                  # 配置文件
├── tests/                   # 测试代码
├── scripts/                 # 脚本
├── docs/                    # 文档
└── README.md
```

## 开发指南

### 本地开发

1. 克隆项目并安装依赖:

```bash
git clone <项目地址>
cd video-subtitle-generator
pip install -e .
```

2. 安装开发依赖:

```bash
pip install -r requirements-dev.txt
```

3. 运行测试:

```bash
pytest tests/
```

### 代码规范

- 使用Black进行代码格式化
- 使用Flake8进行代码检查
- 使用MyPy进行类型检查
- 遵循PEP 8编码规范

### 贡献指南

1. Fork项目
2. 创建特性分支(`git checkout -b feature/AmazingFeature`)
3. 提交更改(`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支(`git push origin feature/AmazingFeature`)
5. 创建Pull Request

## 许可证

本项目采用MIT许可证,详见[LICENSE](LICENSE)文件。

## 联系方式

- 项目主页: <项目地址>
- 问题反馈: <Issues地址>
- 文档中心: docs/

## 致谢

- [OpenAI Whisper](https://github.com/openai/whisper) - 优秀的开源语音识别模型
- [FFmpeg](https://ffmpeg.org/) - 强大的音视频处理工具
- [Docker](https://www.docker.com/) - 容器化平台

## 更新日志

### v1.0.0 (2024-01-01)

- 初始版本发布
- 支持批量视频字幕生成
- 支持多种视频和字幕格式
- 支持GPU加速
- 支持并发处理
- 完整的CLI接口
- Docker容器化部署