服务端 API 文档

截图

最近更新时间:2021-07-26 10:47:51

截图是截取视频特定位置的图像并生成图片的过程,是一种离线任务。云点播提供以下类型的截图:

  • 指定时间点截图:指定一组时间点,截取视频在这些时间点的图像。
  • 采样截图:按相同的时间间隔对视频截取多张图。
  • 截取一张图作封面:指定一个时间点截图,将其 URL 作为媒资系统中该视频的封面。
  • 截雪碧图:按相同的时间间隔对视频截取多张小图,然后组装成若干大图(即雪碧图)。

使用截图功能,可以满足如下应用场景:

  • 为视频生成封面:使用视频的截图作为视频的封面。
  • 缩略图:雪碧图是嵌套了多个小图(即缩略图)的大图,常用来表示一个视频的概要。
  • 播放预览:雪碧图配合 VTT 文件,可以用来实现播放器进度条上的预览效果。

截图模板

截图的目标规格,包含截图文件格式、截图宽高等参数。云点播使用截图模板表示截图参数集合,通过截图模板,可以指定以下截图相关参数。

时间点截图模板

时间点截图模板,用于“指定时间点截图”和“截取一张图作封面”两种任务。

参数 说明
格式(Format) 截图文件的输出格式,目前仅支持 JPG。
宽度(Width) 截图宽度,范围是128px - 4096px。
高度(Height) 截图高度,范围是128px - 4096px。
填充方式(FillType) 当截图的宽高比与原始视频的宽高比不一致时,对截图的处理方式,即为“填充”。一般有以下几种填充方式:
  • 拉伸:对图片进行拉伸,填满整个图片,可能导致图片被“压扁”或者“拉长”。
  • 留黑:保持图片宽高比不变,边缘剩余部分使用黑色填充。
  • 留白:保持图片宽高比不变,边缘剩余部分使用白色填充。
  • 高斯模糊:保持图片宽高比不变,边缘剩余部分使用高斯模糊化后填充。
  • 针对常见的规格,云点播提供 预置时间点截图模板。另外,您还可以通过控制台创建和管理自定义截图模板,具体操作请参见 模板设置

    采样截图模板

    采样截图模板,用于“采样截图”任务。

    参数 说明
    格式(Format) 截图文件的输出格式,目前仅支持 JPG。
    宽度(Width) 截图宽度,范围是128px - 4096px。
    高度(Height) 截图高度,范围是128px - 4096px。
    采样方式(SampleType) 采样方式分为两种:
  • 按百分比采样:例如按照5%为间隔采样,生成截图张数将为20张。
  • 按时间间隔采样:例如按照10s为间隔采样,截图张数取决于视频的时长。
  • 采样间隔(Interval) 采样的间隔长度:
  • 如果按百分比采样,间隔是百分比。
  • 如果按时间间隔采样,间隔是多少秒。
  • 填充方式(FillType) 当截图的宽高比与原始视频的宽高比不一致时,对截图的处理方式,即为“填充”。一般有以下几种填充方式:
  • 拉伸:对图片进行拉伸,填满整个图片,可能导致图片被“压扁”或者“拉长”。
  • 留黑:保持图片宽高比不变,边缘剩余部分使用黑色填充。
  • 留白:保持图片宽高比不变,边缘剩余部分使用白色填充。
  • 高斯模糊:保持图片宽高比不变,边缘剩余部分使用高斯模糊化后填充。
  • 针对常见的规格,云点播提供了 预置采样截图模板。另外,您还可以通过控制台创建和管理自定义截图模板,具体操作请参见 模板设置

    雪碧图模板

    雪碧图模板,用于“截雪碧图”任务。

    参数 说明
    格式(Format) 雪碧图文件的输出格式,目前仅支持 JPG。
    小图宽度(Width) 雪碧图中小图的宽度。
    小图高度(Height) 雪碧图中小图的高度。
    小图行数(Rows) 一张大图中有多少行小图。
    小图列数(Columns) 一张大图中有多少列小图。
    采样方式(SampleType) 小图采样方式,目前仅支持按照时间间隔采样。
    采样间隔(Interval) 小图采样的间隔,即隔多久采样一张小图。
    注意:

    • Width × Columns 需要在128px - 4096px之间(即大图宽度在128px - 4096px之间)。
    • Height × Rows 需要在128px - 4096px之间(即大图高度在128px - 4096px之间)。

    针对常见的规格,云点播提供了 预置雪碧图模板。另外,您还可以通过控制台创建和管理自定义截图模板,具体操作请参见 模板设置

    任务发起

    发起截图任务,有“通过服务端 API 直接发起”,“通过控制台直接发起”和“上传时指定要执行的任务”三种方式。具体请参照视频处理的 任务发起

    以下是各种方式发起截图任务的说明:

    结果获取

    发起截图任务后,您可以通过异步等待 结果通知 和同步进行 任务查询 两种方式获取截图任务的执行结果。下面是发起截图任务后,普通回调方式下结果通知的示例(省略了值为 null 的字段):

    {
      "EventType":"ProcedureStateChanged",
      "ProcedureStateChangeEvent":{
          "TaskId":"1256768367-Procedure-2e1af2456351812be963e309cc133403t0",
          "Status":"FINISH",
          "FileId":"5285890784246869930",
          "FileName":"动物世界",
          "FileUrl":"http://1256768367.vod2.myqcloud.com/xxx/xxx/AtUCmy6gmIYA.mp4",
          "MetaData":{
              "AudioDuration":60,
              "AudioStreamSet":[
                  {
                      "Bitrate":383854,
                      "Codec":"aac",
                      "SamplingRate":48000
                  }
              ],
              "Bitrate":1021028,
              "Container":"mov,mp4,m4a,3gp,3g2,mj2",
              "Duration":60,
              "Height":480,
              "Rotate":0,
              "Size":7700180,
              "VideoDuration":60,
              "VideoStreamSet":[
                  {
                      "Bitrate":637174,
                      "Codec":"h264",
                      "Fps":23,
                      "Height":480,
                      "Width":640
                  }
              ],
              "Width":640
          },
          "MediaProcessResultSet":[
              {
                  "Type":"SnapshotByTimeOffset",
                  "SnapshotByTimeOffsetTask":{
                      "Status":"SUCCESS",
                      "ErrCode":0,
                      "Message":"",
                      "Input":{
                          "Definition":10,
                          "Definition":[3, 6, 9]
                      },
                      "Output":{
                          "Definition":10,
                          "PicInfoSet": [
                              {
                                  "TimeOffset":3,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx1.jpg"
                              },
                              {
                                  "TimeOffset":6,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx2.jpg"
                              },
                              {
                                  "TimeOffset":9,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx3.jpg"
                              }
                          ]
                      }
                  }
              },
              {
                  "Type":"SampleSnapshot",
                  "SampleSnapshotTask":{
                      "Status":"SUCCESS",
                      "ErrCode":0,
                      "Message":"",
                      "Input":{
                          "Definition":10
                      },
                      "Output":{
                          "Definition":10,
                          "PicInfoSet": [
                              {
                                  "TimeOffset":6,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx1.jpg"
                              },
                              {
                                  "TimeOffset":12,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx2.jpg"
                              },
                              {
                                  "TimeOffset":18,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx3.jpg"
                              },
                              {
                                  "TimeOffset":24,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx4.jpg"
                              },
                              {
                                  "TimeOffset":30,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx5.jpg"
                              },
                              {
                                  "TimeOffset":36,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx6.jpg"
                              },
                              {
                                  "TimeOffset":42,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx7.jpg"
                              },
                              {
                                  "TimeOffset":48,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx8.jpg"
                              },
                              {
                                  "TimeOffset":54,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx9.jpg"
                              },
                              {
                                  "TimeOffset":60,
                                  "Url":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx10.jpg"
                              }
                          ]
                      }
                  }
              },
              {
                  "Type":"ImageSprites",
                  "ImageSpriteTask":{
                      "Status":"SUCCESS",
                      "ErrCode":0,
                      "Message":"",
                      "Input":{
                          "Definition":10
                      },
                      "Output":{
                          "Definition":10,
                          "Height":80,
                          "Width":142,
                          "TotalCount":1,
                          "ImageUrlSet":[
                              "http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx1.jpg"
                          ],
                          "WebVttUrl":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx.vtt"
                      }
                  }
              },
              {
                  "Type":"CoverBySnapshot",
                  "CoverBySnapshotTask":{
                      "Status":"SUCCESS",
                      "ErrCode":0,
                      "Message":"",
                      "Input":{
                          "Definition":10,
                          "PositionType":"Time",
                          "PositionValue":0
                      },
                      "Output":{
                          "CoverUrl":"http://1256768367.vod2.myqcloud.com/xxx/xxx/xxx.jpg"
                      }
                  }
              }
          ],
          "TasksPriority":0,
          "TasksNotifyMode":""
      }
    }

    回调结果中,ProcedureStateChangeEvent.MediaProcessResultSetTypeSnapshotByTimeOffsetSampleSnapshotImageSpritesCoverBySnapshot的结果,分别代表指定时间点截图、采样截图、截雪碧图和截取一张图作封面几种截图任务。

    目录