ビデオスナップショットからのスプライト生成とは - Object Storage Service

カスケードスタイルシート (CSS) スプライトは、複数のイメージを 1 つのイメージファイルにまとめたものです。スプライトは、主に Web サイトのパフォーマンス最適化とフロントエンド開発に使用されます。CSS の background-position プロパティを使用して HTTP リクエストを削減することで、ページの読み込み速度とユーザーエクスペリエンスを向上させることができます。スプライト生成機能を使用して、ビデオフレームを抽出し、それらをスプライトに結合できます。このトピックでは、ビデオスナップショットからスプライトを生成するためのパラメーターについて説明し、例を示します。

使用上の注意

ビデオスナップショットからのスプライト生成は、非同期処理 (x-oss-async-process) のみをサポートします。
ビデオのタイムスタンプまたはストリームが破損している場合、スプライトの生成が失敗したり、生成されるイメージの数が正しくなかったりすることがあります。
この機能を使用する前に、IMM プロジェクトをアタッチする必要があります。コンソールまたは API を使用してプロジェクトをアタッチする方法の詳細については、「クイックスタート」および「AttachOSSBucket - OSS バケットのアタッチ」をご参照ください。
匿名アクセスは拒否されます。
この機能を使用するには、必要な権限が必要です。詳細については、「権限」をご参照ください。

パラメーター

アクション: video/sprite

次の表にパラメーターを示します。

パラメーター	タイプ	必須	説明
ss	int	いいえ	スプライトを生成する開始時刻。単位: ミリ秒。有効な値: 0 (デフォルト): ビデオの先頭から。 0 より大きい値: 指定されたミリ秒から。
f	string	はい	スプライトの出力フォーマット。有効な値: jpg png 説明最大解像度は 16384px × 16384px です。
m	string	いいえ	スプライトサブイメージのフレームキャプチャモード。デフォルト値は inter です。有効な値: inter: 固定間隔モード。フレームキャプチャの間隔は inter パラメーターによって決定され、キャプチャされるフレームの数は num パラメーターによって決定されます。 key: キーフレームモード。ソースビデオから IDR フレームのみがキャプチャされます。キャプチャされるフレームの数は num パラメーターによって決定されます。このモードでは inter パラメーターは無効です。 avg: 平均間隔モード。num パラメーターに基づいて、平均間隔でフレームがキャプチャされます。このモードでは inter パラメーターは無効です。 dhash: dhash モード。フレームは固定間隔でキャプチャされます。時間の経過とともにコンテンツがしきい値を超えて変化する最も重要なフレームが選択されます。フレームキャプチャの間隔は inter パラメーターによって決定され、キャプチャされるフレームの数は num パラメーターによって決定され、しきい値は thr パラメーターによって決定されます。
thr	int	いいえ	dhash モードでのスプライトサブイメージのフレームキャプチャのしきい値。しきい値が大きいほど、キャプチャされるフレームの数は少なくなります。有効な値: [0, 100]。デフォルト値: 0。説明このパラメーターは dhash モードでのみ有効です。 dhash モードはしきい値に敏感です。このパラメーターを 25 以下の値に設定し、必要に応じて調整してください。
num	int	いいえ	スプライトサブイメージ用にキャプチャするフレーム数。デフォルト値: 0。これは、キャプチャされるフレーム数に制限がないことを示します。デフォルト値は、フレームキャプチャモードによって意味が異なります: 固定間隔モード: ビデオの最後までフレームがキャプチャされます。キーフレームモード: ビデオの最後までフレームがキャプチャされます。平均間隔モード: このパラメーターを 0 に設定することはできません。 dhash モード: コンテンツの変更が thr パラメーターの値を超えるすべてのフレームがキャプチャされます。重要ビデオの長さとフレームキャプチャのパラメーターにより、実際にキャプチャされるフレームの数は指定された値よりも少なくなる場合があります。
inter	int	いいえ	スプライトサブイメージのフレームをキャプチャする間隔。単位: ミリ秒。デフォルト値: 0。これは、すべてのビデオフレームがキャプチャされることを示します。説明このパラメーターの値がソースビデオのフレーム間隔 (フレームレートの逆数) よりも小さい場合、フレームはソースビデオのフレーム間隔に基づいてキャプチャされます。
sw	int	いいえ	スプライトサブイメージの幅。単位: px。有効な値: [32, 4096]。デフォルトでは、サブイメージの幅はソースビデオの幅と同じです。
sh	int	いいえ	スプライトサブイメージの高さ。単位: px。有効な値: [32, 4096]。デフォルトでは、サブイメージの高さはソースビデオの高さと同じです。
psw	int	いいえ	ソースビデオの幅に対するスプライトサブイメージの幅のパーセンテージ。有効な値: (0, 200]。デフォルト値: 100。説明 [sw] と [psw] の両方のパラメーターを設定した場合、[psw] パラメーターは有効になりません。
psh	int	いいえ	ソースビデオの高さに対するスプライトサブイメージの高さのパーセンテージ。有効な値: (0, 200]。デフォルト値: 100。説明 [sh] と [psh] の両方のパラメーターを設定した場合、[psh] パラメーターは有効になりません。
scaletype	string	いいえ	スケーリングモード。有効な値: crop: イメージをスケーリングしてトリミングします。 stretch (デフォルト): イメージをスペースに合わせて引き伸ばします。 fill: イメージをスケーリングし、黒枠を保持します。 fit: 黒枠なしでイメージを比例的にスケーリングします。
tw	int	いいえ	スプライトの各行のサブイメージの数。デフォルト値: 6。有効な値: [1, 100]。
th	int	いいえ	スプライトの各列のサブイメージの数。デフォルト値: 6。有効な値: [1, 100]。
pad	int	いいえ	スプライト内のサブイメージ間のパディング。単位: px。デフォルト値: 2。有効な値: [0, 100]。
margin	int	いいえ	スプライトのエッジ周りのページの余白。単位: px。デフォルト値: 2。有効な値: [0, 100]。

