Skip to content
BranchesTags

Repository files navigation

VideoSubtitleAI - 本地离线音视频转字幕工具

基于OpenAI Whisper大模型驱动的本地离线音视频转字幕工具

Python Whisper License

📋 目录

✨ 功能特性

🎯 核心功能

功能 描述
多格式支持 支持 MP4、MOV、AVI、MKV、FLV、WMV、WEBM 等视频格式，以及 MP3、WAV、M4A、FLAC 等音频格式
高精度识别 基于 OpenAI Whisper 大模型，支持 99 种语言识别，时间轴精准对齐
标准字幕输出 生成标准 SRT 格式字幕，支持所有主流播放器
多语言支持 自动检测语言，支持中文、英文、日文、韩文等多国语言
自动分句断句 智能断句、标点符号识别，时间轴自动优化
批量处理 一键处理整个文件夹，支持递归扫描子目录
模型选择 提供 tiny/base/small/medium/large 多种模型，平衡速度与准确率
纯本地推理 完全离线运行，无网络请求，保护隐私安全
进度与日志 实时进度显示、详细错误日志、批量处理报告

🔧 技术亮点

  • 模块化设计: 代码高度模块化，方便扩展双语字幕、字幕编辑、格式转换等功能
  • **GPU 加速: 自动检测并使用 CUDA 加速，处理速度提升 10-100 倍
  • **智能优化: 自动合并短片段、拆分超长片段，移除静音段落
  • **临时文件管理: 自动清理临时文件，节省磁盘空间

🏗️ 技术架构

┌─────────────────────────────────────────────────────────────────────┐
│                        VideoSubtitleAI                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐         │
│  │ 命令行入口   │    │  API 接口   │    │ 批量处理器    │         │
│  │  main.py   │    │ VideoSubtitleAI │    │ BatchProcessor │         │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘         │
│         │                 │                 │                      │
│         └─────────────────┼─────────────────┼──────────────────────┘
│                           │                                      │
│                           ▼                                      ▼
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    核心处理流程                           │   │
│  ├─────────────┬─────────────┬─────────────┬─────────────┤   │
│  │ 音频处理  │ 语音识别   │ 字幕生成 │ 进度日志  │   │
│  │AudioProcessor│SpeechRecognizer│SubtitleGen│ProgressLogger│   │
│  └──────┬──────┴──────┬──────┴──────┬──────┴──────┘   │
│         │             │             │                     │
│         ▼             ▼             ▼                     │
│  ┌───────────────────────────────────────────────────────┐       │
│  │              OpenAI Whisper 模型               │       │
│  │  tiny / base / small / medium / large / large-v3   │       │
│  └───────────────────┬───────────────────────────┘       │
│                      │                                     │
│                      ▼                                     │
│  ┌───────────────────────────────────────────────────────┐       │
│  │              计算层 (PyTorch)                    │       │
│  │         CPU / CUDA (NVIDIA GPU)                │       │
│  └───────────────────────────────────────────────────────┘       │
└──────────────────────────────────────────────────────────────────┘

🚀 安装指南

系统要求

  • 操作系统: Windows 10/11, macOS 10.15+, Linux
  • Python: 3.8 - 3.11 (推荐 3.10)
  • 内存: 至少 8GB+ (推荐 16GB+)
  • GPU (可选): NVIDIA GPU (支持 CUDA 11.8+)

步骤 1: 安装 FFmpeg

FFmpeg 用于视频音频处理必须安装：

Windows:

# 使用 winget 安装 (推荐)
winget install ffmpeg

# 或者使用 choco
choco install ffmpeg

# 或者手动下载: https://ffmpeg.org/download.html#build-windows
# 解压后将 bin 目录添加到系统 PATH

macOS:

# 使用 Homebrew
brew install ffmpeg

**Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

验证安装:

ffmpeg -version

步骤 2: 创建虚拟环境 (推荐)

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate

# macOS/Linux:
source venv/bin/activate

步骤 3: 安装 PyTorch

根据你的系统选择合适的 PyTorch 版本：

GPU 版本 (推荐，速度快):

# CUDA 11.8 (Windows/Linux)
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

CPU 版本:

pip3 install torch torchvision torchaudio

验证 PyTorch 安装:

import torch
print(torch.__version__)
print(torch.cuda.is_available())  # GPU 版本返回 True

步骤 4: 安装项目依赖

pip install -r requirements.txt

或者手动安装:

pip install openai-whisper
pip install tqdm
pip install numpy

🎬 快速开始

处理单个视频

# 使用默认模型 (base) 处理视频
python main.py -i video.mp4

# 指定输出路径
python main.py -i video.mp4 -o subtitle.srt

# 使用更好的模型
python main.py -i video.mp4 -m small

