Object Storage Service:Video concatenation

Use cases

• Film and video production: Stitch shots and scenes from different clips into a complete narrative sequence.

• Short-form content: Combine clips into vlogs, tutorials, or themed videos for social media platforms.

• Education and training: Merge theory and demonstration clips into a single instructional video.

• Sports highlights: Assemble highlight reels from multiple footage segments.

How it works

The video/concat action concatenates videos in the order that /pre and /sur segments appear in the processing string, then transcodes the result to the specified format.

All examples in this topic use the x-oss-async-process header to submit the task as an asynchronous job.

Prerequisites

Before you begin, ensure that you have:

• Activated Intelligent Media Management (IMM). For details, see Activate a product.

• Attached an IMM project to the bucket. To attach via the OSS console, see Step 1: Attach an IMM project. To attach via API, see AttachOSSBucket.

Limitations

Review these constraints before submitting a task:

• Asynchronous only: Video concatenation supports only asynchronous processing (x-oss-async-process). Synchronous requests are not supported.

• Maximum input videos: A single task can concatenate up to 11 videos.

• Anonymous access: Requests from anonymous users are denied.

• Container compatibility: When using default audio sample rates or audio channel counts, concatenation may fail if those defaults are incompatible with the target container. Specify explicit values for ar and ac to avoid this.

• Codec and container restrictions: See Transcoding parameters for codec-to-container compatibility rules.

Concatenate videos

Use Java SDK 3.17.4 or later, Python SDK 2.18.4 or later, or Go SDK 3.0.2 or later.

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 {
        // Replace with the endpoint for the region where your bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the region ID, such as cn-hangzhou.
        String region = "cn-hangzhou";
        // Read credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the bucket name.
        String bucketName = "examplebucket";
        // Specify the output video name.
        String targetObject = "dest.mp4";
        // Specify the source video (the main file used as the transcoding base).
        String sourceVideo = "src.mp4";
        // Specify the videos to prepend and append.
        String video1 = "concat1.mp4";
        String video2 = "concat2.mp4";

        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Base64 URL-safe encode the video object names (required by the /pre and /sur parameters).
            String video1Encoded = Base64.getUrlEncoder().withoutPadding().encodeToString(video1.getBytes());
            String video2Encoded = Base64.getUrlEncoder().withoutPadding().encodeToString(video2.getBytes());

            // Build the processing style string:
            // - /pre,o_<encoded>: prepend video1 to the beginning
            // - /sur,o_<encoded>,t_0: append video2 to the end (t_0 means use the full clip)
            // - Other parameters control the output encoding.
            String style = String.format(
                "video/concat,ss_0,f_mp4,vcodec_h264,fps_25,vb_1000000,acodec_aac,ab_96000,ar_48000,ac_2,align_1" +
                "/pre,o_%s/sur,o_%s,t_0",
                video1Encoded, video2Encoded
            );

            // Append save-as and notification instructions.
            String bucketEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bucketName.getBytes());
            String targetEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(targetObject.getBytes());
            String process = String.format(
                "%s|sys/saveas,b_%s,o_%s/notify,topic_QXVkaW9Db252ZXJ0",
                style, bucketEncoded, targetEncoded
            );

            // Submit the asynchronous task.
            AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceVideo, 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.shutdown();
        }
    }
}

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

