GMapiServer

GMapiServer 是一个基于 Python + Flask 的媒体处理 API 服务，支持通过远程 URL 拉取输入文件并返回处理结果。

项目当前提供：

• FFmpeg 同步与异步处理
• Sanjuuni 同步与异步处理
• 文本转二维码 Lua
• 视频拆帧、音频导出与 FramePack 打包
• 异步任务状态查询与增量日志
• 任务持久化恢复与自动缓存清理

适合用作轻量级媒体转换服务，或作为上层业务系统的媒体处理后端。

功能概览

FFmpeg

• 输入远程文件 URL
• 执行自定义 FFmpeg 参数
• 返回处理后文件下载地址

文档：docs/api/ffmpeg.md

Sanjuuni

• 调用 lib/sanjuuni/sanjuuni
• 支持 lua、nfp、raw、bimg、32vid
• 适合 ComputerCraft / CC 相关图像和视频转换场景

文档：docs/api/sanjuuni.md

项目参考：https://github.com/MCJack123/sanjuuni/tree/master

QR Lua

• 接收文本并生成 QR 对应的 Lua PixelBox 数据
• 支持前景色、背景色、边框、像素缩放和纠错等级参数

文档：docs/api/qr-lua.md

任务系统与视频拆帧

• 支持异步任务创建与状态轮询
• 支持视频拆帧和音频文件导出
• 支持 FramePack 二进制帧打包
• 支持视频帧缓存复用、访问续期和重启恢复

文档：docs/api/task-apis.md

CC / CraftOS-PC 用法

• 提供基于 FFmpeg API 的 dfpwm 转换示例
• 提供可直接在 CC / CraftOS-PC 使用的 Lua 代码

文档：docs/api/ffmpeg-cc.md

文档索引

• docs/api/ffmpeg.md：FFmpeg 接口文档
• docs/api/sanjuuni.md：Sanjuuni 接口文档
• docs/api/task-apis.md：同步、异步与任务查询文档
• docs/api/ffmpeg-cc.md：FFmpeg 的 CC / CraftOS-PC 使用文档
• docs/api/qr-lua.md：二维码 Lua 接口文档

技术栈

• Python
• Flask
• Requests
• yt-dlp
• qrcode
• threading
• FFmpeg
• Sanjuuni

项目结构

GMapiServer/
├── main.py                # Flask API 入口
├── start_server.py        # 启动脚本
├── shared_utils.py        # 任务/文件注册表与持久化逻辑
├── ffmpeg_utils.py        # FFmpeg 处理实现
├── sanjuuni_utils.py      # Sanjuuni 处理实现
├── video_frame_utils.py   # 视频拆帧与音频处理实现
├── file_cleanup.py        # 缓存清理线程
├── logging_config.py      # 日志配置
├── logo.py                # 启动 Logo
├── requirements.txt       # Python 依赖
├── docs/
│   └── api/
│       ├── ffmpeg.md
│       ├── sanjuuni.md
│       ├── qr-lua.md
│       ├── task-apis.md
│       └── ffmpeg-cc.md
├── lib/                   # 本地工具依赖
│   ├── ffmpeg/
│   └── sanjuuni/
├── data/                  # 运行期数据目录
└── README.md

环境要求

Python 依赖

pip install -r requirements.txt

当前 requirements.txt 包含：

Flask==3.1.0
Requests==2.32.3
yt-dlp
qrcode

本地工具依赖

项目代码会直接调用以下二进制文件：

• lib/ffmpeg/bin/ffmpeg
• lib/ffmpeg/bin/ffprobe
• lib/sanjuuni/sanjuuni

Windows 下会自动使用对应的 .exe 文件。

如果这些文件缺失，相关接口会执行失败。

启动方式

方式一：直接启动主程序

python main.py --port 5000

方式二：使用启动脚本

python start_server.py

默认监听地址：http://0.0.0.0:5000

运行目录说明

服务运行后会自动创建并使用以下目录：

• data/ffmpeg/：FFmpeg 输出缓存
• data/sanjuuni/：Sanjuuni 输出缓存
• data/videoframe/：视频帧与音频缓存
• data/state.json：运行中任务持久化状态
• data/task_id.json：已完成任务快照
• data/server.log：启动脚本日志文件

API 一览

类别	方法	路径	说明
FFmpeg	POST	/api/ffmpeg	同步 FFmpeg 处理
FFmpeg	POST	/api/ffmpeg/async	异步 FFmpeg 处理
Sanjuuni	POST	/api/sanjuuni	同步 Sanjuuni 处理
Sanjuuni	POST	/api/sanjuuni/async	异步 Sanjuuni 处理
QR Lua	POST	/api/qr_bimg	生成二维码 Lua
Video Frame	POST	/api/video_frame/async	异步视频拆帧
Task	GET	/api/task/<task_id>	查询任务状态
Download	GET	/download/<file_id>/<filename>	下载处理结果
Frame	GET	/frames/<job_id>/<filename>	访问帧图片或音频
FramePack	GET / POST	/api/framepack	打包多帧为二进制
Health	GET	/health	健康检查

详细参数、请求示例、任务轮询、CC 调用示例请直接查看 docs/api/ 下的对应文档。

缓存与清理

默认缓存保留时间为 2 小时。

当前 file_cleanup.py 默认配置：

CLEANUP_INTERVAL = 600
FILE_EXPIRY = 7200
TASK_EXPIRY = 7200
VIDEO_FRAME_CACHE_TTL = 7200

说明：

• 每 600 秒执行一次清理
• 文件记录默认 2 小时过期
• 任务记录默认 2 小时过期
• 视频帧缓存默认 2 小时过期

更完整的任务缓存、重启恢复、日志轮询和视频帧复用说明见：docs/api/task-apis.md

注意事项

1. 所有输入都依赖远程 URL 可访问。
2. 视频拆帧、转码、下载过程会消耗较多 CPU、磁盘和网络资源。
3. FFmpeg 和 Sanjuuni 的二进制文件需要提前准备好。
4. 输出文件和缓存会自动清理，若需要长期保存请及时下载或使用 NoDelete。
5. 当前下载返回中的 download_url 为固定域名拼接结果，私有化部署时通常需要按实际环境调整。

贡献与反馈

欢迎提交 Issue 或 Pull Request。

联系方式：

• 邮箱：xingluo01@liulikeji.cn
• QQ：180877430