# 指定语言 (自动检测也可以)
python main.py -i video.mp4 -l zh

批量处理文件夹

# 处理文件夹中的所有视频
python main.py -i ./videos -o ./subtitles

# 递归处理子文件夹
python main.py -i ./videos -o ./subtitles -r

# 使用 large 模型获得最高准确率
python main.py -i ./videos -m large

检测语言

# 仅检测视频语言，不生成字幕
python main.py -i video.mp4 --detect-language-only

查看系统信息

python main.py -i dummy --info

📖 使用说明

命令行参数详解

python main.py [参数]

输入输出参数

参数 说明
-i, --input 必需 输入文件或文件夹路径
-o, --output 输出文件或文件夹路径（可选）

模型参数

参数 说明 默认值
-m, --model Whisper 模型大小: tiny, base, small, medium, large, large-v2, large-v3 base
--model-dir 模型存储目录（可选） ~/.cache/whisper
--device 运行设备: cpu, cuda 自动选择

语言参数

参数 说明 默认值
-l, --language 语言代码: auto (自动检测), zh (中文), en (英文), ja (日文), ko (韩文) 等 auto
--translate 翻译为英文（默认是转录原语言） False

批量处理参数

参数 说明 默认值
-r, --recursive 递归处理子文件夹 False
--skip-existing 跳过已存在字幕的文件 True
--no-skip-existing 不跳过已存在字幕的文件 -

其他参数

参数 说明
--log-dir 日志目录（可选）
-v, --verbose 输出详细日志
--detect-language-only 仅检测语言，不生成字幕
--info 显示系统信息

模型选择指南

模型 大小 参数 速度 准确率 VRAM 需求 适用场景
tiny 39 MB 39M 最快 较低 ~1 GB 快速预览、粗略处理
base 74 MB 74M 快 中 ~1 GB 日常使用、视频剪辑
small 244 MB 244M 中等 较高 ~2 GB 大多数场景推荐
medium 769 MB 769M 较慢 高 ~5 GB 专业内容、高质量要求
large 1.5 GB 1550M 最慢 最高 ~10 GB 最高精度要求
large-v2 1.5 GB 1550M 最慢 最高 ~10 GB 改进版 large
large-v3 1.5 GB 1550M 最慢 最高 ~10 GB 最新版本，推荐

**建议:

  • **大多数场景推荐使用 small 或 medium
  • 中文语音清晰视频 建议 small 或 medium
  • 低配置电脑 用 base 或 tiny
  • 高要求场景 用 large 或 large-v3

语言代码参考

语言 代码 语言 代码
自动检测 auto 英文 en
中文 zh 日文 ja
韩文 ko 法文 fr
德文 de 西班牙文 es
俄文 ru 葡萄牙文 pt
意大利文 it 荷兰文 nl
阿拉伯文 ar 印地文 hi

Whisper 支持 99 种语言，完整列表请参考 Whisper 官方文档

📁 项目结构

VideoSubtitleAI/
├── __init__.py              # 包初始化文件
├── main.py                    # 主程序入口，命令行接口
├── audio_processor.py        # 音频处理模块
├── speech_recognizer.py      # 语音识别模块 (Whisper)
├── subtitle_generator.py      # 字幕生成模块 (SRT)
├── batch_processor.py        # 批量处理模块
├── progress_logger.py         # 进度显示和日志模块
├── requirements.txt           # Python 依赖包
└── README.md                  # 项目说明文档

模块说明

1. audio_processor.py - 音频处理模块

功能: 从视频提取音频，转换音频格式

主要类: AudioProcessor

主要方法:

  • extract_audio_from_video() - 从视频提取音频
  • convert_audio_format() - 转换音频格式
  • process_media_file() - 统一处理音视频处理接口
  • get_audio_duration() - 获取音频时长

2. speech_recognizer.py - 语音识别模块

功能: 基于 Whisper 模型进行语音识别

主要类: SpeechRecognizer

主要方法:

  • recognize() - 执行语音识别
  • detect_language() - 仅检测语言
  • load_model() - 加载模型
  • unload_model() - 卸载模型释放显存

3. subtitle_generator.py - 字幕生成模块

功能: 生成 SRT 格式字幕，优化时间轴

主要类: SubtitleGenerator

主要方法:

  • generate_srt_file() - 生成 SRT 字幕文件
  • generate_srt_content() - 生成 SRT 内容字符串
  • parse_srt_file() - 解析 SRT 文件
  • merge_srt_files() - 合并多个 SRT 文件
  • shift_subtitle_timing() - 调整字幕时间轴

4. batch_processor.py - 批量处理模块

功能: 批量处理文件夹中的音视频文件

主要类: BatchProcessor, BatchProgress

