Pembuatan sprite - Object Storage Service - Alibaba Cloud Documentation Center

CSS (Cascading Style Sheets) sprite adalah kumpulan gambar yang digabungkan menjadi satu file gambar. Sprite terutama digunakan untuk mengoptimalkan performa situs web dan pengembangan frontend. Anda dapat menggunakan properti CSS background-position untuk mengurangi jumlah permintaan HTTP, sehingga mempercepat pemuatan halaman dan meningkatkan pengalaman pengguna. Fitur pembuatan sprite memungkinkan Anda mengekstraksi frame video dan menggabungkannya menjadi satu sprite. Topik ini menjelaskan parameter untuk membuat sprite dari tangkapan video serta menyediakan contoh penggunaannya.

Catatan penggunaan

Pembuatan sprite dari tangkapan video hanya mendukung pemrosesan asinkron (x-oss-async-process).
Pembuatan sprite dapat gagal atau menghasilkan jumlah gambar yang tidak sesuai jika cap waktu video atau aliran rusak.
Sebelum menggunakan fitur ini, Anda harus menyambungkan Proyek IMM. Untuk informasi lebih lanjut tentang cara menyambungkan proyek melalui Konsol atau menggunakan API, lihat Quick Start dan AttachOSSBucket - Attach an OSS bucket.
Akses anonim akan ditolak.
Anda harus memiliki izin yang diperlukan untuk menggunakan fitur ini. Untuk informasi lebih lanjut, lihat permissions.

Parameter

Action: video/sprite

Tabel berikut menjelaskan parameter-parameter tersebut.

Parameter	Tipe	Wajib	Deskripsi
ss	int	Tidak	Waktu mulai untuk membuat sprite. Satuan: milidetik. Nilai yang valid: 0 (default): dari awal video. Nilai lebih besar dari 0: dari milidetik yang ditentukan.
f	string	Ya	Format output sprite. Nilai yang valid: jpg png Catatan Resolusi maksimum adalah 16384px × 16384px.
m	string	Tidak	Mode pengambilan frame untuk sub-gambar sprite. Nilai default adalah inter. Nilai yang valid: inter: mode interval tetap. Interval pengambilan frame ditentukan oleh parameter inter, dan jumlah frame yang diambil ditentukan oleh parameter num. key: mode keyframe. Hanya frame IDR yang diambil dari video sumber. Jumlah frame yang diambil ditentukan oleh parameter num. Parameter inter tidak berlaku dalam mode ini. avg: mode interval rata-rata. Frame diambil pada interval rata-rata berdasarkan parameter num. Parameter inter tidak berlaku dalam mode ini. dhash: mode dhash. Frame diambil pada interval tetap. Frame paling signifikan yang perubahan kontennya melebihi ambang batas dipilih. Interval pengambilan frame ditentukan oleh parameter inter, jumlah frame yang diambil ditentukan oleh parameter num, dan ambang batas ditentukan oleh parameter thr.
thr	int	Tidak	Ambang batas pengambilan frame untuk sub-gambar sprite dalam mode dhash. Semakin besar nilai ambang batas, semakin sedikit frame yang diambil. Nilai yang valid: [0, 100]. Nilai default: 0. Catatan Parameter ini hanya berlaku dalam mode dhash. Mode dhash sensitif terhadap ambang batas. Atur parameter ini ke nilai tidak lebih dari 25 dan sesuaikan sesuai kebutuhan.
num	int	Tidak	Jumlah frame yang akan diambil untuk sub-gambar sprite. Nilai default: 0, yang berarti tidak ada batasan jumlah frame yang diambil. Nilai default memiliki makna berbeda dalam mode pengambilan frame yang berbeda: Mode interval tetap: Frame diambil hingga akhir video. Mode keyframe: Frame diambil hingga akhir video. Mode interval rata-rata: Parameter ini tidak boleh diatur ke 0. Mode dhash: Semua frame yang perubahan kontennya melebihi nilai parameter thr diambil. Penting Jumlah aktual frame yang diambil mungkin lebih sedikit daripada nilai yang ditentukan karena panjang video dan parameter pengambilan frame.
inter	int	Tidak	Interval pengambilan frame untuk sub-gambar sprite. Satuan: milidetik. Nilai default: 0, yang berarti semua frame video diambil. Catatan Jika nilai parameter ini lebih kecil daripada interval frame (kebalikan dari laju frame) video sumber, frame diambil berdasarkan interval frame video sumber.
sw	int	Tidak	Lebar sub-gambar sprite. Satuan: px. Nilai yang valid: [32, 4096]. Secara default, lebar sub-gambar sama dengan lebar video sumber.
sh	int	Tidak	Tinggi sub-gambar sprite. Satuan: px. Nilai yang valid: [32, 4096]. Secara default, tinggi sub-gambar sama dengan tinggi video sumber.
psw	int	Tidak	Presentase lebar sub-gambar sprite relatif terhadap lebar video sumber. Nilai yang valid: (0, 200]. Nilai default: 100. Catatan Jika Anda mengatur kedua parameter sw dan psw, parameter psw akan diabaikan.
psh	int	Tidak	Presentase tinggi sub-gambar sprite relatif terhadap tinggi video sumber. Nilai yang valid: (0, 200]. Nilai default: 100. Catatan Jika Anda mengatur kedua parameter sh dan psh, parameter psh akan diabaikan.
scaletype	string	Tidak	Mode penskalaan. Nilai yang valid: crop: menskalakan dan memotong gambar. stretch (default): meregangkan gambar agar mengisi ruang. fill: menskalakan gambar dan mempertahankan bilah hitam. fit: menskalakan gambar secara proporsional tanpa bilah hitam.
tw	int	Tidak	Jumlah sub-gambar dalam setiap baris sprite. Nilai default: 6. Nilai yang valid: [1, 100].
th	int	Tidak	Jumlah sub-gambar dalam setiap kolom sprite. Nilai default: 6. Nilai yang valid: [1, 100].
pad	int	Tidak	Spasi antar sub-gambar dalam sprite. Satuan: px. Nilai default: 2. Nilai yang valid: [0, 100].
margin	int	Tidak	Margin di sekeliling tepi sprite. Satuan: px. Nilai default: 2. Nilai yang valid: [0, 100].

