313 lines
8.8 KiB
Markdown
313 lines
8.8 KiB
Markdown
GMapiServer
|
||
|
||
GMapiServer 是一个基于 Python 和 Flask 构建的高性能 API 服务器，支持通过 URL 输入文件并输出下载链接，提供同步和异步两种处理模式。内置缓存自动清理机制（默认保留 2 小时），支持多种工具接口调用，包括实时任务状态查询和视频帧处理功能。
|
||
|
||
🚀 项目简介
|
||
|
||
GMapiServer 是一个轻量级、模块化的 API 服务框架，旨在为开发者提供以下核心功能：
|
||
|
||
• URL 输入与输出：支持通过 URL 提交文件，返回生成文件的下载链接。
|
||
|
||
• 异步处理：任务在后台异步执行，不阻塞主进程，提升服务器并发性能。
|
||
|
||
• 自动缓存清理：内置定时清理机制，自动删除过期的缓存文件（包括输出文件），默认保留时间 2 小时。
|
||
|
||
• 多工具接口集成：集成 FFmpeg 和 Sanjuuni 工具接口，支持在线调用。
|
||
|
||
• 实时任务状态：提供任务状态查询接口，支持日志实时推送。
|
||
|
||
• 视频帧提取：支持从视频中提取指定分辨率、帧率的图片帧，可打包为二进制格式。
|
||
|
||
🛠️ 技术栈
|
||
|
||
• 编程语言: Python
|
||
|
||
• Web 框架: Flask
|
||
|
||
• 异步处理: 基于 threading
|
||
|
||
• 缓存清理: 定时任务
|
||
|
||
• 依赖管理: pip
|
||
|
||
🧩 支持的接口
|
||
|
||
1. FFmpeg 工具接口
|
||
|
||
• 功能: 在线调用 FFmpeg 工具进行视频/音频处理（如转码、裁剪、合并等）。
|
||
|
||
• 接口文档: https://www.liulikeji.cn/archives/FFmpegApi
|
||
|
||
• 同步接口: POST /api/ffmpeg
|
||
|
||
• 异步接口: POST /api/ffmpeg/async
|
||
|
||
2. Sanjuuni 工具接口
|
||
|
||
• 功能: 在线调用 https://github.com/MCJack123/sanjuuni/tree/master（具体功能需参考其官方文档）。
|
||
|
||
• 接口文档: https://www.liulikeji.cn/archives/SanjuuniApi
|
||
|
||
• 同步接口: POST /api/sanjuuni
|
||
|
||
• 异步接口: POST /api/sanjuuni/async
|
||
|
||
3. 视频帧提取接口
|
||
|
||
• 功能: 从视频中提取指定分辨率、帧率的图片帧，支持强制分辨率调整和填充，支持B站BV号。
|
||
|
||
• 异步接口: POST /api/video_frame/async
|
||
|
||
• 参数:
|
||
|
||
• video_url: 视频文件 URL (或使用 video_bv 参数替代)
|
||
|
||
• video_bv: B站视频BV号 (自动转换为URL)
|
||
|
||
• w: 输出宽度
|
||
|
||
• h: 输出高度
|
||
|
||
• fps: 输出帧率 (默认: 30)
|
||
|
||
• force_resolution: 是否强制调整分辨率 (默认: false)
|
||
|
||
• pad_to_target: 是否填充到目标分辨率 (默认: false)
|
||
|
||
• 返回示例:
|
||
```json
|
||
{
|
||
"task_id": "abc12345",
|
||
"status_url": "http://localhost:5000/api/task/abc12345",
|
||
"message": "任务已创建，请使用状态URL查询进度"
|
||
}
|
||
```
|
||
|
||
• 实时任务状态响应（处理中）:
|
||
```json
|
||
{
|
||
"task_id": "abc12345",
|
||
"status": "running",
|
||
"progress": 50,
|
||
"create_time": 1770393314.1262555,
|
||
"start_time": 1770393314.1262555,
|
||
"end_time": null,
|
||
"type": "video_frame",
|
||
"result": {
|
||
"audio_urls": {
|
||
"audio_dfpwm_url": "/frames/abc12345/audio.dfpwm",
|
||
"audio_dfpwm_left_url": "/frames/abc12345/audio_left.dfpwm",
|
||
"audio_dfpwm_right_url": "/frames/abc12345/audio_right.dfpwm"
|
||
},
|
||
"current_frames": 180,
|
||
"total_frames": 6059,
|
||
"output_resolution": {"w": 640, "h": 360},
|
||
"frame_urls": [
|
||
"/frames/abc12345/frame_000001.png",
|
||
"/frames/abc12345/frame_000002.png",
|
||
// ... 当前已生成的帧
|
||
]
|
||
},
|
||
"total_logs": 15,
|
||
"last_index": 15,
|
||
"new_logs": ["日志1", "日志2"]
|
||
}
|
||
```
|
||
|
||
• 任务完成时结果:
|
||
```json
|
||
{
|
||
"task_id": "abc12345",
|
||
"status": "completed",
|
||
"progress": 100,
|
||
"create_time": 1770393314.1262555,
|
||
"start_time": 1770393314.1262555,
|
||
"end_time": 1770393391.1024792,
|
||
"type": "video_frame",
|
||
"result": {
|
||
"audio_urls": {
|
||
"audio_dfpwm_url": "/frames/abc12345/audio.dfpwm",
|
||
"audio_dfpwm_left_url": "/frames/abc12345/audio_left.dfpwm",
|
||
"audio_dfpwm_right_url": "/frames/abc12345/audio_right.dfpwm"
|
||
},
|
||
"duration_seconds": 303.019,
|
||
"current_frames": 6059,
|
||
"total_frames": 6059,
|
||
"fps": 20,
|
||
"output_resolution": {"w": 640, "h": 360},
|
||
"frame_urls": [
|
||
"/frames/abc12345/frame_000001.png",
|
||
"/frames/abc12345/frame_000002.png",
|
||
// ... 所有生成帧
|
||
]
|
||
},
|
||
"total_logs": 164,
|
||
"last_index": 164,
|
||
"new_logs": ["最后日志"]
|
||
}
|
||
```
|
||
|
||
4. 异步任务状态查询
|
||
|
||
• 功能: 查询异步任务状态和进度，支持日志实时推送。
|
||
|
||
• 接口: GET /api/task/<task_id>
|
||
|
||
• 返回字段:
|
||
|
||
• status: 任务状态（pending/running/completed/error）
|
||
|
||
• progress: 进度百分比
|
||
|
||
• new_logs: 新增的日志条目
|
||
|
||
• result: 完成后的结果（包含下载URL）
|
||
|
||
• error: 错误信息（如果状态为error）
|
||
|
||
5. 帧打包接口
|
||
|
||
• 功能: 将多个帧图片打包为二进制格式，便于批量下载。
|
||
|
||
• 接口: POST /api/framepack
|
||
|
||
• 参数:
|
||
|
||
• urls: 帧图片URL列表，格式为 /frames/<job_id>/<filename>.png
|
||
|
||
• 返回: 二进制流，格式为帧数(4字节) + 各帧数据
|
||
|
||
6. 文件下载接口
|
||
|
||
• 功能: 下载处理完成的文件。
|
||
|
||
• 接口: GET /download/<file_id>/<filename>
|
||
|
||
7. 任务列表查询
|
||
|
||
• 功能: 列出所有任务状态（调试用）。
|
||
|
||
• 接口: GET /api/tasks
|
||
|
||
8. 健康检查
|
||
|
||
• 功能: 服务健康检查。
|
||
|
||
• 接口: GET /health
|
||
|
||
📦 部署与使用
|
||
|
||
1. 安装依赖
|
||
|
||
pip install -r requirements.txt
|
||
|
||
|
||
2. 启动服务器
|
||
|
||
python main.py --port 5000
|
||
|
||
|
||
3. 异步任务使用示例
|
||
|
||
创建异步FFmpeg任务
|
||
|
||
curl -X POST http://localhost:5000/api/ffmpeg/async \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"input_url": "http://example.com/input.mp4",
|
||
"output_format": "mp4",
|
||
"args": ["-c:v", "libx264", "-crf", "23"]
|
||
}'
|
||
|
||
|
||
查询任务状态
|
||
|
||
curl http://localhost:5000/api/task/<task_id>
|
||
|
||
|
||
4. 指定公网地址
|
||
|
||
在相应工具模块中配置下载URL：
|
||
# sanjuuni_utils.py
|
||
return {
|
||
'status': 'success',
|
||
'download_url': f"http://ffmpeg.liulikeji.cn/download/{output_id}/{output_filename}", # 外部访问地址
|
||
'file_id': output_id,
|
||
'temp_dir': temp_dir
|
||
}
|
||
|
||
# ffmpeg_utils.py
|
||
return {
|
||
'status': 'success',
|
||
'download_url': f"http://ffmpeg.liulikeji.cn/download/{output_id}/{output_filename}", # 外部访问地址
|
||
'file_id': output_id,
|
||
'temp_dir': temp_dir
|
||
}
|
||
|
||
|
||
⏰ 自动缓存清理配置
|
||
|
||
• 默认保留时间: 2 小时
|
||
|
||
• 自定义配置:
|
||
# 在logging_config.py文件中修改缓存清理时间
|
||
CLEANUP_INTERVAL = 3600 # 清理临时文件的间隔(秒)
|
||
FILE_EXPIRY = 7200 # 文件过期时间(秒)
|
||
|
||
|
||
🔥 视频帧实时进度功能
|
||
|
||
GMapiServer 的视频帧提取功能支持实时进度跟踪，让客户端可以在任务处理过程中实时获取已生成的帧并进行下载。
|
||
|
||
• 实时帧进度跟踪: 自动解析FFmpeg输出的进度信息，实时更新当前帧数
|
||
• 智能进度计算: 基于帧数自动计算转换进度（20-80%）
|
||
• 音频预处理: 音频在视频处理前提取，客户端可提前下载音频文件
|
||
• 实时URL返回: 在处理过程中不断返回已生成的帧URL列表
|
||
|
||
## 优势特性
|
||
|
||
1. **减少等待时间**: 客户端无需等待整个视频处理完成
|
||
2. **并行下载**: 可以在转换过程中并行下载已生成的帧
|
||
3. **实时反馈**: 用户可以看到实时处理进度和日志
|
||
4. **资源优化**: 避免了"堵车"效应，提高系统并发能力
|
||
|
||
## 使用建议
|
||
|
||
• 客户端可以轮询 `/api/task/<task_id>` 接口获取最新状态
|
||
• 通过检查 `result.frame_urls` 列表长度变化确定新生成的帧
|
||
• 音频文件可以立即下载（音频处理优先级更高）
|
||
|
||
|
||
🔧 异步任务处理流程
|
||
|
||
1. 任务创建: 客户端提交任务请求，服务器返回任务ID和状态查询URL
|
||
2. 后台处理: 任务在独立线程中执行，不阻塞主进程
|
||
3. 状态查询: 客户端可轮询状态接口获取任务进度和实时日志
|
||
4. 结果获取: 任务完成后可通过状态接口或文件下载接口获取结果
|
||
5. 自动清理: 任务结果文件在指定时间后自动清理
|
||
|
||
⚠️ 注意事项
|
||
|
||
1. 文件合法性: 请确保上传文件符合法律法规，不得用于非法用途。
|
||
2. 缓存文件: 系统会自动清理过期文件，请及时下载生成的输出文件。
|
||
3. 异步任务: 异步任务结果在服务器重启后会丢失，请及时处理完成的任务。
|
||
4. 资源限制: 视频帧提取和转码操作可能消耗较多CPU和内存资源。
|
||
|
||
📝 贡献与反馈
|
||
|
||
欢迎提交 Issue 或 Pull Request！
|
||
如有问题，请联系：[xingluo01@liulikeji.cn] 或 [qq:180877430]
|
||
|
||
📁 项目结构
|
||
|
||
|
||
GMapiServer/
|
||
├── main.py # 主程序入口
|
||
├── shared_utils.py # 共享工具函数
|
||
├── ffmpeg_utils.py # FFmpeg处理模块
|
||
├── sanjuuni_utils.py # Sanjuuni处理模块
|
||
├── video_frame_utils.py # 视频帧提取模块
|
||
├── file_cleanup.py # 文件清理模块
|
||
├── logging_config.py # 日志配置
|
||
├── requirements.txt # 依赖包列表
|
||
└── README.md # 项目说明文档 |