nanamiakari0815/MediaConvert

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

MediaConvert/README.md

帷幄庸者

docs: 更新API文档、部署文档和README

1780c78c

PreviewCode viewBlame

MediaConvert API - 多媒体处理服务

基于 OpenAI Whisper 和 FFmpeg 的多媒体处理 API 服务，支持语音转文本和音视频转码功能。

功能特性

🎯 语音转文本：支持多种音频格式（MP3, WAV, M4A, FLAC, MP4 等）
🎬 音视频转码：支持多种格式转换和参数调整
🌍 支持 99+ 种语言的语音识别
⚡ GPU 加速支持，提升处理速度
🔄 异步任务处理，支持大文件处理
📊 实时任务状态查询和监控
🎛️ 灵活的参数配置和优先级管理
📝 多种输出格式（文本、SRT字幕、JSON、音频、视频等）
🐳 Docker 容器化部署，生产就绪
☁️ S3/MinIO 对象存储支持，直接从云存储下载和上传文件
🔄 统一任务API，简化接口调用
📋 完整的API文档，支持多种调用方式

快速开始

方式一：Docker 部署（推荐）

生产环境部署


# 1. 拉取最新镜像
docker pull docker.cnb.cool/l8ai/document/mediaconvert:latest

# 2. 创建必要的目录（数据持久化）
mkdir -p data logs models task_workspace

# 3. 创建环境配置文件
cat > .env << 'EOF'
# 数据库配置
DB_TYPE=sqlite
SQLITE_DB_NAME=data/MediaConvert.db

# S3/MinIO配置（下载服务）
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
S3_ENDPOINT_URL=http://your-minio:9000
AWS_REGION=us-east-1

# S3/MinIO配置（上传服务）
UPLOAD_S3_ACCESS_KEY_ID=your_access_key
UPLOAD_S3_SECRET_ACCESS_KEY=your_secret_key
UPLOAD_S3_ENDPOINT_URL=http://your-minio:9000
UPLOAD_S3_REGION=us-east-1
UPLOAD_S3_BUCKET=ai-file

# 日志配置
LOG_LEVEL=20
LOG_FILES_DIR=/workspace/log_files

# GPU配置（如果有GPU）
WHISPER_DEVICE=cuda
FORCE_CPU=false
EOF

# 4. 启动服务（生产环境）
docker run -d \
  --name mediaconvert-api \
  --restart unless-stopped \
  -p 33080:80 \
  --env-file .env \
  -v $(pwd)/data:/workspace/data \
  -v $(pwd)/logs:/workspace/log_files \
  -v $(pwd)/models:/workspace/models \
  -v $(pwd)/task_workspace:/workspace/task_workspace \
  docker.cnb.cool/l8ai/document/mediaconvert:latest

GPU支持部署


# 启动服务（GPU加速）
docker run -d \
  --name mediaconvert-api \
  --restart unless-stopped \
  --gpus all \
  -p 33080:80 \
  --env-file .env \
  -v $(pwd)/data:/workspace/data \
  -v $(pwd)/logs:/workspace/log_files \
  -v $(pwd)/models:/workspace/models \
  -v $(pwd)/task_workspace:/workspace/task_workspace \
  docker.cnb.cool/l8ai/document/mediaconvert:latest

Docker Compose 部署（推荐）


# 1. 下载 docker-compose.yml
curl -O https://raw.githubusercontent.com/your-repo/mediaconvert-api/main/docker-compose.yml

# 2. 启动服务
docker-compose up -d

# 3. 查看服务状态
docker-compose ps

# 4. 查看日志
docker-compose logs -f

目录结构说明


./
├── data/                    # 数据库文件（持久化）
│   └── MediaConvert.db     # SQLite数据库
├── logs/                   # 日志文件（持久化）
│   ├── app.log            # 应用日志
│   └── error.log          # 错误日志
├── models/                 # 模型文件（持久化，可选）
│   ├── whisper/           # Whisper模型
│   └── huggingface/       # HuggingFace模型
├── task_workspace/         # 任务工作空间（持久化）
│   └── task_*/            # 各任务的临时文件
├── .env                   # 环境配置文件
└── docker-compose.yml     # Docker Compose配置

