Un sprite CSS (Cascading Style Sheets) regroupe plusieurs images dans un seul fichier image. Les sprites optimisent principalement les performances des sites web et le développement frontend. Grâce à la propriété background-position du CSS, vous réduisez les requêtes HTTP, ce qui améliore la vitesse de chargement des pages et l'expérience utilisateur. La fonctionnalité de génération de sprites extrait des images vidéo et les assemble en un sprite. Cette rubrique présente les paramètres de génération de sprites à partir d'images instantanées vidéo et propose des exemples.
Remarques
La génération de sprites à partir d'images instantanées vidéo prend uniquement en charge le traitement asynchrone (
x-oss-async-process).Si l'horodatage ou le flux vidéo est corrompu, la génération du sprite peut échouer ou produire un nombre incorrect d'images.
Avant d'utiliser cette fonctionnalité, vous devez associer un projet IMM. Pour savoir comment associer un projet depuis la console ou via une API, consultez les rubriques Démarrage rapide et AttachOSSBucket - Associer un bucket OSS.
Paramètres
Action : video/sprite
Le tableau suivant décrit les paramètres.
|
Paramètre |
Type |
Obligatoire |
Description |
|
ss |
int |
Non |
Heure de début de la génération du sprite. Unité : milliseconde. Valeurs valides :
|
|
f |
string |
Oui |
Format de sortie du sprite. Valeurs valides :
Remarque
La résolution maximale est de 16 384 px × 16 384 px. |
|
m |
string |
Non |
Mode de capture des images pour les sous-images du sprite. La valeur par défaut est
|
|
thr |
int |
Non |
Seuil de capture des images pour les sous-images du sprite en mode dhash. Plus le seuil est élevé, moins il y a d'images capturées. Valeurs valides : [0, 100]. Valeur par défaut : 0. Remarque
Ce paramètre n'est valide qu'en mode dhash. Le mode dhash est sensible au seuil. Définissez ce paramètre sur une valeur inférieure ou égale à 25 et ajustez-la si nécessaire. |
|
num |
int |
Non |
Nombre d'images à capturer pour les sous-images du sprite. Valeur par défaut : 0, ce qui signifie qu'il n'y a aucune limite sur le nombre d'images capturées. La valeur par défaut a des significations différentes selon les modes de capture :
Important
Le nombre réel d'images capturées peut être inférieur à la valeur spécifiée en raison de la durée de la vidéo et des paramètres de capture. |
|
inter |
int |
Non |
Intervalle de capture des images pour les sous-images du sprite. Unité : milliseconde. Valeur par défaut : 0, ce qui signifie que toutes les images vidéo sont capturées. Remarque
Si la valeur de ce paramètre est inférieure à l'intervalle entre les images (l'inverse de la fréquence d'images) de la vidéo source, les images sont capturées selon l'intervalle de la vidéo source. |
|
sw |
int |
Non |
Largeur d'une sous-image du sprite. Unité : px. Valeurs valides : [32, 4 096]. Par défaut, la largeur de la sous-image correspond à celle de la vidéo source. |
|
sh |
int |
Non |
Hauteur d'une sous-image du sprite. Unité : px. Valeurs valides : [32, 4 096]. Par défaut, la hauteur de la sous-image correspond à celle de la vidéo source. |
|
psw |
int |
Non |
Pourcentage de la largeur de la sous-image du sprite par rapport à la largeur de la vidéo source. Valeurs valides : (0, 200]. Valeur par défaut : 100. Remarque
Si vous définissez à la fois les paramètres sw et psw, le paramètre psw est ignoré. |
|
psh |
int |
Non |
Pourcentage de la hauteur de la sous-image du sprite par rapport à la hauteur de la vidéo source. Valeurs valides : (0, 200]. Valeur par défaut : 100. Remarque
Si vous définissez à la fois les paramètres sh et psh, le paramètre psh est ignoré. |
|
scaletype |
string |
Non |
Mode de mise à l'échelle. Valeurs valides :
|
|
tw |
int |
Non |
Nombre de sous-images par ligne du sprite. Valeur par défaut : 6. Valeurs valides : [1, 100]. |
|
th |
int |
Non |
Nombre de sous-images par colonne du sprite. Valeur par défaut : 6. Valeurs valides : [1, 100]. |
|
pad |
int |
Non |
Marge intérieure entre les sous-images du sprite. Unité : px. Valeur par défaut : 2. Valeurs valides : [0, 100]. |
|
margin |
int |
Non |
Marge extérieure autour des bords du sprite. Unité : px. Valeur par défaut : 2. Valeurs valides : [0, 100]. |
Les paramètres sys/saveas et notify sont également utilisés lors de la génération de sprites à partir d'images instantanées vidéo. Pour plus d'informations, consultez les rubriques Enregistrer sous et Notifications.
Utiliser l'API REST
Si vous ne spécifiez pas d'extension de fichier (comme .jpg) dans le chemin de stockage du sprite de sortie, le système ajoute automatiquement un numéro ordinal au nom de fichier, par exemple _0_1.jpg. Si vous spécifiez une extension, seul le dernier sprite est enregistré. Nous vous recommandons donc de ne pas spécifier d'extension de fichier. Pour personnaliser le numéro ordinal, utilisez les variables liées à ApsaraVideo Media Processing.
Générer un sprite pour l'ensemble de la vidéo en capturant une image toutes les 2 secondes
Vous pouvez générer un sprite couvrant toute la vidéo en capturant une image toutes les 2 secondes. Chaque sprite contient une grille de 3 × 3 sous-images, chaque sous-image ayant une résolution de 200 × 150.
Informations sur le sprite
-
Fichier source
Nom de la vidéo : example.mkv
-
Notification de message
Rubrique MNS pour les notifications : example-mns-topic
-
Configuration de sortie
-
Informations de capture d'images
Format du sprite : jpg
Intervalle de capture des sous-images : 2 s
Disposition de la grille des sous-images : 3 × 3
Résolution des sous-images : 200 × 150
Mode de mise à l'échelle des sous-images : crop
Marge intérieure entre les sous-images : 0
Marge extérieure autour des sous-images : 0
-
Chemin de stockage des fichiers
Fichier JPG : oss://outbucket/outobjprefix-%d.jpg
-
Exemple
// Generate a sprite from the example.mkv video file.
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
Générer un sprite en capturant des images à intervalles réguliers selon un nombre spécifié
Vous pouvez générer un sprite de 10 × 10 où les sous-images couvrent uniformément l'ensemble de la vidéo. Cela simplifie la logique frontend.
Informations sur le sprite
-
Fichier source
Nom de la vidéo : example.mkv
-
Notification de message
Rubrique MNS pour les notifications : example-mns-topic
-
Configuration de sortie
-
Informations de capture d'images
Format du sprite : jpg
Mode de capture des sous-images : avg
Disposition de la grille des sous-images : 10 × 10
Résolution des sous-images : 1/10 de la vidéo source
Mode de mise à l'échelle des sous-images : fit
Marge intérieure entre les sous-images : 4
Marge extérieure autour des sous-images : 5
-
Chemin de stockage des fichiers
Fichier JPG : oss://outbucket/outobjprefix-%d.jpg
-
Exemple
// Generate a sprite from the example.mkv video file.
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
Utiliser les SDK
La génération asynchrone de sprites à partir d'images instantanées vidéo est prise en charge uniquement par les SDK pour Java, Python et Go. Pour plus d'informations, consultez la rubrique Installer les SDK.
Java
Le SDK OSS pour Java version 3.17.4 ou ultérieure est requis.
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 {
// Specify the endpoint of the region where the bucket is located.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// Specify the region ID that corresponds to the endpoint. Example: cn-hangzhou.
String region = "cn-hangzhou";
// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// Specify the bucket name.
String bucketName = "examplebucket";
// Specify the filename of the sprite.
String targetKey = "example.jpg";
// Specify the name of the source video file.
String sourceKey = "src.mp4";
// Create an OSSClient instance.
// When the OSSClient instance is no longer used, call the shutdown method to release its resources.
ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(credentialsProvider)
.clientConfiguration(clientBuilderConfiguration)
.region(region)
.build();
try {
// Configure the parameters for generating a sprite from a video.
String style = String.format("video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0");
// Create an asynchronous processing instruction.
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);
// Create an AsyncProcessObjectRequest object.
AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
// Execute the asynchronous processing task.
AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
System.out.println("EventId: " + response.getEventId());
System.out.println("RequestId: " + response.getRequestId());
System.out.println("TaskId: " + response.getTaskId());
} finally {
// Shut down the OSSClient.
ossClient.shutdown();
}
}
}
Python
Le SDK Python version 2.18.4 ou ultérieure est requis.
# -*- coding: utf-8 -*-
import base64
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
def main():
# Obtain temporary access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
# Specify the region ID that corresponds to the endpoint. Example: cn-hangzhou.
region = 'cn-hangzhou'
# Specify the bucket name.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)
# Specify the name of the source video file.
source_key = 'src.mp4'
# Specify the filename of the sprite.
target_key = 'example.jpg'
# Configure the parameters for generating a sprite from a video.
animation_style = 'video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0'
# Create a processing instruction that includes the storage path and the Base64-encoded bucket name and object name.
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:
# Execute the asynchronous processing task.
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
Le SDK Go version 3.0.2 ou ultérieure est requis.
package main
import (
"encoding/base64"
"fmt"
"os"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
"log"
)
func main() {
// Obtain temporary access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Create an OSSClient instance.
// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify the endpoint based on your actual region.
// Set yourRegion to the Alibaba Cloud region ID. Example: 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)
}
// Specify the bucket name. Example: examplebucket.
bucketName := "examplebucket"
bucket, err := client.Bucket(bucketName)
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Specify the name of the source video file.
sourceKey := "src.mp4"
// Specify the name of the output sprite file.
targetKey := "example.jpg"
// Configure the parameters for generating a sprite from a video.
animationStyle := "video/sprite,f_jpg,sw_100,sh_100,inter_10000,tw_10,th_10,pad_0,margin_0"
// Create a processing instruction that includes the storage path and the Base64-encoded bucket name and object name.
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)
// Execute the asynchronous processing task.
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)
}