All Products
Search
Document Center

Object Storage Service:Video transcoding

Last Updated:May 27, 2025

You can use video transcoding to change encoding formats, reduce resolution and bitrate, convert container formats, and modify video parameters to meet different business requirements.

Features

Video transcoding is the process of converting a compressed video stream into another video stream, transforming video format, container, resolution, frame rate, and bitrate parameters to make them suitable for playback on different devices and platforms, while reducing file size to optimize transmission efficiency.

image

Scenarios

  • Multi-device compatibility: To ensure videos can be played smoothly on different devices (such as mobile phones, tablets, computers, smart TVs), transcoding technology can convert videos to formats supported by specific devices.

  • Streaming media playback: Streaming services need to transcode videos into multiple formats and bitrates to dynamically adjust based on users' network conditions, thereby improving viewing experience.

  • Video compression: While ensuring video quality, transcoding technology reduces file size for easier storage and transmission, especially in bandwidth-limited situations.

  • Data archiving: Transcoding can convert high-quality videos into more efficient formats for long-term storage and management, reducing storage space requirements.

  • Resolution adaptation: To accommodate different playback devices and network environments, transcoding can reduce video resolution to achieve smoother playback experience.

  • Format conversion: Some uncommon formats may not be supported by media players, so transcoding can convert videos to more commonly used formats.

How to use

Prerequisites

  • Intelligent Media Management (IMM) is activated. For more information, see Activate IMM.

  • The corresponding Object Storage Service (OSS) bucket is bound to an IMM project. For more information, see Quick Start. For information about how to bind a bucket to an IMM project by using the IMM API, see AttachOSSBucket.

  • The required permissions are granted to the Resource Access Management (RAM) user that you use to use IMM features. For more information, see Permissions.

Video transcoding

You can use OSS SDK only for Java, Python, or Go to transcode videos in asynchronous mode.

Java

OSS SDK for Java 3.17.4 or later is required.

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 in which the bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the ID of the Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
        String region = "cn-hangzhou";
        // Obtain access credentials from environment variables. Before you run the 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 name of the bucket. Example: examplebucket.
        String bucketName = "examplebucket";
        // Specify the name of the output video.
        String targetKey = "dest.avi";
        // Specify the name of the source video.
        String sourceKey = "src.mp4";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer in use, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Create a style variable of the string type to store video transcoding parameters.
            String style = String.format("video/convert,f_avi,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1");
            // 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", 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 instance.
            ossClient.shutdown();
        }
    }
}

Python

OSS SDK for Python V2.18.4 or later is required.

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


def main():
    # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
    # Obtain access credentials from environment variables. Before you run the 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 name of the bucket.
    bucket_name = 'examplebucket'
    # Specify the ID of the Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
    region = 'cn-hangzhou'
    # Create a bucket.
    bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

    # Specify the name of the source video.
    source_key = 'src.mp4'
    # Specify the name of the output video.
    target_key = 'dest.avi'
    # Create a style variable of the string type to store video transcoding parameters.
    style = 'video/convert,f_avi,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1'
    process = "{0}|sys/saveas,o_{1}".format(style,
                                            oss2.compat.to_string(base64.urlsafe_b64encode(
                                                oss2.compat.to_bytes(target_key))).replace('=', ''))

    # Call the media processing operation.
    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

OSS SDK for Go V3.0.2 or later is required.

package main

import (
	"encoding/base64"
	"fmt"
	"os"
	"strings"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run the 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. Specify your actual endpoint.
	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 name of the bucket in which the source video is stored. Example: examplebucket.
	bucketName := "examplebucket"
	bucket, err := client.Bucket(bucketName)
	// Specify the name of the output video.
	targetObject := "dest.avi"
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	// Specify the name of the source video.
	sourceObject := "src.mp4"

	// Create a style variable of the string type to store video transcoding parameters.
	style := "video/convert,f_avi,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1"

	process := fmt.Sprintf("%s|sys/saveas,b_%v,o_%v", style, strings.TrimRight(base64.URLEncoding.EncodeToString([]byte(bucketName)), "="), strings.TrimRight(base64.URLEncoding.EncodeToString([]byte(targetObject)), "="))
	fmt.Printf("%#v\n", process)
	rs, err := bucket.AsyncProcessObject(sourceObject, process)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	fmt.Printf("EventId:%s\n", rs.EventId)
	fmt.Printf("RequestId:%s\n", rs.RequestId)
	fmt.Printf("TaskId:%s\n", rs.TaskId)
}