方式二：源码部署

环境要求

Python 3.8+
CUDA 支持的 GPU（可选，用于加速）
FFmpeg（用于音频处理）

安装依赖


# 使用国内镜像加速
pip install -r requirements.txt -i https://mirrors.cloud.tencent.com/pypi/simple

启动服务


python start.py

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

服务验证


# 健康检查
curl "http://localhost:33080/api/tasks/health"

# 预期返回
{"status":"healthy","message":"Unified Task API is running"}

# Whisper服务检查
curl "http://localhost:33080/api/whisper/health"

# 预期返回
{"status":"healthy","message":"Whisper API is running"}

# 访问API文档
open http://localhost:33080/docs

API 使用说明

统一任务API（推荐）

创建语音转文本任务

POST /api/tasks/create


# S3存储方式（推荐）
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=audio.mp3" \
  -F "task_type=transcribe" \
  -F "language=zh" \
  -F "word_timestamps=true" \
  -F "priority=high"

# 本地文件上传
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "file_upload=@audio.mp3" \
  -F "task_type=transcribe" \
  -F "language=zh" \
  -F "priority=high"

创建音视频转码任务


# 高质量音频转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=video.mp4" \
  -F "task_type=transcode" \
  -F "transcode_type=audio_high" \
  -F "output_format=mp3"

# H264视频转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=video.mp4" \
  -F "task_type=transcode" \
  -F "transcode_type=video_h264" \
  -F "output_format=mp4" \
  -F "resolution=1280x720"

查询任务结果


# 根据任务ID查询
curl "http://localhost:33080/api/tasks/query/{task_id}"

# 根据bucket和文件路径查询
curl "http://localhost:33080/api/tasks/query?bucket=gaojiaqi&file_url=s3://gaojiaqi/audio.mp3"

专用API

Whisper专用API

POST /api/tasks/whisper/create


curl -X POST "http://localhost:33080/api/tasks/whisper/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=audio.mp3" \
  -F "language=zh" \
  -F "word_timestamps=true" \
  -F "priority=high"

转码专用API

POST /api/tasks/transcode/create


curl -X POST "http://localhost:33080/api/tasks/transcode/create" \
  -F "bucket=gaojiaqi" \
  -F "file_path=video.mp4" \
  -F "transcode_type=audio_high" \
  -F "output_format=mp3"

响应示例


{
  "code": 200,
  "message": "统一任务创建成功: 类型=transcribe, 文件来源=s3",
  "data": {
    "task_id": 19,
    "status": "queued",
    "task_type": "transcribe",
    "file_name": "audio.mp3",
    "file_url": "s3://gaojiaqi/audio.mp3",
    "created_at": "2025-08-08T14:50:00.123456",
    "priority": "high",
    "result_url": "http://localhost:33080/api/tasks/query/19"
  }
}

任务状态说明

状态	说明	下一步
`queued`	任务已排队，等待处理	继续等待
`processing`	任务正在处理中	继续等待
`completed`	✅ 任务已完成	获取结果
`failed`	❌ 任务处理失败	检查错误信息

成功响应示例


{
  "code": 200,
  "message": "查询成功",
  "data": {
    "task_id": 18,
    "status": "completed",
    "task_type": "transcribe",
    "file_name": "audio.mp3",
    "file_url": "s3://gaojiaqi/audio.mp3",
    "ai_file_path": [
      "gaojiaqi/audio/whisper/transcription_result.json",
      "gaojiaqi/audio/whisper/transcription_text.txt",
      "gaojiaqi/audio/whisper/transcription_timeline.txt",
      "gaojiaqi/audio/whisper/transcription_subtitles.srt"
    ],
    "s3_urls": [
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_result.json",
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_text.txt",
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_timeline.txt",
      "http://shenben.club:9000/ai-file/gaojiaqi/audio/whisper/transcription_subtitles.srt"
    ],
    "result": {
      "text": "这是转录的完整文本内容...",
      "language": "zh",
      "segments": [
        {
          "id": 0,
          "start": 0.0,
          "end": 5.0,
          "text": "这是第一段文本"
        }
      ]
    },
    "task_processing_time": 100.98
  }
}