主要方法:

  • scan_files() - 扫描文件夹中的音视频文件
  • process_files() - 批量处理文件
  • process_folder() - 处理整个文件夹
  • generate_report() - 生成处理报告

5. progress_logger.py - 进度和日志模块

功能: 进度条显示、日志记录

主要类: ProgressBar, ConsoleLogger, ProgressLogger

主要方法:

  • create_progress_bar() - 创建进度条
  • log() - 记录日志
  • success() / fail() - 记录成功/失败
  • print_summary() - 打印处理摘要

6. main.py - 主程序入口

功能: 命令行接口，整合所有模块

主要类: VideoSubtitleAI

主要方法:

  • initialize() - 初始化所有组件
  • process_single_file() - 处理单个文件
  • process_folder() - 处理文件夹
  • detect_language() - 检测语言

🔧 扩展开发

架构设计

项目采用模块化设计，各模块职责单一，便于扩展：

VideoSubtitleAI (主类)
    │
    ├── AudioProcessor (音频处理)
    ├── SpeechRecognizer (语音识别)
    ├── SubtitleGenerator (字幕生成)
    ├── BatchProcessor (批量处理)
    └── ProgressLogger (进度日志)

扩展示例: 双语字幕

# 在 subtitle_generator.py 中添加

def generate_bilingual_srt(
    self,
    segments_cn: List[Dict],
    segments_en: List[Dict],
    output_path: str,
):
    """
    生成双语字幕
    第一行: 中文
    第二行: 英文
    """
    # 实现逻辑...
    pass

扩展示例: 字幕编辑

# 创建新模块 subtitle_editor.py

class SubtitleEditor:
    """字幕编辑器"""
    
    def merge_subtitles(self, srt_files: List[str]):
        """合并字幕"""
        pass
    
    def split_subtitle(self, srt_path: str, split_time: float):
        """分割字幕"""
        pass
    
    def adjust_timing(self, segments: List, offset: float):
        """调整时间轴"""
        pass

扩展示例: 更多格式支持

# 在 subtitle_generator.py 中添加

def convert_to_vtt(self, segments: List[Dict]) -> str:
    """转换为 WebVTT 格式"""
    pass

def convert_to_ass(self, segments: List[Dict]) -> str:
    """转换为 ASS/SSA 格式"""
    pass

def convert_to_smi(self, segments: List[Dict]) -> str:
    """转换为 SMI 格式"""
    pass

❓ 常见问题

Q1: 第一次运行很慢？

A: 第一次运行时会自动下载 Whisper 模型，模型大小从 39MB 到 1.5GB 不等。下载完成后，后续运行会快很多。

你也可以手动下载模型放到 ~/.cache/whisper/ 目录：

Q2: GPU 加速不工作？

A: 请检查：

  1. 安装了 CUDA 版本的 PyTorch
  2. NVIDIA 驱动程序是最新的
  3. CUDA 版本与 PyTorch 匹配

验证：

import torch
print(torch.cuda.is_available())  # 应该返回 True
print(torch.cuda.get_device_name(0))  # 显示 GPU 名称

Q3: 内存不足？

A: 解决方案：

  1. 使用更小的模型（tiny 或 base）
  2. 关闭其他占用内存的程序
  3. 使用交换空间（虚拟内存）
  4. 考虑升级硬件

Q4: 字幕不准确？

A: 提高准确率的方法：

  1. 使用更大的模型（medium 或 large）
  2. 确保音频质量良好
  3. 尝试指定语言而不是自动检测
  4. 检查视频中是否有清晰的语音

Q5: 支持哪些视频格式？

A: 只要 FFmpeg 支持的格式都可以：

  • 视频: MP4, MOV, AVI, MKV, FLV, WMV, WebM, MPEG, 3GP 等
  • 音频: MP3, WAV, M4A, FLAC, AAC, OGG, WMA 等

Q6: 如何批量处理大量文件？

A: 只需指定文件夹路径即可：

python main.py -i /path/to/videos -o /path/to/subtitles -r

-r 参数会递归处理所有子文件夹。

Q7: 生成的字幕在播放器无法播放？

A: 检查：

  1. 字幕文件名与视频文件名相同（除扩展名不同）
  2. 字幕文件编码是 UTF-8
  3. 播放器支持 SRT 格式

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系方式

如有问题或建议，请通过以下方式联系：

  • 提交 Issue
  • 发送邮件

🙏 致谢

更新日志

v1.0.0 (2024-xx-xx)

  • 初始版本发布
  • 支持多种音视频格式
  • 基于 Whisper 模型的语音识别
  • 生成标准 SRT 字幕
  • 支持批量处理
  • 支持多种模型大小选择
  • 实时进度显示和日志记录

如果这个项目对你有帮助，请给个 ⭐ Star！

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages