如何使用 Encoder Standard 通过 REST 来生成缩略图How to generate thumbnails using Encoder Standard with REST

媒体服务徽标 v3media services logo v3


可以使用 Media Encoder Standard 以 JPEGPNGBMP 图像文件格式从输入视频生成一个或多个缩略图。You can use Media Encoder Standard to generate one or more thumbnails from your input video in JPEG, PNG, or BMP image file formats.

建议阅读如何通过自定义转换进行编码 - REST,以熟悉自定义转换。It is recommended that you become familiar with custom transforms by reading How to encode with a custom transform - REST.

缩略图参数Thumbnail parameters

你应设置以下参数:You should set the following parameters:

  • 开始 - 输入视频中开始生成缩略图的位置。start - The position in the input video from where to start generating thumbnails. 该值可以是 ISO 8601 格式(例如,PT05S 表示在 5 秒处开始),可以是帧计数(例如,10 表示在第 10 帧处开始),也可以是流持续时间的相对值(例如,10% 表示在流持续时间的 10% 处开始)。The value can be in ISO 8601 format (For example, PT05S to start at 5 seconds), or a frame count (For example, 10 to start at the 10th frame), or a relative value to stream duration (For example, 10% to start at 10% of stream duration). 还支持宏 {Best},它会指示编码器从视频的前几秒中选择最佳的缩略图,并且无论“步距”和“范围”的其他设置如何,都只会生成一个缩略图。Also supports a macro {Best}, which tells the encoder to select the best thumbnail from the first few seconds of the video and will only produce one thumbnail, no matter what other settings are for Step and Range. 默认值为宏 {Best}。The default value is macro {Best}.
  • 步距 - 生成缩略图的间隔。step - The intervals at which thumbnails are generated. 该值可以是 ISO 8601 格式(例如,PT05S 表示每 5 秒一张图片),可以是帧计数(例如,30 表示每 30 帧一张图片),也可以是流持续时间的相对值(例如,10% 表示流持续时间的每 10% 一张图片)。The value can be in ISO 8601 format (for example, PT05S for one image every 5 seconds), or a frame count (for example, 30 for one image every 30 frames), or a relative value to stream duration (for example, 10% for one image every 10% of stream duration). 步距值将影响第一个生成的缩略图,该缩略图可能与在转换预设开始时间指定的缩略图不完全相同。Step value will affect the first generated thumbnail, which may not be exactly the one specified at transform preset start time. 导致这一情况的原因在于编码器,编码器尝试在开始时间和开始时间的步距位置之间选择最佳缩略图作为第一输出。This is due to the encoder, which tries to select the best thumbnail between start time and step position from start time as the first output. 由于默认值为 10%,因此意味着如果流的持续时间较长,第一个生成的缩略图可能会与开始时指定的缩略图相距甚远。As the default value is 10%, it means that if the stream has long duration, the first generated thumbnail might be far away from the one specified at start time. 如果希望第一个缩略图接近开始时间,则尝试为步距选择一个合理的值;如果在开始时间处只需要一个缩略图,则将范围值设置为 1。Try to select a reasonable value for step if the first thumbnail is expected be close to start time, or set the range value to 1 if only one thumbnail is needed at start time.
  • 范围 - 与输入视频中转换预设开始时间相关的位置,在该位置停止生成缩略图。range - The position relative to transform preset start time in the input video at which to stop generating thumbnails. 该值可以是 ISO 8601 格式(例如,PT5M30S 表示从开始时间起 5 分 30 秒停止),也可以是帧计数(例如,300 表示在开始时间帧的第 300 帧停止)。The value can be in ISO 8601 format (For example, PT5M30S to stop at 5 minutes and 30 seconds from start time), or a frame count (For example, 300 to stop at the 300th frame from the frame at start time. 如果该值为 1,则表示在开始时间处仅生成一个缩略图),或者是相对于流持续时间的相对值(例如,50% 表示从开始时间起的流持续时间的一半处停止)。If this value is 1, it means only producing one thumbnail at start time), or a relative value to the stream duration (For example, 50% to stop at half of stream duration from start time). 默认值是 100%,这表示在流的末尾处停止。The default value is 100%, which means to stop at the end of the stream.
  • - 编码器要生成的输出图像层的集合。layers - A collection of output image layers to be produced by the encoder.