Parameters

Action: video/convert

The following table describes the parameters for video transcoding.

Parameter

Type

Required

Description

ss

int

No

The start time of the video from which transcoding begins. Unit: milliseconds. Valid values:

  • 0 (default): Transcoding begins from the start position of the video.

  • Greater than 0: Starts from the ssth millisecond.

t

int

No

The duration of video content to be transcoded after the specified start time. Unit: milliseconds. Valid values:

  • 0 (default): Transcoding lasts until the end of the video.

  • Greater than 0: lasts for t milliseconds.

f

string

Yes

The type of the media container. Valid values:

  • Valid values for audio and video containers: mp4, mkv, mov, asf, avi, mxf, ts, flv, and webm

  • Valid values for audio containers: mp3, aac, flac, oga, ac3, opus, and amr

vn

int

No

Specifies whether to disable video stream generation. Valid values:

  • 0 (default): does not disable video stream generation.

  • 1: disables video stream generation. No video stream is included in the output object.

vcodec

string

No

The encoding format of the output video. Valid values:

  • copy (default): copies the video stream in the video that you want to process into the output object.

  • h264: The output video is in the H.264 format.

  • h265: The output video is in the H.265 format.

  • vp9: The output video is in the VP9 format.

fps

float

No

The video frame rate. Valid values: 0 to 240.

fpsopt

int

No

The frame rate option. Valid values:

  • 0: always uses the target frame rate.

  • 1: uses the source frame rate when the source frame rate is less than the target frame rate.

  • 2: returns a failure when the source frame rate is less than the target frame rate.

pixfmt

string

No

The target pixel format. By default, the target pixel format is the same as the source pixel format. Valid values:

  • yuv420p

  • yuva420p

  • yuv420p10le

  • yuv422p

  • yuv422p10le

  • yuv444p

  • yuv444p10le

s

string

No

The desired resolution.

  • The resolution is in the Width x Height format.

  • The width and height must be a multiple of 2 and within the range of 64 to 4,096. Examples: 4096x4096 and 64x64.

sopt

int

No

The resolution option. Valid values:

  • 0: always uses the target resolution.

  • 1: uses the source resolution when the source resolution is less than the target resolution.

  • 2: returns a failure when the source resolution is less than the target resolution.

scaletype

string

No

The resizing mode. Valid values:

  • crop: proportionally resizes the video to fit within a rectangular area defined by the specified width and height or the specified lengths of the longer and shorter sides, and then crops the parts that extend beyond the rectangular area from the center.

  • stretch (default): forcibly resizes the video based on the specified width and height or the specified lengths of the longer and shorter sides, and then stretches the video to fill the remaining space.

  • fill: proportionally resizes the video to the maximum resolution within a rectangular area defined by the specified width and height or the specified lengths of the longer and shorter sides, and then fills the space with black from the center.

  • fit: proportionally resizes the video to the maximum resolution within a rectangular area defined by the specified width and height or the specified lengths of the longer and shorter sides.

arotate

int

No

Specifies whether to enable adaptive resolution orientation. Valid values:

  • 0 (default): does not enable adaptive resolution orientation.

  • 1: enables adaptive resolution orientation.

g

int

No

The keyframe interval. Valid values: 1 to 100000.

vb

int

No

The target video bitrate. Unit: bit/s. Valid values: 10000 to 100000000.

vbopt

int

No

The video bitrate option. Valid values:

  • 0: always uses the target video bitrate.

  • 1: uses the source bitrate when the source video bitrate is less than the target video bitrate.

  • 2: returns a failure when the source video bitrate is less than the target video bitrate.

crf

float

No

