The time shifting feature allows you to play the content that has been streamed from the start time of live streaming to the current time. This topic describes how time shifting works and how you can send requests to use the feature.

How it works

Time shifting is based on the conventional HTTP Live Streaming (HLS) technology. A live stream is divided into TS segments, and the TS segments are distributed to users by using the HLS protocol. The .m3u8 playlist that is requested by users contains TS segment URLs that are constantly updated. In conventional HLS, TS segment URLs and TS files are not stored. As a result, earlier content that has been streamed cannot be played. After the time shifting feature is enabled, TS segment URLs and TS files are separately stored in a database and an Object Storage Service (OSS) bucket for up to 30 days. This allows users to play the content that has been streamed from the start time of live streaming to the current time. For more information about how to set the retention period, see Configure time shifting.

Usage notes

This feature allows a maximum of 100,000 users to watch a live stream at the same time. If you want to raise the upper limit, submit a ticket.

Send a request to implement time shifting during live streaming

A complete request to implement time shifting during live streaming comprises an HLS live streaming URL and time shifting parameters in the format of lhs_{type}_{format}_{unit}_{zone}. The following code provides an example:

http://example.com/AppName/StreamName.m3u8?aliyunols=on&lhs_start_human_s_8=20171024160220&lhs_end_human_s_8=20171024160420
Note The aliyunols parameter is required and has a fixed value of on.

The following table describes the required time shifting parameters.

Parameter Description
type The type of time. Valid values:
  • start: the start time of live streaming.
  • end: the end time of live streaming.
  • vodend: the end time of video-on-demand (VOD) playback.
    Note If you set this parameter to vodend, the video is played back in VOD mode. In this case, all the TS files generated within a specified period are returned at the same time, including the endlist tags.
  • offset: the time shift offset.
format The format of time. Valid values:
  • unix: UNIX timestamp.
  • human: yyyyMMddHHmmss. Example: 20170809230130.
unit The unit of time. Valid values:
  • s: seconds
  • ms: milliseconds
  • us: microseconds
  • ns: nanoseconds
Note You can query the valid duration for time shifting and data volume for a specified domain name in the ApsaraVideo Live console. For more information, see Usage statistics. Alternatively, you can send a request to obtain the statistics, For more information, see Send a request to query time shifting data.
zone The time zone. Valid values: 0 to 9. The value indicates the number of hours to be added to Coordinated Universal Time (UTC). A value of 0 indicates the UTC time. A value of 8 indicates UTC+8.
Note If the format parameter is set to unix, you must set the zone parameter to 0.

Examples of 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: indicates that the time shift offset is 30 minutes.

Send a request to query time shifting data

A request to query time shifting data comprises a request URL and parameters. A request URL is in the format of http://{domain}/openapi/timeline/query. The following code provides two examples:

// Without authentication information
http://example.com/openapi/timeline/query?aliyunols=on&app=bbb&stream=cc&format=ts&lhs_end_unix_s_0=1513334270&lhs_start_unix_s_0=1513334255
// With authentication information
http://example.com/openapi/timeline/query?auth_key=1606204918-0-0-3e898a5f491fedb113d17aad7c091dde&aliyunols=on&app=zzb-test&stream=zzb-shiyi&format=ts&lhs_start_unix_s_0=1606200900&lhs_end_unix_s_0=1606202520
Item Description
Request method GET
URL The request URL, in the format of http://{domain}/openapi/timeline/query. {domain} specifies the streaming domain.
Parameters
  • aliyunols: required. You must set the value to on.
  • app: required. The name of the application.
  • stream: required. The name of the live stream.
  • format: required. The format of the time shifting data to be queried. Supported formats are .ts and .flv.
  • lhs_start_unix_s_0: required. The start timestamp. Unit: seconds.
  • lhs_end_unix_s_0: required. The end timestamp. Unit: seconds.
Note If you have enabled Alibaba Cloud CDN-based authentication, you must add the authentication parameter auth_key. You can use the console or write code to generate a value for auth_key. For more information, see Configure URL signing or URL signing demos.

The following sample response is returned:

{
  "retCode": 0,
  "description": "success",
  "content": {
    "current": 1514269063,
    "timeline": [
      {
        "start": 1514269054,
        "end": 1514269058
      },
      {
        "start": 1514269058,
        "end": 1514269062
      }
    ]
  }
}
Parameter Description
current The current system time. The player aligns the time with the value of this parameter.
timeline The valid duration for time shifting. This value is an array. Each array element is a map that indicates a valid time shifting period.
start The start UNIX timestamp of the time shifting period. Unit: seconds.
end The end UNIX timestamp of the time shifting period. Unit: seconds.