Catatan

Parameter sys/saveas dan notify juga digunakan saat Anda membuat sprite dari tangkapan video. Untuk informasi lebih lanjut, lihat Save As dan Notifications.

Gunakan REST API

Penting

Jika Anda tidak menentukan ekstensi file, seperti .jpg, dalam path penyimpanan untuk output sprite, sistem secara otomatis menambahkan angka ordinal ke nama file, misalnya _0_1.jpg. Jika Anda menentukan ekstensi file, hanya sprite terakhir yang disimpan. Oleh karena itu, kami menyarankan agar Anda tidak menentukan ekstensi file. Untuk menyesuaikan angka ordinal, gunakan variabel terkait ApsaraVideo Media Processing.

Buat sprite untuk seluruh video dengan mengambil satu frame setiap 2 detik

Anda dapat membuat sprite untuk seluruh video dengan mengambil satu frame setiap 2 detik. Setiap sprite berisi grid sub-gambar berukuran 3 × 3, dan setiap sub-gambar memiliki resolusi 200 × 150.

Informasi sprite

File sumber
- Nama video: example.mkv
Notifikasi pesan
- Topik MNS untuk notifikasi: example-mns-topic
Konfigurasi output
- Informasi pengambilan frame
  - Format sprite: jpg
  - Interval pengambilan frame untuk sub-gambar: 2 detik
  - Tata letak grid sub-gambar: 3 × 3
  - Resolusi sub-gambar: 200 × 150
  - Mode penskalaan sub-gambar: crop
  - Spasi antar sub-gambar: 0
  - Margin di sekeliling sub-gambar: 0
- Path penyimpanan file
  - File JPG: oss://outbucket/outobjprefix-%d.jpg

Contoh

// Buat sprite dari file video 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

Buat sprite dengan mengambil frame pada interval merata berdasarkan jumlah yang ditentukan

Anda dapat membuat sprite berukuran 10 × 10 di mana sub-gambar secara merata mencakup seluruh video. Hal ini menyederhanakan logika frontend.

Informasi sprite