The constant rate factor (CRF). Valid values: 0 to 51.

maxrate

int

No

The maximum bitrate. Unit: bit/s. Valid values: 10000 to 100000000.

bufsize

int

No

The buffer size. Unit: bit. Valid values: 10000 to 200000000.

an

int

No

Specifies whether to disable audio stream generation. Valid values:

  • 0 (default): does not disable audio stream generation.

  • 1: disables audio stream generation. No audio stream is included in the output object.

acodec

string

No

The encoding format of the audio. Valid values:

  • copy (default): copies the audio stream to the output object.

  • mp3: The output audio is in the MP3 format.

  • aac: The output audio is in the AAC format.

  • flac: The output audio is in the FLAC format.

  • vorbis: The output audio is in the Vorbis format.

  • ac3: The output audio is in the AC3 format.

  • opus: The output audio is in the Opus format.

  • amr: The output audio is in the AMR format.

ar

int

No

The audio sampling rate. Valid values:

  • 8000

  • 11025

  • 12000

  • 16000

  • 22050

  • 24000

  • 32000

  • 44100

  • 48000

  • 88200

  • 96000

ac

int

No

The number of sound channels in the output audio. By default, the output audio retains the same number of channels as the source audio. Valid values: 1 to 8.

aq

int

No

The audio compression quality. This parameter and the ab parameter are mutually exclusive. Valid values: 0 to 100.

ab

int

No

The audio bitrate. This parameter and the aq parameter are mutually exclusive. Unit: bit/s. Valid values: 1000 to 10000000.

abopt

int

No

The audio bitrate option. Valid values:

  • 0 (default): always uses the target audio bitrate.

  • 1: uses the source audio bitrate when the source audio bitrate is less than the target audio bitrate.

  • 2: returns a failure when the source audio bitrate is less than the target audio bitrate.

sn

int

No

Specifies whether to disable subtitle generation. Valid values:

  • 0 (default): does not disable subtitle generation.

  • 1: disables subtitle generation. No subtitles are included in the output object.

adepth

int

No

The sampling bit depth of the output audio. Valid values: 16 and 24.

Note

This parameter takes effect only if you set the acodec parameter to flac

segment

string

No

The media segmentation settings. By default, no segmentation is performed.

f

string

No

The media segmentation mode. Valid values:

  • hls

  • dash

Parent node: segment

t

int

No

The length of the segment. Unit: milliseconds. Valid values: 0 to 3600000.

Parent node: segment

You may also need to use the sys/saveas and notify parameters in a video transcoding task. For more information, see sys/saveas and Message notification.

API reference

If your business requires a high level of customization, you can directly call RESTful APIs. To directly call a RESTful API, you must include the signature calculation in your code. For information about how to calculate the signature for the Authorization header, see Signature Version 4 (recommended).

Convert from AVI to MP4

Transcoding task information

  • Source object

    • Video format: AVI

    • Video name: example.avi

  • Processing method: video transcoding

  • Destination object

    • Video information

      • Video format: MP4

      • Video name: outobjprefix.mp4

      • Video stream format: H.265

      • Video resolution: 1920×1080

      • Video frame rate: 30 fps

      • Video bitrate: 2 Mbps

    • Audio information

      • Audio stream format: AAC

      • Audio bitrate: 100 Kbps

      • Subtitle stream: disabled

    • Output path: oss://outbucket/outobjprefix.mp4

Example

POST /example.avi?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: SignatureValue
 
// Transcode the example.avi object to the MP4 container format and specify H.265 as the video stream format. Set the resolution to 1920 x 1080, frame rate to 30 fps, and video bitrate to 2 Mbit/s. Specify AAC as the audio stream format and set the audio bitrate to 100 Kbit/s. Disable subtitle stream generation. Save the output object as oss://outbucket/outobjprefix.mp4.
x-oss-async-process=video/convert,f_mp4,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LnthdXRvZXh0fQ

Convert from AVI to TS

