All Products
Search
Document Center

ApsaraVideo Live:Live stream encapsulation

Last Updated:Aug 26, 2025

ApsaraVideo Live provides the live stream encapsulation feature to support playback over various streaming protocols with low latency.

Supported container formats

ApsaraVideo Live supports various streaming protocols, including Real-Time Messaging Protocol (RTMP), HTTP-FLV, and HTTP Live Streaming (HLS).

To reduce latency and improve compatibility with multiple playback devices, live stream encapsulation converts the original streams into different container formats in the cloud before pushing to viewers.

The following table lists the supported container formats, as well as the streaming protocols and codecs that each format supports:

Container format

Supported streaming protocol

Supported codec

TS

  • Low-Latency HLS (LL-HLS)

  • Audio: AAC, OPUS, AC3, EAC3, and MP3

  • Video: H.264 and H.265

CMAF

  • LL-HLS

  • HLS

  • DASH

  • HLS & DASH

  • Audio: AAC

  • Video: H.264 and H.265

How it works

Live stream encapsulation splits streams into segments in TS or CMAF format and distributes them via protocols like HLS, LL-HLS, or DASH. The system generates a manifest file, which records the URLs of segments in sequence. When a client requests the live stream, the server returns the up-to-date manifest that contains the latest segments.

This feature can be combined with live stream transcoding (multi-bitrate transcoding supported) and time shifting to provide a better streaming experience.

Scenarios

  • Implement low-latency live streaming

    ApsaraVideo Live provides HLS streaming URLs. To enable low-latency video streaming over HLS, use the encapsulation feature to convert the stream for playback over LL-HLS.

    Compared to standard HLS, LL-HLS divides the stream into smaller partial segments (with a duration of 200 milliseconds to 1 second) and blocks playlist reloads, thus reducing the end-to-end latency to 3 to 5 seconds.

  • Enhance compatibility with multiple devices and browsers

    By default, ApsaraVideo Live distributes live streams over the HLS protocol using the TS container format. However, this format is incompatible with some devices and browsers. In this case, use the encapsulation feature to package the content into CMAF format, which supports a wide range of devices, platforms, and codecs, such as H.265.

Before you begin

Group of Pictures (GOP) size

  • For smooth playback, ensure the GOP size of the ingested stream remains consistent. If you intend to encapsulate a transcoded stream, ensure its GOP size is also stable.

  • The duration of each segment in the encapsulated stream must be a multiple of the GOP size.

LL-HLS protocol

  • The stuttering rate may increase under poor network conditions. We recommend using live stream encapsulation with multi-bitrate transcoding, which automatically adjusts the bitrate based on network conditions.

  • Ensure the GOP size of the live stream is fixed at 1 or 2 seconds to prevent stuttering or playback failure.

  • Use a player that supports LL-HLS, such as ApsaraVideo Player, hls.js, or ExoPlayer.

  • A main streaming domain name can support up to 100,000 viewers. To increase the quota, submit a ticket.

Others

  • When you add an encapsulation configuration to a domain name for the first time, the system updates the relevant configurations for content delivery acceleration. These changes take about 3 to 5 minutes to take effect.

Use the feature

Configure encapsulation settings

Configure encapsulation settings in the ApsaraVideo Live console or by API.

Note

For an ongoing stream, the configuration takes effect only after you re-ingest the stream.

In the console

  1. Log on to the ApsaraVideo Live console.
  2. In the left-side navigation pane, click Feature Management > Encapsulation.

  3. Select a streaming domain name, then click Add.

    image

    Parameter

    Description

    AppName

    • To configure encapsulation for all applications under the domain name, enter an asterisk (*). 

    • To configure it for a specific application, the value must be the same as the AppName specified in the ingest URL of the stream.

    StreamName

    • To configure encapsulation for all streams under an application, enter an asterisk (*). 

    • To configure it for a specific stream, enter the stream name.

    Protocol

    Select the container format and playback protocol. Valid values:

    • HLS - CMAF

    • LL-HLS - CMAF

    • LL-HLS - TS

    • DASH - CMAF (Only DASH supported)

    • HLS & DASH - CMAF (HLS and DASH supported)

    Segment Quantity

    Specify the number of segments per manifest file. Valid values: 3 to 5.

    Segment Length (s)

    • If the playback protocol is HLS or DASH, enter an integer between 1 to 10. We recommend that you set GOP to 5 seconds and the segment length to a multiple of the fixed GOP.

    • If the playback protocol is LL-HLS, set the segment length to 1 or 2 seconds, which must be a multiple of the fixed GOP. The recommended GOP is 1 second.

    Part Length (ms)

    If the playback protocol is LL-HLS, specify the duration of HLS partial segments. Valid values: 200 to 1000 milliseconds.

    We recommend that you specify a value that is slightly larger than one-third of the segment length.

    Transcoded Stream

    Specifies whether to encapsulate the transcoded stream.

    Valid values: Source Stream Only and Transcoded Stream Included.

    Note

    If the live center of the streaming domain is outside the Chinese Mainland (Singapore, Germany, Japan, or Indonesia), there may be a significant delay during playback. After completing the configuration, test and verify if the results meet your expectations.

  4. Click OK.

