Time shifting

更新时间:
复制 MD 格式

Time shifting allows viewers to play back a live stream from its start time to the current time. This topic describes how time shifting works and how to send requests.

Use cases

The time shifting feature allows viewers to rewind a live stream during playback. For example, during a live sports broadcast, viewers can use time shifting to re-watch parts of the event.

How it works

ApsaraVideo Live slices streams into TS segments and distributes them to viewers by using the HLS protocol. A viewer's request for an M3U8 playlist contains a constantly updated list of TS segment addresses. For standard HLS live streaming, the TS segment addresses and their corresponding TS files are not saved. This means you cannot rewind the live stream. When you enable time shifting, ApsaraVideo Live saves the TS segment information and files. This lets you rewind the video from the start of the live stream to the current time.

Limitations

Time shifting supports a maximum of 100,000 concurrent viewers. To support more viewers, submit a ticket. For more information, see Contact us.

Usage

Note
  • Using the time shifting feature incurs time shifting fees. You are charged based on the amount of time-shifted data written and the specifications of time-shifted playback. For more information about the billing rules, see Time shifting fees.

  • For more information about the regions that support the time shifting feature, see Supported regions.

To use time shifting, you must complete the following two steps:

  1. Configure the time shifting feature.

    Note

    You must enable this feature to save live stream content for time shifting.

  2. Send a request from the client to use the time shifting feature.

Configure time shifting

Configure time shifting in the console

  1. Log on to the ApsaraVideo Live console.

  2. In the left-side navigation pane, choose Feature Management > Time Shifting to go to the Time Shifting page.

  3. Select the streaming domain that you want to configure.

  4. Click Add.

  5. Configure time shifting.

    The following table describes the parameters for the time shifting configuration.

    Parameter

    Description

    AppName

    The application name. This configuration takes effect only when the AppName matches the AppName used for stream ingest. The name can be up to 255 characters in length and can contain digits, uppercase letters, lowercase letters, hyphens (-), and underscores (_). Hyphens and underscores cannot be at the beginning of the name. To configure time shifting at the domain level, enter an asterisk (*).

    Stream Name

    The stream name.

    Time-shift Scope

    • Original Only: Only the original stream supports time shifting.

    • Original & Transcoded: Both original and transcoded streams support time shifting.

    Retention Period

    ApsaraVideo Live offers the following retention periods:

    • 1 day

    • 3 days

    • 7 days

    • 15 days

    • 30 days

    Note
    • After you configure time shifting, you must re-ingest the stream for the configuration to take effect.

    • You can directly access the time-shifted stream by using the URL that corresponds to the streaming domain. For more information about the URL specifications, see Time shifting rules.

    • If a primary streaming domain is associated with a sub-streaming domain, you must enable time shifting for the sub-streaming domain. Otherwise, the time shifting configuration does not take effect for the sub-streaming domain.

  6. Click OK.

Configure time shifting by using an API

// This file is auto-generated, don't edit it. Thanks.
package com.aliyun.sample;
import com.aliyun.tea.*;
public class Sample {
    /**
     * <b>description</b> :
     * <p>Initializes a client by using credentials.</p>
     * @return Client
     * 
     * @throws Exception
     */
    public static com.aliyun.live20161101.Client createClient() throws Exception {
        // For production environments, we recommend using a more secure, credential-free method. For more information about how to configure credentials, see https://help.aliyun.com/document_detail/378657.html.
        com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                .setCredential(credential);
        // For the endpoint, see https://api.aliyun.com/product/live.
        config.endpoint = "live.aliyuncs.com";
        return new com.aliyun.live20161101.Client(config);
    }
    public static void main(String[] args_) throws Exception {
        com.aliyun.live20161101.Client client = Sample.createClient();
        com.aliyun.live20161101.models.OpenLiveShiftRequest openLiveShiftRequest = new com.aliyun.live20161101.models.OpenLiveShiftRequest()
                .setRegionId("<Your RegionId>")
                .setDomainName("<Your DomainName>")
                .setAppName("<Your AppName>")
                .setStreamName("<Your StreamName>");
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // When you copy the code to run, print the API response on your own.
            client.openLiveShiftWithOptions(openLiveShiftRequest, runtime);
        } catch (TeaException error) {
            // This is for demonstration purposes only. In your production environment, handle exceptions with care and do not ignore them.
            // Error message
            System.out.println(error.getMessage());
            // Diagnostic address
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // This is for demonstration purposes only. In your production environment, handle exceptions with care and do not ignore them.
            // Error message
            System.out.println(error.getMessage());
            // Diagnostic address
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }        
    }
}
Note
  • You can set AppName to an asterisk (*) to apply the configuration to all live streams under the specified domain.

  • You can set StreamName to an asterisk (*) to apply the configuration to all live streams under the specified AppName.

  • After you add the configuration, you can call the DescribeLiveShiftConfigs operation to query the time shifting configurations of a specific domain.

  • For more information about how to use the Java SDK, see Java SDK User Guide.

  • You must re-ingest the stream for the configuration to take effect.

  • For more information about the parameters, see OpenLiveShift.