説明

sys/saveas および notify パラメーターは、ビデオスナップショットからスプライトを生成する際にも使用されます。詳細については、「名前を付けて保存」および「通知」をご参照ください。

REST API の使用

重要

出力スプライトのストレージパスに .jpg などのファイル拡張子を指定しない場合、システムは自動的にファイル名に _0_1.jpg などの序数を追加します。ファイル拡張子を指定した場合、最後のスプライトのみが保存されます。したがって、ファイル拡張子を指定しないことをお勧めします。序数をカスタマイズするには、ApsaraVideo Media Processing 関連の変数を使用します。

2 秒ごとに 1 フレームをキャプチャしてビデオ全体のスプライトを生成する

2 秒ごとに 1 フレームをキャプチャして、ビデオ全体のスプライトを生成できます。各スプライトには 3 × 3 グリッドのサブイメージが含まれ、各サブイメージの解像度は 200 × 150 です。

スプライト情報

ソースファイル
- ビデオ名: example.mkv
メッセージ通知
- 通知用の MNS トピック: example-mns-topic
出力構成
- フレームキャプチャ情報
  - スプライトフォーマット: jpg
  - サブイメージのフレームキャプチャ間隔: 2 s
  - サブイメージのグリッドレイアウト: 3 × 3
  - サブイメージの解像度: 200 × 150
  - サブイメージのスケーリングモード: crop
  - サブイメージ間のパディング: 0
  - サブイメージ周りのページの余白: 0
- ファイルストレージパス
  - JPG ファイル: oss://outbucket/outobjprefix-%d.jpg

例

// example.mkv ビデオファイルからスプライトを生成します。
POST /exmaple.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
 
x-oss-async-process=video/sprite,f_jpg,sw_200,sh_150,inter_2000,tw_3,th_3,pad_0,margin_0|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

指定された数に基づいて均等な間隔でフレームをキャプチャしてスプライトを生成する

サブイメージがビデオ全体を均等にカバーする 10 × 10 のスプライトを生成できます。これにより、フロントエンドのロジックが簡素化されます。

スプライト情報

ソースファイル
- ビデオ名: example.mkv
メッセージ通知
- 通知用の MNS トピック: example-mns-topic
出力構成
- フレームキャプチャ情報
  - スプライトフォーマット: jpg
  - サブイメージのフレームキャプチャモード: avg
  - サブイメージのグリッドレイアウト: 10 × 10
  - サブイメージの解像度: ソースビデオの 1/10
  - サブイメージのスケーリングモード: fit
  - サブイメージ間のパディング: 4
  - サブイメージ周りのページの余白: 5
- ファイルストレージパス
  - JPG ファイル: oss://outbucket/outobjprefix-%d.jpg

例

// example.mkv ビデオファイルからスプライトを生成します。
POST /exmaple.mkv?x-oss-async-process HTTP/1.1
Host: video-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
 
x-oss-async-process=video/sprite,f_jpg,m_avg,psw_10,psh_10,scaletype_fit,tw_10,th_10,pad_4,margin_5|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LXtpbmRleH0ue2F1dG9leHR9Cg/notify,topic_ZXhhbXBsZS1tbnMtdG9waWMK

SDK の使用

ビデオスナップショットからの非同期スプライト生成は、Java、Python、および Go の SDK でのみサポートされています。詳細については、「SDK のインストール」をご参照ください。

Java

OSS SDK for Java 3.17.4 以降が必要です。

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.AsyncProcessObjectRequest;
import com.aliyun.oss.model.AsyncProcessObjectResult;
import com.aliyuncs.exceptions.ClientException;

import java.util.Base64;