配置说明

环境变量配置

主要配置通过环境变量或.env文件设置：

数据库配置


DB_TYPE=sqlite                    # 数据库类型
SQLITE_DB_NAME=data/MediaConvert.db  # SQLite数据库文件路径

S3/MinIO配置


# 下载服务配置
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
S3_ENDPOINT_URL=http://your-minio:9000
AWS_REGION=us-east-1

# 上传服务配置
UPLOAD_S3_ACCESS_KEY_ID=your_access_key
UPLOAD_S3_SECRET_ACCESS_KEY=your_secret_key
UPLOAD_S3_ENDPOINT_URL=http://your-minio:9000
UPLOAD_S3_REGION=us-east-1
UPLOAD_S3_BUCKET=ai-file

模型和性能配置


WHISPER_DEVICE=cuda              # 设备类型：cuda/cpu
FORCE_CPU=false                  # 强制使用CPU
LOG_LEVEL=20                     # 日志级别
MAX_FILE_SIZE=2147483648         # 最大文件大小（2GB）

高级配置

详细配置选项请参考：config/settings.py

性能优化

GPU 加速


# 检查 CUDA 可用性
docker run --rm --gpus all docker.cnb.cool/l8ai/document/mediaconvert:latest \
  python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

# 检查GPU状态
nvidia-smi

模型选择

模型	大小	速度	准确性	推荐用途
`tiny`	39MB	最快	较低	实时转录
`base`	74MB	快	中等	快速处理
`small`	244MB	中等	良好	平衡选择
`medium`	769MB	较慢	很好	高质量转录
`large-v3`	1550MB	慢	最佳	最高质量（默认）

并发优化


# 调整并发任务数（通过环境变量）
MAX_CONCURRENT_TASKS=3

# 监控系统资源
docker stats mediaconvert-api

故障排除

常见问题

CUDA 内存不足


# 修改环境变量使用 CPU
echo "FORCE_CPU=true" >> .env
docker restart mediaconvert-api

容器启动失败


# 查看容器日志
docker logs mediaconvert-api

# 检查端口占用
netstat -tlnp | grep :80

# 检查磁盘空间
df -h

任务处理失败


# 查看任务详情
curl "http://localhost:33080/api/tasks/query/{task_id}"

# 查看应用日志
tail -f logs/app.log

S3连接问题


# 测试S3连接
curl "http://your-minio:9000"

# 验证S3配置
docker exec mediaconvert-api env | grep S3

监控和维护


# 查看容器状态
docker ps
docker stats mediaconvert-api

# 查看日志
docker logs -f mediaconvert-api
tail -f logs/app.log

# 重启服务
docker restart mediaconvert-api

# 更新镜像
docker pull docker.cnb.cool/l8ai/document/mediaconvert:latest
docker-compose down && docker-compose up -d

文档和资源

完整文档

📖 API接口文档 - 详细的API使用指南
🔄 任务处理流程 - 任务处理机制说明
🐳 Docker部署指南 - 生产环境部署指南
☁️ S3/MinIO使用指南 - 对象存储配置指南

在线API文档

启动服务后，访问以下地址查看交互式API文档：

Swagger UI: http://localhost:33080/docs
ReDoc: http://localhost:33080/redoc

支持的文件格式

音频格式

MP3, WAV, M4A, FLAC, AAC, OGG

视频格式

MP4, AVI, MOV, MKV, WEBM, FLV

文件大小限制

S3存储：无限制（推荐大文件使用）
本地上传：2GB
HTTP URL：取决于源服务器

