Before uploading audio or video data to OSS through the RTMP protocol, you must use PutLiveChannel to create a LiveChannel. PutLiveChannel returns a URL used to push streams through the RTMP protocol and a URL used to play the uploaded data.

You can use the URLs returned by PutLiveChannel to push streams and play the uploaded data. In addition, you can perform operations on the created LiveChannel, such as query the stream pushing status, query stream pushing records, or disable stream pushing.

Request syntax

PUT /ChannelName?live HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT date
Content-Length: Size
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<LiveChannelConfiguration>
  <Description>ChannelDescription</Description>
  <Status>ChannelStatus</Status>
  <Target>
     <Type>HLS</Type>
     <FragDuration>FragDuration</FragDuration>
     <FragCount>FragCount</FragCount>
     <PlaylistName>PlaylistName</PlaylistName>
  </Target>
  <Snapshot>
    <RoleName>Snapshot ram role</RoleName>
    <DestBucket>Snapshot dest bucket</DestBucket>
    <NotifyTopic>Notify topic of MNS</NotifyTopic>
    <Interval>Snapshot interval in second</Interval>
  </Snapshot>
</LiveChannelConfiguration>

Request elements

Element Type Description Required
LiveChannelConfiguration Container Specifies the container used to store the settings of the LiveChannel.

Sub-node: Description、Status、Target

Parent node: None

Yes
Description String Specifies the description of the LiveChannel, which is 128 bytes in maximum.

Sub-node: None

Parent node: LiveChannelConfiguration

No
Status Enumerated string Specifies the status of the LiveChannel.

Sub-node: None

Parent node: LiveChannelConfiguration

Valid values: enabled and disabled

Default value: enabled

No
Target Container Specifies the container used to store the settings for storing uploaded data.

Sub-node: Type, FragDuration, FragCount, and PlaylistName

Parent node: LiveChannelConfiguration

Yes
Type Enumerated string Specifies the format that the uploaded data is stored as.

Sub-node: None

Parent node: Target

Valid value: HLS

Yes
FragDuration String Specifies the duration (in seconds) of each ts file when the value of Type is HLS.

Sub-node: None

Parent node: Target

Default value: 5

Value range: [1, 100]

No
FragCount String Specifies the number of ts files included in the m3u8 file when the value of Type is HLS.

Sub-node: None

Parent node: Target

Default value: 3

Value range: [1, 100]

No
PlaylistName String Specifies the name of the m3u8 file generated when the value of Type is HLS. The name must be ended with ".m3u8" and in the following length range: [6, 128].

Sub-node: None

Parent node: Target

Default value: playlist.m3u8

Value range: [6, 128]

No
Snapshot Container Specifies the container used to store the Snapshot (high-frequent snapshot operation) options.

Sub-node: RoleName, DestBucket, NotifyTopic, Interval, and PornRec

Parent node: Snapshot

No
RoleName String Specifies the name of the role who performs the high-frequent snapshot operations. The role must have the permission to write data into DestBucket and send messages to NotifyTopic.

Sub-node: None

Parent node: Snapshot

No
DestBucket String Specifies the bucket where the snapshots are stored. The DestBucket and the current bucket must be owned by the same user.

Sub-node: None

Parent node: Snapshot

No
NotifyTopic String Specifies the topic of the MNS used to notify the user of the result of high-frequent snapshot operations.

Sub-node: None

Parent node: Snapshot

No
Interval Numeric Specifies the interval (in seconds) between each snapshot operation. If no key frame (I-frame) exists in an interval, no snapshot is captured in the interval.

Sub-node: None

Parent node: Snapshot

Value range: [1, 100]

No

Detail analysis

  • ChannelName must conform to the naming conventions for objects and cannot include "/".
  • The default values of FragDuration and FragCount take effect only when the values are both not specified. If you specify the value of one of the two parameters, the value of the other must also be specified.
  • If the value of Type is HLS, OSS updates the generated m3u8 file each time when a ts file is generated. The number of newly-generated ts files included in the m3u8 file is specified by FragCount.
  • If the value of Type is HLS, when the duration of the video or audio data in the current ts file reaches the value of FragDuration, OSS generates a new ts file when receiving the next key frame. If OSS does not receive the next key frame with in a time peroid (calculated by max(2*FragDuration, 60s)), a new ts file is generated, which results lag in audio or video playing.

Response element

Element Type Description
CreateLiveChannelResult Container Specifies the container used to store the response fo the CreateLiveChannel request.

Sub-nodes: PublishUrls and PlayUrls

Parent node: None

PublishUrls Container Specifies the container used to store the stream pushing URL.

Sub-node: Url

Parent node: CreateLiveChannelResult

Url String Specifies the stream pushing URL.

Sub-node: None

Parent node: PublishUrls

PlayUrls Container Specifies the container used to store the stream pushing URL.

Sub-node: Url

Parent node: CreateLiveChannelResult

Url String Specifies the URL used to play the audio or video data.

Sub-node: None

Parent node: PlayUrls

Detail analysis

  • The stream pushing URL is not signed. If the ACL for the bucket is not public-read-write, you must sign the URL before accessing it.
  • The URL used to play the audio or video data is not signed. If the ACL for the bucket is private, you must sign the URL before accessing it.

Examples

Request example

PUT /test-channel?live HTTP/1.1
Date: Wed, 24 Aug 2016 11:11:28 GMT
Content-Length: 333
Host: test-bucket.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS YJjHKOKWDWINLKXv:hvwOZJRh8toAj3DZvtsuPgf+agA=
<?xml version="1.0" encoding="utf-8"?>
<LiveChannelConfiguration>
    <Description/>
    <Status>enabled</Status>
    <Target>
        <Type>HLS</Type>
        <FragDuration>2</FragDuration>
        <FragCount>3</FragCount>
    </Target>
    <Snapshot>
        <RoleName>role_for_snapshot</RoleName>
        <DestBucket>snapshotdest</DestBucket>
        <NotifyTopic>snapshotnotify</NotifyTopic>
        <Interval>1</Interval>
     </Snapshot>
</LiveChannelConfiguration>

Response example

HTTP/1.1 200
content-length: 259
server: AliyunOSS
x-oss-server-time: 4
connection: close
x-oss-request-id: 57BD8419B92475920B0002F1
date: Wed, 24 Aug 2016 11:11:28 GMT
x-oss-bucket-storage-type: standard
content-type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<CreateLiveChannelResult>
  <PublishUrls>
    <Url>rtmp://test-bucket.oss-cn-hangzhou.aliyuncs.com/live/test-channel</Url>
  </PublishUrls>
  <PlayUrls>
    <Url>http://test-bucket.oss-cn-hangzhou.aliyuncs.com/test-channel/playlist.m3u8</Url>
  </PlayUrls>
</CreateLiveChannelResult>