By API

Call the AddLivePackageConfig operation to add an encapsulation configuration

Sample code

// This file is auto-generated, don't edit it. Thanks.
package demo;

import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
import com.aliyun.core.http.HttpClient;
import com.aliyun.core.http.HttpMethod;
import com.aliyun.core.http.ProxyOptions;
import com.aliyun.httpcomponent.httpclient.ApacheAsyncHttpClientBuilder;
import com.aliyun.sdk.service.live20161101.models.*;
import com.aliyun.sdk.service.live20161101.*;
import com.google.gson.Gson;
import darabonba.core.RequestConfiguration;
import darabonba.core.client.ClientOverrideConfiguration;
import darabonba.core.utils.CommonUtil;
import darabonba.core.TeaPair;

//import javax.net.ssl.KeyManager;
//import javax.net.ssl.X509TrustManager;
import java.net.InetSocketAddress;
import java.time.Duration;
import java.util.*;
import java.util.concurrent.CompletableFuture;
import java.io.*;

public class AddLivePackageConfig {
    public static void main(String[] args) throws Exception {

        // HttpClient Configuration
        /*HttpClient httpClient = new ApacheAsyncHttpClientBuilder()
                .connectionTimeout(Duration.ofSeconds(10)) // Set the connection timeout time, the default is 10 seconds
                .responseTimeout(Duration.ofSeconds(10)) // Set the response timeout time, the default is 20 seconds
                .maxConnections(128) // Set the connection pool size
                .maxIdleTimeOut(Duration.ofSeconds(50)) // Set the connection pool timeout, the default is 30 seconds
                // Configure the proxy
                .proxy(new ProxyOptions(ProxyOptions.Type.HTTP, new InetSocketAddress("<YOUR-PROXY-HOSTNAME>", 9001))
                        .setCredentials("<YOUR-PROXY-USERNAME>", "<YOUR-PROXY-PASSWORD>"))
                // If it is an https connection, you need to configure the certificate, or ignore the certificate(.ignoreSSL(true))
                .x509TrustManagers(new X509TrustManager[]{})
                .keyManagers(new KeyManager[]{})
                .ignoreSSL(false)
                .build();*/

        // Configure Credentials authentication information, including ak, secret, token
        StaticCredentialProvider provider = StaticCredentialProvider.create(Credential.builder()
                // Please ensure that the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET are set.
                .accessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .accessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                //.securityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN")) // use STS token
                .build());

        // Configure the Client
        AsyncClient client = AsyncClient.builder()
                .region("<Your RegionId>") // Region ID
                //.httpClient(httpClient) // Use the configured HttpClient, otherwise use the default HttpClient (Apache HttpClient)
                .credentialsProvider(provider)
                //.serviceConfiguration(Configuration.create()) // Service-level configuration
                // Client-level configuration rewrite, can set Endpoint, Http request parameters, etc.
                .overrideConfiguration(
                        ClientOverrideConfiguration.create()
                                  // Endpoint 请参考 https://api.aliyun.com/product/live
                                .setEndpointOverride("live.aliyuncs.com")
                        //.setConnectTimeout(Duration.ofSeconds(30))
                )
                .build();

        // Parameter settings for API request
        AddLivePackageConfigRequest addLivePackageConfigRequest = AddLivePackageConfigRequest.builder()
                .regionId("<Your RegionId>")
                .domainName("<Your DomainName>")
                .appName("<Your AppName>")
                .streamName("<Your StreamName>")
                // Request-level configuration rewrite, can set Http request parameters, etc.
                // .requestConfiguration(RequestConfiguration.create().setHttpHeaders(new HttpHeaders()))
                .build();

        // Asynchronously get the return value of the API request
        CompletableFuture<AddLivePackageConfigResponse> response = client.addLivePackageConfig(addLivePackageConfigRequest);
        // Synchronously get the return value of the API request
        AddLivePackageConfigResponse resp = response.get();
        System.out.println(new Gson().toJson(resp));
        // Asynchronous processing of return values
        /*response.thenAccept(resp -> {
            System.out.println(new Gson().toJson(resp));
        }).exceptionally(throwable -> { // Handling exceptions
            System.out.println(throwable.getMessage());
            return null;
        });*/

        // Finally, close the client
        client.close();
    }

}
Note
  • For valid values of <Protocol>, see AddLivePackageConfig.

  • For information about server SDK for Java, see Use the server SDK for Java.

  • After you configure encapsulation for a stream, it is still accessible via the streaming URL of original quality.