public class Demo {
    public static void main(String[] args) throws ClientException {
        // バケットが配置されているリージョンのエンドポイントを指定します。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // エンドポイントに対応するリージョン ID を指定します。例: cn-hangzhou。
        String region = "cn-hangzhou";
        // 環境変数からアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // バケット名を指定します。
        String bucketName = "examplebucket";
        // スプライトのファイル名を指定します。
        String targetKey = "example.jpg";
        // ソースビデオファイルの名前を指定します。
        String sourceKey = "src.mp4";

        // OSSClient インスタンスを作成します。
        // OSSClient インスタンスが不要になったら、shutdown メソッドを呼び出してリソースを解放します。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // ビデオからスプライトを生成するためのパラメーターを設定します。
            String style = String.format("video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0");
            // 非同期処理命令を作成します。
            String bucketEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bucketName.getBytes());
            String targetEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(targetKey.getBytes());
            String process = String.format("%s|sys/saveas,b_%s,o_%s/notify,topic_QXVkaW9Db252ZXJ0", style, bucketEncoded, targetEncoded);
            // AsyncProcessObjectRequest オブジェクトを作成します。
            AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
            // 非同期処理タスクを実行します。
            AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
            System.out.println("EventId: " + response.getEventId());
            System.out.println("RequestId: " + response.getRequestId());
            System.out.println("TaskId: " + response.getTaskId());

        } finally {
            // OSSClient をシャットダウンします。
            ossClient.shutdown();
        }
    }
}

Python

Python SDK 2.18.4 以降が必要です。

# -*- coding: utf-8 -*-
import base64
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 環境変数から一時的なアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    # バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
    # エンドポイントに対応するリージョン ID を指定します。例: cn-hangzhou。
    region = 'cn-hangzhou'

    # バケット名を指定します。
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

    # ソースビデオファイルの名前を指定します。
    source_key = 'src.mp4'

    # スプライトのファイル名を指定します。
    target_key = 'example.jpg'

    # ビデオからスプライトを生成するためのパラメーターを設定します。
    animation_style = 'video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0'

    # ストレージパスと Base64 エンコードされたバケット名およびオブジェクト名を含む処理命令を作成します。
    bucket_name_encoded = base64.urlsafe_b64encode('examplebucket'.encode()).decode().rstrip('=')
    target_key_encoded = base64.urlsafe_b64encode(target_key.encode()).decode().rstrip('=')
    process = f"{animation_style}|sys/saveas,b_{bucket_name_encoded},o_{target_key_encoded}/notify,topic_QXVkaW9Db252ZXJ0"

    try:
        # 非同期処理タスクを実行します。
        result = bucket.async_process_object(source_key, process)
        print(f"EventId: {result.event_id}")
        print(f"RequestId: {result.request_id}")
        print(f"TaskId: {result.task_id}")
    except Exception as e:
        print(f"Error: {e}")


if __name__ == "__main__":
    main()

Go

Go SDK 3.0.2 以降が必要です。

package main

import (
    "encoding/base64"
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "log"
)

func main() {
    // 環境変数から一時的なアクセス資格情報を取得します。このサンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // OSSClient インスタンスを作成します。
    // yourEndpoint をバケットのエンドポイントに設定します。たとえば、バケットが中国 (杭州) リージョンにある場合、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。実際にご利用のリージョンに基づいてエンドポイントを指定してください。
    // yourRegion を Alibaba Cloud リージョン ID に設定します。例: cn-hangzhou。
    client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // バケット名を指定します。例: examplebucket。
    bucketName := "examplebucket"

    bucket, err := client.Bucket(bucketName)
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }

    // ソースビデオファイルの名前を指定します。
    sourceKey := "src.mp4"
    // 出力スプライトファイルの名前を指定します。
    targetKey := "example.jpg"

    // ビデオからスプライトを生成するためのパラメーターを設定します。
    animationStyle := "video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0"

    // ストレージパスと Base64 エンコードされたバケット名およびオブジェクト名を含む処理命令を作成します。
    bucketNameEncoded := base64.URLEncoding.EncodeToString([]byte(bucketName))
    targetKeyEncoded := base64.URLEncoding.EncodeToString([]byte(targetKey))
    process := fmt.Sprintf("%s|sys/saveas,b_%v,o_%v/notify,topic_QXVkaW9Db252ZXJ0", animationStyle, bucketNameEncoded, targetKeyEncoded)

    // 非同期処理タスクを実行します。
    result, err := bucket.AsyncProcessObject(sourceKey, process)
    if err != nil {
    log.Fatalf("Failed to async process object: %s", err)
    }

    fmt.Printf("EventId: %s\n", result.EventId)
    fmt.Printf("RequestId: %s\n", result.RequestId)
    fmt.Printf("TaskId: %s\n", result.TaskId)
}