File sumber
- Nama video: example.mkv
Notifikasi pesan
- Topik MNS untuk notifikasi: example-mns-topic
Konfigurasi output
- Informasi pengambilan frame
  - Format sprite: jpg
  - Mode pengambilan frame untuk sub-gambar: avg
  - Tata letak grid sub-gambar: 10 × 10
  - Resolusi sub-gambar: 1/10 dari video sumber
  - Mode penskalaan sub-gambar: fit
  - Spasi antar sub-gambar: 4
  - Margin di sekeliling sub-gambar: 5
- Path penyimpanan file
  - File JPG: oss://outbucket/outobjprefix-%d.jpg

Contoh

// Buat sprite dari file video 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

Gunakan SDK

Pembuatan sprite asinkron dari tangkapan video hanya didukung oleh SDK untuk Java, Python, dan Go. Untuk informasi lebih lanjut, lihat Install SDKs.

Java

Diperlukan OSS SDK for Java versi 3.17.4 atau lebih baru.

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 {
        // Tentukan endpoint wilayah tempat bucket berada.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Tentukan ID wilayah yang sesuai dengan endpoint. Contoh: cn-hangzhou.
        String region = "cn-hangzhou";
        // Peroleh kredensial akses dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Tentukan nama bucket.
        String bucketName = "examplebucket";
        // Tentukan nama file sprite.
        String targetKey = "example.jpg";
        // Tentukan nama file video sumber.
        String sourceKey = "src.mp4";

        // Buat instance OSSClient.
        // Setelah instance OSSClient tidak digunakan lagi, panggil metode shutdown untuk melepaskan sumber dayanya.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Konfigurasikan parameter untuk membuat sprite dari video.
            String style = String.format("video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0");
            // Buat instruksi pemrosesan asinkron.
            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);
            // Buat objek AsyncProcessObjectRequest.
            AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
            // Jalankan tugas pemrosesan asinkron.
            AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
            System.out.println("EventId: " + response.getEventId());
            System.out.println("RequestId: " + response.getRequestId());
            System.out.println("TaskId: " + response.getTaskId());

        } finally {
            // Matikan OSSClient.
            ossClient.shutdown();
        }
    }
}

Python

Diperlukan Python SDK versi 2.18.4 atau lebih baru.

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

def main():
    # Mendapatkan kredensial akses sementara dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan bahwa variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    # Tentukan titik akhir wilayah tempat bucket berada. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur titik akhir ke https://oss-cn-hangzhou.aliyuncs.com.
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
    # Tentukan ID wilayah yang sesuai dengan titik akhir tersebut. Contoh: cn-hangzhou.
    region = 'cn-hangzhou'

    # Tentukan nama bucket.
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

    # Tentukan nama file video sumber.
    source_key = 'src.mp4'

    # Tentukan nama file sprite.
    target_key = 'example.jpg'

    # Konfigurasikan parameter untuk menghasilkan sprite dari video.
    animation_style = 'video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0'

    # Buat instruksi pemrosesan yang mencakup path penyimpanan serta nama bucket dan nama objek yang dikodekan 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:
        # Jalankan tugas pemrosesan asinkron.
        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

Diperlukan Go SDK versi 3.0.2 atau lebih baru.

package main

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

func main() {
    // Peroleh kredensial akses temporary dari variabel lingkungan. Sebelum menjalankan kode contoh ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah dikonfigurasi.
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // Buat instance OSSClient.
    // Atur yourEndpoint ke endpoint bucket. Misalnya, jika bucket berada di wilayah Tiongkok (Hangzhou), atur endpoint ke https://oss-cn-hangzhou.aliyuncs.com. Sesuaikan endpoint berdasarkan wilayah Anda.
    // Atur yourRegion ke ID wilayah Alibaba Cloud. Contoh: 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)
    }
    // Tentukan nama bucket. Contoh: examplebucket.
    bucketName := "examplebucket"

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

    // Tentukan nama file video sumber.
    sourceKey := "src.mp4"
    // Tentukan nama file sprite output.
    targetKey := "example.jpg"

    // Konfigurasikan parameter untuk membuat sprite dari video.
    animationStyle := "video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0"

    // Buat instruksi pemrosesan yang mencakup path penyimpanan dan nama bucket serta nama objek yang di-encode 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)

    // Jalankan tugas pemrosesan asinkron.
    result, err := bucket.AsyncProcessObject(sourceKey, process)
    if err != nil {
    log.Fatalf("Gagal memproses objek secara asinkron: %s", err)
    }

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