Requesting time-shifted playback

After you configure time shifting, ApsaraVideo Live saves the TS segment files of the live stream. The client can then send a time-shifted playback request to play back previously recorded segments of the live stream.

The following code provides an example of a time-shifted playback request:

http://<DomainName>/<AppName>/<StreamName.m3u8>?aliyunols=on&lhs_offset_unix_s_0=300&auth_key=3sdda******

As shown in the example, the time shifting request is similar to a live streaming URL for an M3U8 playlist but includes two additional parameters. aliyunols=on is a required parameter, and lhs_offset_unix_s_0=300 indicates a rewind of 300 seconds.

Note
  • When you send a time shifting request through a content delivery network (CDN), you must include the aliyunols=on parameter.

  • Currently, time-shifted playback supports only live streaming URLs in M3U8 format.

  • Use ApsaraVideo Player to play back time-shifted content. For more information about how to use ApsaraVideo Player, see Player SDK.

In this example, the live content is rewound by 300 seconds. When you play back time-shifted content, you can use the lhs_offset_unix_s_0 parameter to set the playback time. The parameter format is lhs_{type}_{format}_{unit}_{zone}.

The following table describes the variables in the parameter.

Type

Format

Unit

Zone

The time type. Valid values:

  • start: the playback start time.

  • end: the playback end time.

  • vodend: specifies the playback end time in video-on-demand (VOD) mode.

    Note

    When type is vodend, playback is in VOD mode. The server returns a complete playlist of all TS segments within the specified time range at once, terminated by an endlist tag.

  • offset: the offset time for rewinding.

The time format for time shifting. Valid values:

  • unix: UNIX timestamp.

  • human: in YYYYMMDDHHMMSS format. Example: 20170809230130.

The time unit for time shifting. Valid values:

  • s: second.

  • ms: millisecond.

The time zone. Valid values: 0 to 9, which indicates UTC+*. 0 indicates UTC, and 8 indicates China Standard Time.

Note

If you set format to unix, set zone to 0.

The following examples show the time shifting parameters:

  • lhs_start_human_s_8=20170809200010

  • lhs_start_unix_s_0=1502280113

  • lhs_end_human_s_8=20170809200010

  • lhs_vodend_unix_s_0=1502280113

  • lhs_offset_unix_ms_0=1800000 (rewind by 30 minutes)

Important
  • You must specify either lhs_start or lhs_offset. If you specify both lhs_start and lhs_offset, lhs_offset takes precedence.

  • lhs_end/lhs_vodend is an optional parameter. If you do not specify lhs_end/lhs_vodend, playback continues in live mode until the stream ingest ends.

  • If you specify lhs_end, playback continues in live mode until the specified lhs_end time.

  • If you specify lhs_vodend, playback continues in video-on-demand (VOD) mode until the specified lhs_vodend time. In VOD mode, all TS segments are returned at once, and you can use the player progress bar to fast forward and rewind.

  • If you specify both lhs_end and lhs_vodend, lhs_vodend takes precedence.

If you do not know the specific start and end times, you can query the time shifting timeline to obtain them.

The following example shows how to query the time shifting timeline:

// Replace the values in angle brackets (<>) with your actual values.
http://<DomainName>/openapi/timeline/query?aliyunols=on&app=<AppName>&stream=<StreamName>&format=ts&lhs_start_unix_s_0=<StartTime>&lhs_end_unix_s_0=<endTime>&auth_key=<auth_key>

The following table describes the parameters in the example.

Parameter

Description

Request method