def main():
    # Read credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    # Replace with the endpoint for the region where your bucket is located.
    endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
    region = 'cn-hangzhou'

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

    # Specify the output video name.
    target_object = 'out.mp4'
    # Specify the source video (the main file used as the transcoding base).
    source_video = 'emrfinal.mp4'
    # Specify the videos to prepend and append.
    video1 = 'osshdfs.mp4'
    video2 = 'product.mp4'

    # Base64 URL-safe encode the video object names (required by the /pre and /sur parameters).
    video1_encoded = base64.urlsafe_b64encode(video1.encode()).decode().rstrip('=')
    video2_encoded = base64.urlsafe_b64encode(video2.encode()).decode().rstrip('=')

    # Build the processing style string:
    # - /pre,o_<encoded>: prepend video1 to the beginning
    # - /sur,o_<encoded>,t_0: append video2 to the end (t_0 means use the full clip)
    # - Other parameters control the output encoding.
    style = (
        f"video/concat,ss_0,f_mp4,vcodec_h264,fps_25,vb_1000000,acodec_aac,ab_96000,ar_48000,ac_2,align_1"
        f"/pre,o_{video1_encoded}/sur,o_{video2_encoded},t_0"
    )

    # Append save-as and notification instructions.
    bucket_encoded = base64.urlsafe_b64encode('examplebucket'.encode()).decode().rstrip('=')
    target_encoded = base64.urlsafe_b64encode(target_object.encode()).decode().rstrip('=')
    process = f"{style}|sys/saveas,b_{bucket_encoded},o_{target_encoded}/notify,topic_QXVkaW9Db252ZXJ0"

    # Submit the asynchronous task.
    try:
        result = bucket.async_process_object(source_video, 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()

package main

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

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

func main() {
    // Read credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    // Replace yourEndpoint with the endpoint for the region where your bucket is located,
    // and yourRegion with the corresponding region ID (e.g., cn-hangzhou).
    client, err := oss.New(
        "yourEndpoint", "", "",
        oss.SetCredentialsProvider(&provider),
        oss.AuthVersion(oss.AuthV4),
        oss.Region("yourRegion"),
    )
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

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

    // Specify the output video name.
    targetObject := "dest.mp4"
    // Specify the source video (the main file used as the transcoding base).
    sourcevideo := "src.mp4"
    // Specify the videos to prepend and append.
    video1 := "concat1.mp4"
    video2 := "concat2.mp4"

    // Base64 URL-safe encode the video object names (required by the /pre and /sur parameters).
    encode := func(s string) string {
        return strings.TrimRight(base64.URLEncoding.EncodeToString([]byte(s)), "=")
    }

    // Build the processing style string:
    // - /pre,o_<encoded>: prepend video1 to the beginning
    // - /sur,o_<encoded>,t_0: append video2 to the end (t_0 means use the full clip)
    // - Other parameters control the output encoding.
    style := fmt.Sprintf(
        "video/concat,ss_0,f_mp4,vcodec_h264,fps_25,vb_1000000,acodec_aac,ab_96000,ar_48000,ac_2,align_1/pre,o_%s/sur,o_%s,t_0",
        encode(video1), encode(video2),
    )

    // Append save-as and notification instructions.
    process := fmt.Sprintf(
        "%s|sys/saveas,b_%s,o_%s/notify,topic_QXVkaW9Db252ZXJ0",
        style, encode(bucketName), encode(targetObject),
    )

    // Submit the asynchronous task.
    rs, err := bucket.AsyncProcessObject(sourcevideo, 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)
}

The response contains a TaskId. The API does not return the processing result directly. To receive a completion notification, configure Simple Message Queue (SMQ), formerly known as MNS. For details, see Message notifications.

For details on the sys/saveas and notify parameters, see Save as and Message notifications.

Parameter reference

Example: Concatenate three clips into an MP4 file

This example concatenates three videos — pre.mov (full clip), example.mkv (from the 10-second mark to the end), and sur.mov (first 10 seconds) — and saves the result as oss://outbucket/outobj.mp4.

Output settings: H.264, 25 fps, 1 Mbps video bitrate; AAC audio, 48 kHz, dual-channel, 96 Kbps.

POST /example.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/concat,ss_10000,f_mp4,vcodec_h264,fps_25,vb_1000000,acodec_aac,ab_96000,ar_48000,ac_2,align_1/pre,o_cHJlLm1vdgo/sur,o_c3VyMS5hYWMK,t_10000|sys/saveas,b_b3V0YnVja2V0,o_b3V0b2JqLnthdXRvZXh0fQo/notify,topic_QXVkaW9Db252ZXJ0

How the style string maps to the example:

Permissions

An Alibaba Cloud account has all permissions by default. A Resource Access Management (RAM) user or RAM role requires explicit grants via a RAM policy or bucket policy.

Billing

Video concatenation calls both OSS and IMM, generating billable items on both sides.

OSS charges (for pricing, see OSS Pricing):

IMM charges (for pricing, see IMM billable items):

What's next

• Message notifications — Configure SMQ to receive task completion events

• Save as — Learn how sys/saveas stores the output object