“单个 PNG 文件”预设示例Example of a "single PNG file" preset

使用以下 JSON 预设可以基于输入视频的前几秒内容生成单个输出 PNG 文件,其中的编码器会尽力尝试查找“相关的”帧。The following JSON preset can be used to produce a single output PNG file from the first few seconds of the input video, where the encoder makes a best-effort attempt at finding an "interesting" frame. 请注意,输出图像尺寸已设置为 100%,这意味着,这些尺寸与输入视频的尺寸匹配。Note that the output image dimensions have been set to 100%, meaning these match the dimensions of the input video. 另请注意需要如何指定“Outputs”中“Format”设置,以匹配“Codecs”节中“PngLayers”的用法。Note also how the "Format" setting in "Outputs" is required to match the use of "PngLayers" in the "Codecs" section.

{
    "properties": {
        "description": "Basic Transform using a custom encoding preset for thumbnails",
        "outputs": [
            {
                "onError": "StopProcessingJob",
                "relativePriority": "Normal",
                "preset": {
                    "@odata.type": "#Microsoft.Media.StandardEncoderPreset",
                    "codecs": [
                        {
                            "@odata.type": "#Microsoft.Media.PngImage",
                            "stretchMode": "AutoSize",
                            "start": "{Best}",
                            "step": "25%",
                            "range": "80%",
                            "layers": [
                                {
                                    "width": "50%",
                                    "height": "50%"
                                }
                            ]
                        }
                    ],
                    "formats": [
                        {
                            "@odata.type": "#Microsoft.Media.Mp4Format",
                            "filenamePattern": "Video-{Basename}-{Label}-{Bitrate}{Extension}",
                            "outputFiles": []
                        },
                        {
                            "@odata.type": "#Microsoft.Media.PngFormat",
                            "filenamePattern": "Thumbnail-{Basename}-{Index}{Extension}"
                        }
                    ]
                }
            }
        ]
    }
}

“一系列 JPEG 图像”预设的示例Example of a "series of JPEG images" preset

可以使用以下 JSON 预设在输入时间线的 5%、15% ... 95% 时间戳处生成一组 10 幅图像,其中的图像大小指定为输入视频的四分之一。The following JSON preset can be used to produce a set of 10 images at timestamps of 5%, 15%, …, 95% of the input timeline, where the image size is specified to be one quarter that of the input video.

JSON 预设JSON preset

{
  "Version": 1.0,
  "Codecs": [
    {
      "JpgLayers": [
        {
          "Quality": 90,
          "Type": "JpgLayer",
          "Width": "25%",
          "Height": "25%"
        }
      ],
      "Start": "5%",
      "Step": "10%",
      "Range": "96%",
      "Type": "JpgImage"
    }
  ],
  "Outputs": [
    {
      "FileName": "{Basename}_{Index}{Extension}",
      "Format": {
        "Type": "JpgFormat"
      }
    }
  ]
}

“在特定时间戳处生成一个图像”预设示例Example of a "one image at a specific timestamp" preset

可以使用以下 JSON 预设在输入视频的 30 秒标记处生成单个 JPEG 图像。The following JSON preset can be used to produce a single JPEG image at the 30-second mark of the input video. 此预设预期输入视频的持续时间超过 30 秒(否则作业失败)。This preset expects the input video to be more than 30 seconds in duration (else the job fails).

JSON 预设JSON preset

