Um sprite CSS (Cascading Style Sheets) é um conjunto de imagens combinadas em um único arquivo. Os sprites são usados principalmente para otimizar o desempenho de sites e no desenvolvimento frontend. Ao utilizar a propriedade background-position do CSS, você reduz as requisições HTTP, o que melhora a velocidade de carregamento da página e a experiência do usuário. Com o recurso de geração de sprites, é possível extrair frames de vídeo e combiná-los em um sprite. Este tópico descreve os parâmetros para gerar sprites a partir de snapshots de vídeo e fornece exemplos.
Observações de uso
A geração de sprites a partir de snapshots de vídeo suporta apenas processamento assíncrono (x-oss-async-process).
A geração de sprites pode falhar ou produzir uma quantidade incorreta de imagens se o carimbo de data/hora ou o stream do vídeo estiver corrompido.
Antes de usar este recurso, anexe um projeto IMM. Para obter mais informações sobre como anexar um projeto no console ou usando uma API, consulte Início rápido e AttachOSSBucket - Anexar um bucket OSS.
Parâmetros
Ação: video/sprite
A tabela a seguir descreve os parâmetros.
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
ss |
int |
Não |
O horário inicial para gerar um sprite. Unidade: milissegundo. Valores válidos:
|
|
f |
string |
Sim |
O formato de saída do sprite. Valores válidos:
Nota
A resolução máxima é 16384px × 16384px. |
|
m |
string |
Não |
O modo de captura de frames para subimagens do sprite. O valor padrão é inter. Valores válidos:
|
|
thr |
int |
Não |
O limiar de captura de frames para subimagens do sprite no modo dhash. Um limiar maior resulta em menos frames capturados. Valores válidos: [0, 100]. Valor padrão: 0. Nota
Este parâmetro é válido apenas no modo dhash. O modo dhash é sensível ao limiar. Defina este parâmetro com um valor não superior a 25 e ajuste-o conforme necessário. |
|
num |
int |
Não |
A quantidade de frames a serem capturados para as subimagens do sprite. Valor padrão: 0, indicando que não há limite para a quantidade de frames capturados. O valor padrão tem significados diferentes nos diversos modos de captura:
Importante
A quantidade real de frames capturados pode ser menor que o valor especificado devido à duração do vídeo e aos parâmetros de captura. |
|
inter |
int |
Não |
O intervalo para capturar frames das subimagens do sprite. Unidade: milissegundo. Valor padrão: 0, indicando que todos os frames do vídeo são capturados. Nota
Se o valor deste parâmetro for menor que o intervalo de frames (o recíproco da taxa de frames) do vídeo source, a captura seguirá o intervalo de frames do vídeo original. |
|
sw |
int |
Não |
A largura de uma subimagem do sprite. Unidade: px. Valores válidos: [32, 4096]. Por padrão, a largura da subimagem é igual à largura do vídeo source. |
|
sh |
int |
Não |
A altura de uma subimagem do sprite. Unidade: px. Valores válidos: [32, 4096]. Por padrão, a altura da subimagem é igual à altura do vídeo source. |
|
psw |
int |
Não |
A porcentagem da largura da subimagem do sprite em relação à largura do vídeo source. Valores válidos: (0, 200]. Valor padrão: 100. Nota
Se você definir os parâmetros sw e psw simultaneamente, o parâmetro psw será ignorado. |
|
psh |
int |
Não |
A porcentagem da altura da subimagem do sprite em relação à altura do vídeo source. Valores válidos: (0, 200]. Valor padrão: 100. Nota
Se você definir os parâmetros sh e psh simultaneamente, o parâmetro psh será ignorado. |
|
scaletype |
string |
Não |
O modo de dimensionamento. Valores válidos:
|
|
tw |
int |
Não |
A quantidade de subimagens em cada linha do sprite. Valor padrão: 6. Valores válidos: [1, 100]. |
|
th |
int |
Não |
A quantidade de subimagens em cada coluna do sprite. Valor padrão: 6. Valores válidos: [1, 100]. |
|
pad |
int |
Não |
O preenchimento entre as subimagens no sprite. Unidade: px. Valor padrão: 2. Valores válidos: [0, 100]. |
|
margin |
int |
Não |
A margem ao redor das bordas do sprite. Unidade: px. Valor padrão: 2. Valores válidos: [0, 100]. |
Os parâmetros sys/saveas e notify também são utilizados na geração de sprites a partir de snapshots de vídeo. Para obter mais informações, consulte Salvar como e Notificações.
Usar a API REST
Caso você não especifique uma extensão de arquivo, como .jpg, no caminho de armazenamento do sprite de saída, o sistema adicionará automaticamente um número ordinal ao nome do arquivo, como _0_1.jpg. Se uma extensão for especificada, apenas o último sprite será salvo. Portanto, recomenda-se não especificar uma extensão de arquivo. Para personalizar o número ordinal, utilize variáveis relacionadas ao ApsaraVideo Media Processing.
Gerar um sprite para todo o vídeo capturando um frame a cada 2 segundos
Gere um sprite para todo o vídeo capturando um frame a cada 2 segundos. Cada sprite contém uma grade de subimagens de 3 × 3, e cada subimagem tem resolução de 200 × 150.
Informações do sprite
-
Arquivo source
Nome do vídeo: example.mkv
-
Notificação de mensagem
Tópico MNS para notificações: example-mns-topic
-
Configuração de saída
-
Informações de captura de frames
Formato do sprite: jpg
Intervalo de captura de frames para subimagens: 2 s
Layout da grade de subimagens: 3 × 3
Resolução da subimagem: 200 × 150
Modo de dimensionamento da subimagem: crop
Preenchimento entre subimagens: 0
Margem ao redor das subimagens: 0
-
Caminho de armazenamento de arquivos
Arquivo JPG: oss://outbucket/outobjprefix-%d.jpg
-
Exemplo
// 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
Gerar um sprite capturando frames em intervalos uniformes com base em uma quantidade especificada
Gere um sprite de 10 × 10 onde as subimagens cobrem uniformemente todo o vídeo. Isso simplifica a lógica do frontend.
Informações do sprite
-
Arquivo source
Nome do vídeo: example.mkv
-
Notificação de mensagem
Tópico MNS para notificações: example-mns-topic
-
Configuração de saída
-
Informações de captura de frames
Formato do sprite: jpg
Modo de captura de frames para subimagens: avg
Layout da grade de subimagens: 10 × 10
Resolução da subimagem: 1/10 do vídeo source
Modo de dimensionamento da subimagem: fit
Preenchimento entre subimagens: 4
Margem ao redor das subimagens: 5
-
Caminho de armazenamento de arquivos
Arquivo JPG: oss://outbucket/outobjprefix-%d.jpg
-
Exemplo
// 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
Usar SDKs
A geração assíncrona de sprites a partir de snapshots de vídeo é suportada apenas pelos SDKs para Java, Python e Go. Para obter mais informações, consulte Instalar SDKs.
Java
É necessário o OSS SDK for Java 3.17.4 ou posterior.
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
É necessário o Python SDK 2.18.4 ou posterior.
# -*- 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
É necessário o Go SDK 3.0.2 ou posterior.
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)
}