Media Push

Introduction

The Agora SDK provides the functionality to convert the audio and video streams of hosts from Agora private protocols to standard protocols (RTMP and RTMPS) and then push those streams to CDN. The CDN audience can watch live streams by clicking the corresponding URLs. This function can enrich the distribution channels of live media streams and facilitate the promotion of live streaming.

Prerequisites

Ensure that you enable the Media Push service before using this function:

1. Log in to Agora Console, and click the Project Management icon on the left navigation panel.

2. On the Project Management page, find the project for which you want to enable the Media Push service, and click the edit icon.

   

3. Under Real-time engagement extensions, find Media Push, and click Enable.

   

4. Click the Status button to enable the Media Push Client-side SDK API service. Read the pop-up prompt carefully, and then click Save.

   The service cannot be disabled after enabling.

5. The Enable button of Media Push changes to the Config button, which allows you to configure the Media Push service.

   

Implementation

Before proceeding, ensure that you implement basic interactive live streaming in your project. See Start Live Interactive Streaming for details.

Refer to the following steps to push streams to the CDN:

1. The host in a channel calls the SetLiveTranscoding method to set the transcoding parameters of media streams (LiveTranscoding), such as the resolution, bitrate, frame rate, and position of any watermark/background. If you need a transcoded picture, set the picture-in-picture layout for each user in the TranscodingUser class, as described in Sample code.

   The OnTranscodingUpdatedHandler callback occurs when the LiveTranscoding class updates, and reports update information to the local host.

2. The host in a channel calls the AddPublishStreamUrl method to add a media stream to the CDN.

   Use transcodingEnabled to set whether transcoding is enabled or not.

3. The host in a channel cans the RemovePublishStreamUrl method to remove a media stream from the Media Push.

When the state of media streams pushed to the CDN changes, the SDK triggers the OnRtmpStreamingStateChangedHandler callback to report current state of pushing streams to the local host. The local host can troubleshoot with the error code when exceptions occur.

Sample code

// CDN transcoding settings.
LiveTranscoding transcoding = new LiveTranscoding();
transcoding.audioSampleRate = AUDIO_SAMPLE_RATE_TYPE.AUDIO_SAMPLE_RATE_44100;
transcoding.audioChannels = 2;
transcoding.audioBitrate = 48;
// Width of the video (px). The default value is 360.
transcoding.width = 360;
// Height of the video (px). The default value is 640.
transcoding.height = 640;
// Video bitrate of the video (Kbps). The default value is 400.
transcoding.videoBitrate = 400;
// Video framerate of the video (fps). The default value is 15. Agora adjusts all values over 30 to 30.
transcoding.videoFramerate = 15;
// If userCount > 1，set the layout for each user with transcodingUsers.
transcoding.userCount = 1;
// Video codec profile. Choose to set as Baseline (66), Main (77), or High (100). If you set this parameter to other values, Agora adjusts it to the default value 100.
transcoding.videoCodecProfile = VIDEO_CODEC_PROFILE_TYPE.VIDEO_CODEC_PROFILE_HIGH;
// Sets the output layout for each user.
TranscodingUser user = new TranscodingUser();
// The uid must be identical to the uid used in joinChannel().
user.uid = 123456;
user.x = 0;
user.y = 0;
user.audioChannel = 0;
user.width = 640;
user.height = 480;
user.alpha = 1;
transcoding.transcodingUsers = new TranscodingUser[] { user };
transcoding.userCount = (uint)transcoding.transcodingUsers.Length; 
transcoding.transcodingUsers = user;

// CDN transcoding settings when using transcoding.
mRtcEngine.SetLiveTranscoding(transcoding);
// Adds a URL to which the host pushes a stream. Set the transcodingEnabled parameter as true to enable the transcoding service. Once transcoding is enabled, you need to set the live transcoding configurations by calling the SetLiveTranscoding method. Agora does not recommend transcoding in the case of a single host.
mRtcEngine.AddPublishStreamUrl(url, true);
// Removes a URL to which the host pushes a stream.
mRtcEngine.RemovePublishStreamUrl(url);

Example 1: Two-host tile horizontally

Canvas:
     width: 640
     height: 360
     backgroundColor: #FFFFFF

User0:
      userId: 123
      x: 0
      y: 0
      width: 320
      height: 360
      zOrder: 1
      alpha: 1.0

User1:
      userId: 456
      x: 320
      y: 0
      width: 320
      height: 360
      zOrder: 1
      alpha: 1.0

Example 2: Three-host tile vertically

Canvas:
      width: 360
      height: 640
      backgroundColor: #FFFFFF

   User0:
      userId: 123
      x: 0
      y: 0
      width: 360
      height: 640
      zOrder: 1
      alpha: 1.0

   User1:
       userId: 456
       x: 0
       y: 320
       width: 180
       height: 320
       zOrder: 2
       alpha: 1.0

   User2:
       userId: 789
       x: 180
       y: 320
       width: 180
       height: 320
       zOrder: 2
       alpha: 1.0

Example 3: One full screen + floating thumbnails

Canvas:
   width: 360
   height: 640
   backgroundColor: #FFFFFF

User0:
   userId: 123
   x: 0
   y: 0
   width: 360
   height: 640
   zOrder: 1
   alpha: 1.0

User1:
    userId: 456
    x: 45
    y: 390
    width: 110
    height: 213
    zOrder: 2
    alpha: 1.0

User2:
    userId: 789
    x: 185
    y: 390
    width: 110
    height: 213
    zOrder: 2
    alpha: 1.0

API reference

• SetLiveTranscoding
• AddPublishStreamUrl
• RemovePublishStreamUrl
• OnTranscodingUpdatedHandler
• OnRtmpStreamingStateChangedHandler

Considerations

• Up to 17 hosts can be supported in the same live streaming channel.

• This service is not free. Agora charges for the use of this service based on the duration of the audio and video transcoding.

• Agora supports pushing streams in the RTMP and RTMPS protocols, but the RTMPS protocol is supported only in transcoding mode.

• If you push the stream directly without transcoding for a single host, you can skip Step1, and call the AddPublishStreamUrl method directly with transcodingEnabled (false).

  Currently, Agora only supports pushing H.264 (default) streams to the CDN.

• Ensure that the stream URLs used in the transcoding mode and non-transcoding mode are different.