shumc/imagorvideo

imagorvideo

概述

imagorvideo是一个通过ffmpeg提供视频缩略图功能的项目，基于https://github.com/cshum/imagor%E6%9E%84%E5%BB%BA%E2%80%94%E2%80%94imagor%E6%98%AF%E4%B8%80%E4%B8%AA%E7%94%A8Go%E5%92%8Clibvips%E7%BC%96%E5%86%99%E7%9A%84%E5%BF%AB%E9%80%9F%E3%80%81Docker%E5%B0%B1%E7%BB%AA%E7%9A%84%E5%9B%BE%E5%83%8F%E5%A4%84%E7%90%86%E6%9C%8D%E5%8A%A1%E5%99%A8%E3%80%82%E8%AF%A5%E9%A1%B9%E7%9B%AE%E4%BD%BF%E7%94%A8ffmpeg C绑定，通过RMSE直方图从视频中选择最佳帧，随后通过imagor的处理流程进行裁剪、缩放和滤镜等图像处理操作。

imagorvideo实现了ffmpeg的读取和seek I/O回调，结合imagor的https://github.com/cshum/imagor#loader-storage-and-result-storage%EF%BC%8C%E5%8E%9F%E7%94%9F%E6%94%AF%E6%8C%81HTTP(s)%E3%80%81%E6%96%87%E4%BB%B6%E7%B3%BB%E7%BB%9F%E3%80%81AWS S3和Google Cloud Storage。对于HTTP、S3等非可seek源，imagor通过内存或临时文件缓冲区模拟seek功能。同时，该项目也可作为imagor扩展的参考示例。

核心功能和特性

• 视频帧提取：使用ffmpeg C绑定，通过RMSE直方图分析从视频中选择最佳帧
• 图像处理流程：集成imagor的完整图像处理能力，支持https://github.com/cshum/imagor#image-endpoint%E5%92%8Chttps://github.com/cshum/imagor#filters
• 多存储源支持：兼容HTTP(s)、文件系统、AWS S3和Google Cloud Storage等存储源
• 模拟seek功能：对非可seek源（如HTTP、S3）通过内存或临时文件缓冲区模拟seek
• 扩展滤镜：提供frame、seek、max_frames等视频特定滤镜
• 元数据端点：快速提取视频元数据（尺寸、时长、FPS等），仅处理视频头部以提升速度

使用场景

• 视频平台生成视频缩略图
• 内容管理系统处理视频资源预览图
• 需要从远程存储（如S3）或HTTP视频源快速生成定制化缩略图的场景
• 需对视频帧进行裁剪、添加水印等后处理的应用

使用方法

快速启动

通过Docker运行imagorvideo服务：

bash
docker run -p 8000:8000 shumc/imagorvideo -imagor-unsafe

基础使用示例

原始视频地址：

http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4

生成缩略图示例：

# 添加标签和黄色填充的300px宽缩略图
http://localhost:8000/unsafe/300x0/7x7/filters:label(imagorvideo,-10,-7,15,yellow):fill(yellow)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4

# 指定1分59秒帧并添加标签的缩略图
http://localhost:8000/unsafe/300x0/0x0:0x14/filters:frame(1m59s):fill(yellow):label(imagorvideo,center,bottom,12,black,20)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4

# 使用0.6位置帧的缩略图
http://localhost:8000/unsafe/300x0/7x7/filters:frame(0.6):label(imagorvideo,10,-7,15,yellow):fill(yellow)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4

核心滤镜

imagorvideo支持以下视频特定滤镜，可与https://github.com/cshum/imagor#filters%E7%BB%93%E5%90%88%E4%BD%BF%E7%94%A8%EF%BC%9A

frame(n)

指定视频的精确位置或时间点提取帧，跳过自动最佳帧选择：

• 取值为0.0-1.0的浮点数（视频位置比例），例：frame(0.5)（中间位置）
• 取值为时间 duration，例：frame(5m1s)（5分1秒）、frame(200s)（200秒）

seek(n)

定位到指定位置附近的关键帧，然后通过RMSE直方图选择该区域内的最佳帧：

• 取值为0.0-1.0的浮点数（视频位置比例），例：seek(0.5)
• 取值为时间 duration，例：seek(5m1s)、seek(200s)

max_frames(n)

限制用于帧选择的最大帧数，数值越小处理速度越快。

frame(n) 与 seek(n) 的区别

frame(n)提供精确时间点的帧，但可能获取到黑帧等无效内容；seek(n)通过关键帧定位和最佳帧选择，可获取指定时间点附近的合理帧。例如：

获取视频5分钟处的帧（可能为黑帧）：

http://localhost:8000/unsafe/filters:frame(5m)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4

使用seek获取5分钟附近的最佳帧：

http://localhost:8000/unsafe/filters:seek(5m)/http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4

元数据端点

imagorvideo提供元数据端点，可提取视频的尺寸、时长、FPS等元数据，仅处理视频头部以提升速度。使用时在URL签名哈希后、图像处理操作前添加/meta：

示例

请求：

http://localhost:8000/unsafe/meta/https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/1080/Big_Buck_Bunny_1080_10s_30MB.mp4

响应：

jsonc
{
  "format": "mp4",
  "content_type": "video/mp4",
  "orientation": 1,
  "duration": 10000,
  "width": 1920,
  "height": 1080,
  "title": "Big Buck Bunny, Sunflower version",
  "artist": "Blender Foundation 2008, Janus Bager Kristensen 2013",
  "fps": 30,
  "has_video": true,
  "has_audio": false
}

配置选项

imagorvideo的特定配置选项：