技术架构

系统组件

FastAPI: Web框架和API服务
OpenAI Whisper: 语音转文本引擎
FFmpeg: 音视频处理引擎
SQLite: 任务数据存储
S3/MinIO: 对象存储支持
Docker: 容器化部署

存储结构


ai-file bucket/
├── {原始bucket}/
│   └── {文件路径(去掉后缀)}/
│       ├── whisper/              # 语音转文本结果
│       │   ├── transcription_result.json
│       │   ├── transcription_text.txt
│       │   ├── transcription_timeline.txt
│       │   └── transcription_subtitles.srt
│       └── ffmpeg/               # 转码结果
│           └── output_file.mp3

测试验证

本地测试

启动服务：


python main.py

测试转码任务：


# 移动端转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcode",
    "transcode_type": "mobile_high"
  }'

# PC端转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcode",
    "transcode_type": "pc_high"
  }'

# 4K转码
curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcode",
    "transcode_type": "4k_standard"
  }'

测试转录任务：


curl -X POST "http://localhost:33080/api/tasks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "s3://gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人.mp4",
    "task_type": "transcribe",
    "language": "zh"
  }'

查询任务状态：


curl "http://localhost:33080/api/tasks/query/{task_id}"

测试结果

✅ 完整功能验证（2025-08-09）

测试环境：

GPU: NVIDIA L20 (44.53GB显存)
测试文件: 145MB，131分钟视频
所有任务均成功完成并上传到S3

测试结果：

移动端视频转码 ✅ 成功
- 处理时间: 8.5分钟
- 输出文件: 189MB
- 访问URL: http://shenben.club:9000/ai-file/gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人/ffmpeg/20250710133938-象山教科研中心智能体培训-视频-1-说话人_mobile-high.mp4
PC端视频转码 ✅ 成功
- 处理时间: 8.2分钟
- 输出文件: 189MB
- 访问URL: http://shenben.club:9000/ai-file/gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人/ffmpeg/20250710133938-象山教科研中心智能体培训-视频-1-说话人_pc-high.mp4
4K高清视频转码 ✅ 成功
- 处理时间: 约15分钟
- 输出文件: 约300MB
- 访问URL: http://shenben.club:9000/ai-file/gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人/ffmpeg/20250710133938-象山教科研中心智能体培训-视频-1-说话人_4k-standard.mp4
音频文本转录 ✅ 成功
- 处理时间: 13.8分钟
- 生成文件: 4个（JSON、TXT、时间轴、SRT字幕）
- 访问URL:
  - http://shenben.club:9000/ai-file/gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人/whisper/transcription_result.json
  - http://shenben.club:9000/ai-file/gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人/whisper/transcription_text.txt
  - http://shenben.club:9000/ai-file/gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人/whisper/transcription_timeline.txt
  - http://shenben.club:9000/ai-file/gaojiaqi/20250710133938-象山教科研中心智能体培训-视频-1-说话人/whisper/transcription_subtitles.srt

验证要点：

✅ S3文件下载正常
✅ GPU加速转码正常
✅ Whisper语音转录正常
✅ S3文件上传正常
✅ 文件复用机制正常
✅ 并发处理能力正常
✅ 系统性能稳定

版本信息

当前版本: v1.0.7
Docker镜像: docker.cnb.cool/l8ai/document/mediaconvert:latest
API版本: v1.0
最后更新: 2025-08-09

许可证

Apache License 2.0

贡献

欢迎提交 Issue 和 Pull Request！

开发环境设置


# 克隆仓库
git clone https://github.com/your-repo/mediaconvert-api.git
cd mediaconvert-api

# 安装依赖
pip install -r requirements.txt -i https://mirrors.cloud.tencent.com/pypi/simple

# 启动开发服务
python start.py

提交规范

功能开发：feat: 添加新功能
问题修复：fix: 修复问题
文档更新：docs: 更新文档
性能优化：perf: 性能优化

35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen

京ICP备11018762号-111