Transcoding task information

  • Source object

    • Video format: AVI

    • Video name: example.avi

  • Processing method

    • Length of transcoding: Transcode 60,000 milliseconds of the video, starting from the 1,000th millisecond of the video.

    • Segment method: Create HTTP Live Streaming (HLS) segments at intervals of 30 seconds.

    • Transcoding completion notification: Send Simple Message Queue (SMQ) messages.

  • Destination object

    • Video information

      • Video format: TS

      • Video stream format: H.264

      • Video bitrate: 1 Mbps

    • Audio information

      • Audio format: AAC

      • Audio bitrate: 100 Kbps

    • Output paths

      • TS objects: oss://outbucket/outobjprefix-%d.ts

      • M3U8 object: oss://outbucket/outobjprefix.m3u8

Example

POST /example.avi?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: SignatureValue
 
// Transcode the example.avi video.
x-oss-async-process=video/convert,ss_10000,t_60000,f_ts,vcodec_h264,vb_1000000,acodec_mp3,ab_100000/segment,f_hls,t_30000|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LnthdXRvZXh0fQ/notify,topic_QXVkaW9Db252ZXJ0

Convert from AVI to MP3

Transcoding task information

  • Source object

    • Video name: example.avi

    • Video format: AVI

  • Processing method: Extract and convert audio

  • Destination object

    • Audio container format: MP3

    • Audio coding format: MP3

    • Audio bitrate: 100 Kbps

    • Video stream: disabled

    • Subtitle stream: disabled

    • Output path: oss://outbucket/outobjprefix.mp3 (If the video contains multiple audio channels, only the first channel is processed by default.)

Example

POST /example.avi?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: SignatureValue
 
// Extract audio from the example.avi object and transcode the extracted audio.
x-oss-async-process=video/convert,f_mp3,acodec_mp3,ab_100000,vn_1,sn_1|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqcHJlZml4LnthdXRvZXh0fQ

Usage notes

  • Video transcoding supports only asynchronous processing (x-oss-async-process).

  • Video transcoding does not support anonymous access.

  • Video transcoding supports the following video formats: MP4, MPEG-TS, MKV, MOV, AVI, FLV, M3U8, WebM, WMV, RM, and VOB.

  • You are charged for using video/convert video transcoding. Fees for media processing are included in your Intelligent Media Management (IMM) bills. For more information, see Billing items.

FAQ

How do I fix a ResourceNotFound error for a video transcoding task?

To fix the ResourceNotFound, The specified resource Attachment is not found. error during video transcoding, make sure that a storage bucket is created and bound to your IMM project. For more information, see OSS data processing guide.

Can I save the output object of a video transcoding task to the path of the source object?

No, you cannot save the output object of a video transcoding task to the same path as the source object. To prevent issues such as execution loops of triggers or accidental overwriting of the source object, do not use the input path as the prefix of the output path.

Can I specify an audio bit depth in a video transcoding task?

Yes, you can specify an audio bit depth in a video transcoding task by including the pixfmt parameter in x-oss-process.

How do I retrieve the task execution result for video transcoding by using the returned task ID?

To retrieve the task execution result for video transcoding by using the returned task ID, we recommend that you call the GetTask operation in IMM.

How does OSS handle the retrieval and deletion of objects with a specific format based on their suffix during video transcoding?

OSS does not support searching for objects by suffix, as it offers an unordered storage service.

What do I do if message pushing for video transcoding is configured but the backend does not receive messages?

Check whether the SMQ topic is created and the subscription is configured. If the SMQ topic does not exist or is deleted, reconfigure the subscription. Restart the transcoding process based on the current subscription configuration.

Can I use a specific template to transcode a video after uploading the video to OSS?

Yes, you can configure a trigger to implement this feature. For existing and new videos in a bucket, video processing tasks can be manually or automatically initiated by using batch processing configurations and triggers. When you create tasks, batch processors, or triggers, you can use system or custom styles. For more information, see Batch processing and Triggers.

Am I charged storage fees for both the transcoded video and the source video? If the transcoded video has a different prefix than the source video, will the transcoded video replace the source video?

The transcoded video consumes storage space, resulting in associated charges. Using the same path for both the transcoded video and the source video may lead to looping issues.