Fast Whisper API 🎙️

基于 FastAPI 和 faster-whisper 的高性能视频语音转文字服务，支持接收视频文件并返回带时间戳的转写结果。适用于 Dify RAG 工作流、内容分析、字幕生成等场景。

✨ 特性

• 🚀 高性能: 基于 faster-whisper，比原版 Whisper 快 4-5 倍
• 📹 多格式支持: 支持 mp4, mov, mkv, avi, flv, wmv 等常见视频格式
• 🎯 精确时间戳: 返回带时间戳的转写片段，便于后续处理
• 🌍 自动语言检测: 自动识别视频中的语言
• 🔧 易于集成: RESTful API，轻松集成到现有系统
• 🧹 自动清理: 处理完成后自动清理临时文件
• 📊 API 文档: 自动生成的 Swagger/ReDoc 文档

🎯 功能特性

• 支持多种视频格式（mp4, mov, mkv, avi, flv, wmv）
• 使用 ffmpeg 自动提取音频
• 使用 faster-whisper 进行本地语音转文字
• 返回带时间戳的 JSON 格式结果
• 自动检测语言
• 处理完成后自动清理临时文件

📋 环境要求

• Python ≥ 3.10
• ffmpeg
• 操作系统: macOS / Linux / Windows (WSL)

注意: 本项目在 macOS (Apple Silicon) 上开发和测试，Linux 和 Windows (WSL) 上也可运行。

🚀 快速开始

1. 安装依赖

安装 ffmpeg

# 使用 Homebrew 安装 ffmpeg
brew install ffmpeg

验证安装：

ffmpeg -version

安装 Python 依赖

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

2. 启动服务

uvicorn main:app --reload

服务将在 http://localhost:8000 启动。

3. 查看 API 文档

启动服务后，访问以下地址查看自动生成的 API 文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

📡 API 使用

转写视频

端点: POST /transcribe

请求格式: multipart/form-data

参数:

• file: 视频文件（必填）

响应示例:

{
  "video_name": "demo.mp4",
  "duration": 312.5,
  "segments": [
    {
      "start": 12.3,
      "end": 18.7,
      "text": "这里是识别出的内容"
    },
    {
      "start": 18.7,
      "end": 25.2,
      "text": "这是下一段内容"
    }
  ],
  "language": "zh",
  "language_probability": 0.987
}

字段说明:

• video_name: 原始视频文件名
• duration: 视频总时长（秒）
• segments: 转写片段数组
  • start: 片段开始时间（秒）
  • end: 片段结束时间（秒）
  • text: 转写文本
• language: 检测到的语言代码
• language_probability: 语言检测置信度

使用 curl 测试

curl -X POST "http://localhost:8000/transcribe" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/your/video.mp4"

使用 Python requests 测试

import requests

url = "http://localhost:8000/transcribe"
files = {"file": open("your_video.mp4", "rb")}

response = requests.post(url, files=files)
result = response.json()

print(f"视频时长: {result['duration']} 秒")
print(f"检测语言: {result['language']}")
for segment in result['segments']:
    print(f"[{segment['start']:.2f}s - {segment['end']:.2f}s] {segment['text']}")

🔧 配置说明

修改模型大小

在 main.py 中修改转写器初始化参数：

transcriber = VideoTranscriber(
    model_size="medium",  # 可选: tiny, base, small, medium, large
    device="cpu",
    compute_type="int8"
)

模型大小说明:

• tiny: 最快，精度较低
• base: 较快，精度一般
• small: 平衡速度和精度（默认）
• medium: 较慢，精度较高
• large: 最慢，精度最高

音频参数

在 main.py 的 extract_audio_from_video 调用中可以修改：

• sample_rate: 采样率（默认 16000 Hz）
• channels: 声道数（默认 1，单声道）

📁 项目结构

video-transcriber/
├── main.py                 # FastAPI 入口和路由
├── transcriber.py          # faster-whisper 转写逻辑
├── audio_utils.py          # ffmpeg 音频提取工具
├── requirements.txt        # Python 依赖
├── README.md              # 项目文档
└── tmp/                   # 临时文件目录（自动创建）

⚠️ 注意事项

1. 首次运行: faster-whisper 会在首次使用时自动下载模型，可能需要一些时间
2. 临时文件: 所有临时文件在处理完成后会自动清理
3. 文件大小: 大文件处理可能需要较长时间，建议在 Dify 工作流中设置合适的超时时间
4. 内存使用: 模型大小影响内存占用，small 模型约占用 500MB-1GB 内存

🐛 故障排查

ffmpeg 未找到

# 确保已安装 ffmpeg
brew install ffmpeg

# 验证安装
which ffmpeg

模型下载失败

如果模型下载失败，可以手动下载并指定路径，或检查网络连接。

内存不足

如果遇到内存问题，可以：

1. 使用更小的模型（如 tiny 或 base）
2. 增加系统可用内存

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📝 许可证

本项目采用 MIT License 许可证。

🙏 致谢

• faster-whisper - 高性能 Whisper 实现
• FastAPI - 现代、快速的 Web 框架
• FFmpeg - 强大的音视频处理工具

📧 联系方式

如有问题或建议，欢迎提交 Issue。

---

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