Cloudflare Streamで動画のサムネイルを表示してみた [Animated GIFにも対応]

アップロード済みの動画コンテンツに対して指定のURLにアクセスすることでサムネイルが取得できます。JPEG画像のほかアニメーションGIFをサポートし、URLパラメータで微調整が可能です。Stream Playerのポスターとして使えます。
2023.03.01

はじめに

清水です。Cloudflareの動画配信プラットフォームのサービスCloudflare Streamで動画のサムネイルを表示する方法を確認してみたのでまとめてみたいと思います。通常の1枚のJPEG画像でサムネイルを生成するほか、アニメーションGIFでのサムネイル生成にも対応しています。なお、サムネイルの生成対象はすでにCloudflare Streamにアップロード済みのVODコンテンツを対象に行いました。以下Cloudflare Streamのドキュメントを参考に進めます。

JPEG画像のサムネイルを生成する

URLでJPEGサムネイル画像を生成する

まずは基本的な、1枚のJPEG画像のサムネイルを生成してみます。ズバリ以下URLへのアクセスでサムネイル画像の生成が可能です。

  • https://customer-{CODE}.​cloudflarestream.com/$VIDEOID/thumbnails/thumbnail.jpg

ここで、customer-{CODE}部分はアカウント固有のサブドメインです。(参考: Cloudflare Streamでアカウント固有のサブドメインを利用するようになりました | DevelopersIO$VIDEOIDは動画コンテンツごとに割り振られるVideo IDですね、それぞれダッシュボード上の以下などから確認が可能です。

後述する方法でStream Playerへサムネイルとして埋め込むほか、Webブラウザから直接サムネイルのURLへアクセスすることで確認も可能です。

またURLクエリ文字列を用いてサムネイル画像を調整することも可能です。以下のパラメータをサポートしています。(詳細はDisplay thumbnails · Cloudflare Stream docsを参照ください。)

  • time
    • 動画コンテンツのどの時間からサムネイル画像を生成するか。デフォルトは0s8m5m2sなどと指定。
  • height
    • 生成するサムネイル画像の高さ。デフォルトは640
  • width
    • 生成するサムネイル画像の幅。デフォルトは640
  • fit
    • 指定したサムネイル画像の高さと幅が元の動画コンテンツと一致しない場合の対処方法指定。
    • 指定可能なパラメータは以下4種類。(デフォルトはcrop
      • crop
        • 指定されたサイズに収まらない部分をカット
      • clip
        • フレーム全体を保持し、指定されたサイズ内で画像サイズを縮小
      • scale
        • 与えられたサイズに合うように画像をゆがめる
      • fill v - フレーム全体を保持し、要求されたサイズの残りの部分を黒の背景で埋める

例えば以下は、動画コンテンツの開始から10秒経過の時点から、高さ720ピクセルでサムネイルを生成した例です。クエリパラメータとして?time=20s&height=720を付与しました。

JPEGサムネイル画像をStream Playerで使う

このサムネイル画像、Cloudflare Streamで提供している動画プレイヤーであるStream Playerで再生前のポスターとして利用可能です。以下iframe要素でWebページに埋め込む例ですが、src属性で指定する動画コンテンツのURLのあとに?poster=に続けてサムネイル画像のURLを、パーセントエンコーディング(URLエンコード)したものを追加します。

<iframe
  src="https://customer-{CODE}.​cloudflarestream.com/$VIDEOID/iframe?poster=https%3A%2F%2Fcustomer-%7BCODE%7D.%E2%80%8Bcloudflarestream.com%2F%24VIDEOID%2Fthumbnails%2Fthumbnail.jpg"
  style="border: none"
  height="720"
  width="1280"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>

以下、クエリパラメータで生成するサムネイル画像の場所(時間、開始から20秒の時点)とサイズ(高さ720ピクセル)を指定してHTMLとして埋め込んでみた例です。

stream-player-with-thumbnails.html

<html>
  <head>
    <title>Stream Player with Thumbnails</title>
  </head>
  <body>
    <iframe
       src="https://customer-0jyoxxxxxxxxxxxx.cloudflarestream.com/9a35xxxxxxxxxxxxxxxxxxxxxxxxxxxx/iframe?poster=https%3A%2F%2Fcustomer-0jyoxxxxxxxxxxxx.cloudflarestream.com%2F9a35xxxxxxxxxxxxxxxxxxxxxxxxxxxx%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D20s%26height%3D720"
       style="border: none"
       height="720"
       width="1280"
       allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
       allowfullscreen="true"
       >
    </iframe>
  </body>
</html>

なお、こちらのiframe埋め込み用コードは同等のものがダッシュボードの動画コンテンツページ、「Embed」のタグからも取得することができます。Poster部分でTimestampを選択してにサムネイル画像の取得時間を入力しましょう。

アニメーションGIFなサムネイルを生成する

URLでアニメーションGIFなサムネイルを生成する

基本的なJPEG画像のサムネイル生成が確認できたところで、続いていはアニメーションGIFなサムネイルの生成をしてみましょう。こちらもズバリ以下URLへのアクセスで生成ができます。拡張子を.jpgから.gifに変更するだけですね。

  • https://customer-{CODE}.​cloudflarestream.com/$VIDEOID/thumbnails/thumbnail.gif

customer-{CODE}ならびに$VIDEOIDは先ほどと同様です、ダッシュボードなどから確認しましょう。

またJPEG画像のサムネイルと同様、URLクエリ文字列を用いて生成されるアニメーションGIFサムネイルを調整することが可能です。パラメータは以下となっています。アニメーションGIF特有のパラメータとしてdurationfpsがある点を抑えておきましょう。(詳細はDisplay thumbnails · Cloudflare Stream docsを参照ください。)

  • time
    • 動画コンテンツのどの時間からサムネイルを生成するか。デフォルトは0s8m5m2sなどと指定。
  • height
    • 生成するサムネイルの高さ。デフォルトは640
  • width
    • 生成するサムネイルの幅。デフォルトは640
  • fit
    • 指定したサムネイルの高さと幅が元の動画コンテンツと一致しない場合の対処方法指定。
    • 指定可能なパラメータは以下4種類。(デフォルトはcrop
      • crop
        • 指定されたサイズに収まらない部分をカット
      • clip
        • フレーム全体を保持し、指定されたサイズ内で画像サイズを縮小
      • scale
        • 与えられたサイズに合うように画像をゆがめる
      • fill
        • フレーム全体を保持し、要求されたサイズの残りの部分を黒の背景で埋める
  • duration
    • アニメーションGIFの時間の長さ(尺)。デフォルトは5s
  • fps
    • アニメーションGIFのフレームレート。デフォルトは8

以下、実際に生成してみたアニメーションGIFなサムネイルです。GIF画像として本ブログエントリに貼り付けてみました。パラメータとして?time=20s&height=360&duration=2s&fps=4を指定しています。

  • https://customer-0jyoxxxxxxxxxxxx.cloudflarestream.com/9a35xxxxxxxxxxxxxxxxxxxxxxxxxxxx/thumbnails/thumbnail.gif?time=20s&height=360&duration=2s&fps=4

なお、画像貼り付けが可能なようにheightdurationfpsなどを調整しています。より高い解像度のサムネイルも生成可能ですが、例えば高さheightは600ピクセルまでといった制限があるようです。以下は?height=720&duration=4sというパラメータで高さを720ピクセルとしようとしてみましたがエラーとなってしまったケースとなります。

アニメーションGIFなサムネイルをStream Playerで使う

アニメーションGIFなサムネイル、通常のJPEGサムネイルと同様にStream Playerのポスターとして利用可能です。使い方も同様に、src属性で指定する動画コンテンツのURLのあとに?poster=に続けてGIFアニメーションサムネイルのURLをパーセントエンコーディングしたものを追加します。

以下、HTMLとして埋め込んでみた例となります。

stream-player-with-thumbnails-animated-gif.html

<html>
  <head>
    <title>Stream Player with Thumbnails</title>
  </head>
  <body>
    <iframe
       src="https://customer-0jyoxxxxxxxxxxxx.cloudflarestream.com/9a35xxxxxxxxxxxxxxxxxxxxxxxxxxxx/iframe?poster=https%3A%2F%2Fcustomer-0jyoxxxxxxxxxxxx.cloudflarestream.com%2F9a35xxxxxxxxxxxxxxxxxxxxxxxxxxxx%2Fthumbnails%2Fthumbnail.gif%3Ftime%3D20s%26amp%3Bheight%3D360%26amp%3Bduration%3D2s%26amp%3Bfps%3D4"
       style="border: none"
       height="720"
       width="1280"
       allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
       allowfullscreen="true"
       >
    </iframe>
  </body>
</html>

スクリーンショットだと少しわかりにくいのですが、再生ボタンを押す前にアニメーションGIFで動きのある画がみれます。

まとめ

Cloudflare Streamで動画のサムネイルを表示する方法について確認してみました。JPEG画像でのサムネイルのほか、GIFアニメーションでのサムネイルも利用可能です。サムネイルはVideo IDをもとにしたURLに対してクエリパラメータを付与、調整することでサムネイルを生成する時点やサムネイルの大きさなどを指定可能です。またStream Playerでポスターとして使用することができます。上手に活用することでコンテンツをよりリッチにして、動画自体を再生させる前にユーザのコンテンツに対する期待値を向上させることができるのではないでしょうか。