Ingest and play an encapsulated stream

Ingest a stream

For smooth playback, ensure the GOP size of the ingested stream remains consistent.

In this example, Open Broadcaster Software (OBS) is used to ingest the stream. The following figure shows the recommended parameter settings.

image.png

Play an encapsulated stream

  1. Obtain the streaming URL of the encapsulated stream. The URL formats vary by streaming protocol:

    Protocol

    URL format

    HLS

    http://<DomainName>/<AppName>/<StreamName>.m3u8?aliyunols=on&auth_key=1725503*****

    DASH

    http://<DomainName>/<AppName>/<StreamName>.mpd?aliyunols=on&auth_key=17255038******

    LL-HLS

    http://<DomainName>/<AppName>/<StreamName>-llhls.m3u8?aliyunols=on&auth_key=1725503******
    Note

    The aliyunols=on parameter is mandatory in the streaming URL of an encapsulated stream.

    You can use live URL generator to generate streaming URLs. Depending on the configured container format and streaming protocol, the URLs generated for an encapsulated stream are different:

    Container format

    Streaming protocol

    URL format

    TS

    LL-HLS

    LL-HLS and HLS

    CMAF

    LL-HLS

    LL-HLS and HLS

    HLS

    HLS

    DASH

    DASH

    HLS & DASH

    HLS & DASH

  2. Play the stream using a compatible player. We recommend ApsaraVideo Player.

    In the following example, the web version of ApsaraVideo Player is used. image

    a. Set Video Type to Broadcast

    b. Enter the streaming URL. 

    c. Click the Preview tab. 

    Important

    When using ApsaraVideo Player web version, you must set up HTTPS certificates and set the Access-Control-Allow-Origin header for cross-domain access. For details, see HTTP/S settings and Configure HTTP Headers.

Advanced usage

Encapsulate transcoded streams

You can combine live stream encapsulation with transcoding to encapsulate transcoded streams.

Procedure

  1. Configure transcoding for the source stream. For more information, see Live stream transcoding.

  2. Call the AddLivePackageConfig operation and configure encapsulation for the source and transcoded streams. Set IgnoreTranscode to false. Sample code:

    // Specifies whether to encapsulate the transcoded stream. Default value: true, which indicates not encapsulating the transcoded stream.
    addLivePackageConfigRequest.setIgnoreTranscode(<false>);
  3. Generate the streaming URL of the encapsulated and transcoded stream.

    URL formats:

    • If you use a default or custom transcoding template, add the _transcoding template ID to StreamName.

      Sample LL-HLS URL for an encapsulated and transcoded stream:

      http://<DomainName>/<AppName>/<StreamName_Transcoding template ID>-llhls.m3u8?aliyunols=on&auth_key=1725503******
    • If you use a multi-bitrate transcoding template, add the _transcoding template group ID to StreamName.

    Note

    If you use encapsulation with multi-bitrate transcoding, the system follows the segment duration and container format settings in the encapsulation configuration.

    For example, if you set container format to CMAF and protocol to DASH, only DASH URL will be generated for the transcoded stream.

  4. Use a compatible player to play the stream.

Time shifting for encapsulated streams

You can utilize time shifting with live stream encapsulation. For more information, see Time shifting.

Note

If you use encapsulation with time shifting, the system follows the segment duration and container format settings in the encapsulation configuration.

API reference

APIs for live stream encapsulation