{
  "Version": 1.0,
  "Codecs": [
    {
      "JpgLayers": [
        {
          "Quality": 90,
          "Type": "JpgLayer",
          "Width": "25%",
          "Height": "25%"
        }
      ],
      "Start": "00:00:30",
      "Step": "1",
      "Range": "1",
      "Type": "JpgImage"
    }
  ],
  "Outputs": [
    {
      "FileName": "{Basename}_{Index}{Extension}",
      "Format": {
        "Type": "JpgFormat"
      }
    }
  ]
}

“不同分辨率的缩略图”预设示例Example of a "thumbnails at different resolutions" preset

可使用以下预设在同一个任务中的不同解决方案下生成缩略图。The following preset can be used to generate thumbnails at different resolutions in one task. 在该示例中,当输入时间线位于 5%、15%、…、95% 时,编码器会在输入视频分辨率的 100% 处和 50% 处各生成一个图像。In the example, at positions 5%, 15%, …, 95% of the input timeline, the encoder generates two images – one at 100% of the input video resolution and the other at 50%.

请注意 FileName 中 {Resolution} 宏的使用;它指示在生成输出图像的文件名时,编码器要使用在预设的“编码”部分中所指定的宽度和高度。Note the use of {Resolution} macro in the FileName; it indicates to the encoder to use the width and height that you specified in the Encoding section of the preset while generating the file name of the output images. 这还能够帮助轻松区分不同图像。This also helps you distinguish between the different images easily.

JSON 预设JSON preset

{
  "Version": 1.0,
  "Codecs": [
    {
      "JpgLayers": [
{
  "Quality": 90,
  "Type": "JpgLayer",
  "Width": "100%",
  "Height": "100%"
},
{
  "Quality": 90,
  "Type": "JpgLayer",
  "Width": "50%",
  "Height": "50%"
}

      ],
      "Start": "5%",
      "Step": "10%",
      "Range": "96%",
      "Type": "JpgImage"
    }
  ],
  "Outputs": [
    {
      "FileName": "{Basename}_{Resolution}_{Index}{Extension}",
      "Format": {
"Type": "JpgFormat"
      }
    }
  ]
}

在编码时生成缩略图的示例Example of generating a thumbnail while encoding

上述所有示例都在讨论如何提交仅生成图像的编码任务,但还可以将视频/音频编码与缩略图生成结合起来。While all of the above examples have discussed how you can submit an encoding task that only produces images, you can also combine video/audio encoding with thumbnail generation. 以下的 JSON 预设指示 Encoder Standard 在编码过程中生成一个缩略图。The following JSON preset tells Encoder Standard to generate a thumbnail during encoding.

JSON 预设JSON preset

有关架构的信息,请参阅文。For information about schema, see this article.

{
  "Version": 1.0,
  "Codecs": [
    {
      "KeyFrameInterval": "00:00:02",
      "SceneChangeDetection": "true",
      "H264Layers": [
        {
          "Profile": "Auto",
          "Level": "auto",
          "Bitrate": 4500,
          "MaxBitrate": 4500,
          "BufferWindow": "00:00:05",
          "Width": 1280,
          "Height": 720,
          "ReferenceFrames": 3,
          "EntropyMode": "Cabac",
          "AdaptiveBFrame": true,
          "Type": "H264Layer",
          "FrameRate": "0/1"

        }
      ],
      "Type": "H264Video"
    },
    {
      "JpgLayers": [
        {
          "Quality": 90,
          "Type": "JpgLayer",
          "Width": "100%",
          "Height": "100%"
        }
      ],
      "Start": "{Best}",
      "Type": "JpgImage"
    },
    {
      "Channels": 2,
      "SamplingRate": 48000,
      "Bitrate": 128,
      "Type": "AACAudio"
    }
  ],
  "Outputs": [
    {
      "FileName": "{Basename}_{Index}{Extension}",
      "Format": {
        "Type": "JpgFormat"
      }
    },
    {
      "FileName": "{Basename}_{Resolution}_{VideoBitrate}.mp4",
      "Format": {
        "Type": "MP4Format"
      }
    }
  ]
}

后续步骤Next steps

使用 .NET 生成缩略图Generate thumbnails using .NET