GET

URL

The request URL. Example: http://{domain}/openapi/timeline/query, where {domain} is your streaming domain.

Parameters

  • aliyunols (required): on. (fixed field)

  • app (required): The application name.

  • stream (required): The stream name.

  • format (required): ts. (fixed field)

    Note

    Currently, the API supports querying only time-shifted data in the ts format.

  • lhs_start_unix_s_0 (required): The UNIX timestamp of the start of the query time range. Example: 1724295706. Unit: seconds.

  • lhs_end_unix_s_0 (required): The UNIX timestamp of the end of the query time range. Example: 1724317306. Unit: seconds.

  • auth_key: The authentication key. This key uses the same encryption algorithm as the key used for the streaming URL. If you are not familiar with authentication and encryption, see Authentication Code Examples.

Common error handling

  • 403: Check whether the encryption process for your auth_key value is correct.

The following example shows a sample response:

{
  "retCode": 0,
  "description": "success",
  "content": {
    "current": 1514269063,
    "timeline": [
      {
        "start": 1514269054,
        "end": 1514269058
      }
    ]
  }
}

Parameter

Description

current

The current system time. The player can use this field to synchronize the time.

timeline

The valid time shifting period, which includes the start and end UNIX timestamps.

start

The start time of the valid segment (UNIX timestamp). Unit: seconds.

end

The end time of the valid segment (UNIX timestamp). Unit: seconds.

Note
  • Typically, one stream ingest generates one timeline object. The start time corresponds to the live stream's start time, and the end time is close to the current time or the live stream end time. However, factors such as stream interruptions, re-ingestion, or network fluctuations can generate multiple timeline objects.

  • You can query the time shifting data volume for a specific domain in the console. For more information, see Query usage.

Advanced usage

Time-shifted transcoded playback

You can use the time shifting feature with the transcoding feature to play back transcoded streams. To play back transcoded streams with time shifting, you must first configure transcoding. For more information about how to configure transcoding, see Live stream transcoding.

This section assumes that you have completed the transcoding configuration.

When you configure time shifting, you must also generate time-shifted data for transcoded streams. The following example shows the sample code:

// Specifies whether to ignore the corresponding transcoded stream when generating time-shifted data. Valid values: true and false. Default value: true.
openLiveShiftRequest.setIgnoreTranscode("<false>");

To enable time-shifted playback, add the time-shifting parameters to the transcoded stream URL.

The following example shows a playback URL:

http://<DomainName>/<AppName>/<StreamName_TranscodingTemplateID.m3u8>?aliyunols=on&lhs_offset_unix_s_0=300&auth_key=3sdda******
Note
  • You must re-ingest the stream to play back the transcoded stream with time shifting.

  • For transcoding configurations that are triggered by stream pulling, playing back a transcoded stream with time shifting does not trigger transcoding. You must play the live transcoded stream in advance to trigger transcoding. You can also configure transcoding to be triggered by stream ingest.

Important
  • Currently, the time shifting feature does not support multi-bitrate transcoded streams.

Time-shifted encapsulated playback

You can use the Time Shifting feature in conjunction with the Encapsulation feature.

Note

ApsaraVideo Live's encapsulation service reduces latency by using modern protocols like Low-Latency HTTP Live Streaming (LL-HLS) and the CMAF container format. LL-HLS achieves end-to-end latencies of 3 to 5 seconds by using shorter segments (0.2 to 1 second) and blocking playlist loads. The CMAF format offers broader device and browser compatibility than traditional TS and supports newer codecs like H.265.

If you are not familiar with the live stream encapsulation feature, see Live stream encapsulation.

This section assumes that you have completed the live stream encapsulation configuration.

To play back encapsulated streams with time shifting, you do not need to modify the time shifting configuration. You can simply add the time shifting parameters to the encapsulated stream URL.

The following example shows a playback URL:

http://<DomainName>/<AppName>/<StreamName-EncapsulationFormat.m3u8>?aliyunols=on&lhs_offset_unix_s_0=300&auth_key=3sdda******
Note
  • You must re-ingest the stream to play back the encapsulated stream with time shifting.

  • To play back an encapsulated and transcoded stream with time shifting, you can simply add the time shifting parameters to the encapsulated and transcoded stream URL.

References

For more information about the APIs for time shifting, see Time shifting.