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

To reduce the difficulty of integrating Media Push, as of v3.6.0, Agora optimizes the API design of Media Push and improves the handling of network issues within Media Push clients and servers, as detailed in the release notes. This section describes how to use the SDK v3.6.0 or later to implement Media Push. If you need to implement Media Push using versions of the SDK earlier than v3.6.0, see how to implement an earlier version.

You can implement different types of Media Push depending on the live streaming scenario requires transcoded or non-transcoded streaming. Transcoding is essentially an encoding and decoding function used to mix multiple audio and video streams into one audio and video stream, which can guarantee the synchronization of multiple hosts' live streams seen by the audience. Therefore, generally speaking, in the case of multiple-hosts live streaming, you need to enable transcoding when pushing streams to CDN; in the case of single-host live streaming, only one media stream is pushed to the CDN, so you do not need to enable transcoding.

Streaming with transcoding

You can refer to the following API call sequence diagram and steps to implement streaming with transcoding:

1. Refer to Start Interactive Live Video Streaming or Start Interactive Live Audio Streaming to implement the basic audio and video interaction.

2. Call startRtmpStreamWithTranscoding and pass in the address of the Media Push and the transcoding configuration to start pushing transcoded streams to a CDN address.

   • The transcoding configuration includes the audio and video profile of the output transcoded streams, video layout of the hosts, watermarks, and media metadata. The audio and video profile includes audio bitrate, video bitrate, audio codec, and video codec. The media metadata includes SEI. See LiveTranscoding. In scenarios where there is streaming with transcoding, the userCount and transcodingUsers fields in the transcoding configuration are required. You can customize or use default values for the remaining fields in the configuration.
   • For live audio scenarios, leave the video-related fields in the transcoding configuration empty.
   • If you need to push streams to multiple addresses, call start multiple times.
   • If you have already started a live stream at one address, pushing another live stream to that address is not supported.
   • After each call to start, make sure to wait until you receive the onRtmpStreamingStateChanged callback reporting the streaming state as RUNNING(2) before performing any other actions. If you receive another streaming state, see Exception Handling for Media Push.

3. You can call updateRtmpTranscoding to dynamically update the transcoding configuration according to a scenario change, such as adjusting the number of hosts or the video layout of the hosts. After the transcoding configuration is updated successfully, the SDK triggers the onTranscodingUpdated callback.

4. Call stopRtmpStream and pass in the CDN address to stop the current live streaming.

Streaming without transcoding

You can refer to the following API call sequence diagram and steps to implement streaming without transcoding:

1. Refer to Start Interactive Live Video Streaming or Start Interactive Live Audio Streaming to implement the basic audio and video interaction. The uid parameter in the joinChannel method cannot be empty or 0; otherwise, the hosts in the channel cannot push any media streams to CDN.

2. Call startRtmpStreamWithoutTranscoding and pass in the address of the Media Push to start pushing non-transcoded streams to a CDN address.

   • If you need to push streams to multiple addresses, call start multiple times.
   • If you have already started a live stream at one address, pushing another live stream to that address is not supported.
   • After each call to start, make sure to wait until you receive the onRtmpStreamingStateChanged callback reporting the streaming state as RUNNING(2) before performing any other actions. If you receive another streaming state, see Exception Handling for Media Push.

3. Call stopRtmpStream and pass in the CDN address to stop the current live streaming.

Sample code

To show the code logic for starting the streaming, dynamically updating the transcoding configuration, and retrying the stream push in case of an exception, Agora provides an open-source sample project on GitHub, see RTMPStream.

Considerations

• This service is not free. Agora charges for the use of this service based on the duration of the audio and video transcoding.
• Agora recommends that you control the number of hosts involved in transcoding according to the actual output video. In any event, the number of the hosts in the same channel cannot exceed 17.
• Agora supports pushing streams in the RTMP and RTMPS protocols to CDN.
• To avoid errors in the code logic, ensure that the CDN addresses used in the transcoded and non-transcoded streaming are different.

Reference

This section provides references commonly used when using Media Push function.

Commonly used video profile

Agora recommends that you use the default values when setting the video resolution, frame rate, and bitrate of the output transcoded stream. You can also refer to the following table to set the values. If you set a bitrate beyond a reasonable range, the Agora server automatically adjusts the bitrate to stay within a reasonable range.

Implementation of earlier versions

This section describes how to implement Media Push using versions of the SDK earlier than v3.6.0.

1. Refer to Start Interactive Live Video Streaming or Start Interactive Live Audio Streaming to implement the basic audio and video interaction.

2. The host in a channel calls the setLiveTranscoding method to set the transcoding configuration of the media streams (LiveTranscoding), such as the resolution, bitrate, frame rate, and position of the watermark/background image. If you need a transcoded picture, set the picture-in-picture layout for each user in the TranscodingUser class.

   To push streams without transcoding for single-host live streaming, skip steps 2 and 3, directly call addPublishStreamUrl, and set transcodingEnabled (false).

3. The host in a channel can call the addPublishStreamUrl method to add a media stream to the CDN.

   Use transcodingEnabled to set whether transcoding is enabled or not.

4. (Optional) The host in a channel calls the setLiveTranscoding method again to update the transcoding configuration of media streams.

   When the transcoding configuration is updated, the SDK triggers the onTranscodingUpdated callback and reports the update information to the host.

5. The host in a channel calls the removePublishStreamUrl method to remove a media stream from the Media Push.

When the streaming state changes, the SDK triggers the onRtmpStreamingStateChanged callback to report the current streaming state to the host. Make sure to wait until you receive the onRtmpStreamingStateChanged callback before performing any other actions. If adding or removing a CDN address fails, see Exception Handling for Media Push.

// C++
// CDN transcoding settings.
LiveTranscoding config;
config.audioSampleRate = TYPE_44100;
config.audioChannels = 2;
config.audioBitrate = 48;
// Width of the video (px). The default value is 360.
config.width = 360;
// Height of the video (px). The default value is 640.
config.height = 640;
// Bitrate of the video (Kbps). The default value is 400.
cofig.videoBitrate = 400;
// Frame rate of the video (fps). The default value is 15. Agora adjusts all values over 30 to 30.
config.videoFramerate = 15;
// If userCount > 1, set the layout for each user with transcodingUser.
config.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 of 100.
config.videoCodecProfile = HIGH;

// Sets the output layout for each user.
config.transcodingUser = new TranscodingUser[config.userCount];
config.transcodingUser[0].uid = 123456;
config.transcodingUser[0].x = 0;
config.transcodingUser[0].audioChannel = 0;
config.transcodingUser[0].y = 0;
config.transcodingUser[0].width = 640;
config.transcodingUser[0].height = 720;

// CDN transcoding settings when using transcoding.
m_rtcEngine->setLiveTranscoding(config);

// 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.
m_rtcEngine->addPublishStreamUrl(url, true);

 if (config.transcodingUsers)
   {
      delete[] config.transcodingUsers;
   }

// Removes a URL to which the host pushes a stream.
m_rtcEngine->removePublishStreamUrl(url);

API reference

The following APIs are recommended by Agora when implementing Media Push:

• startRtmpStreamWithoutTranscoding
• startRtmpStreamWithTranscoding
• updateRtmpTranscoding
• stopRtmpStream
• onTranscodingUpdated
• onRtmpStreamingStateChanged
• onRtmpStreamingEvent

The following APIs are still functional but not recommended by Agora when implementing Media Push:

• setLiveTranscoding
• addPublishStreamUrl
• removePublishStreamUrl
• onStreamPublished
• onStreamUnpublished

Related docs

When using the Media Push function, you may also need to refer to the following docs:

• Pricing for Media Push
• Exception Handling for Media Push
• How to solve SEI-related issues?
• What is the relationship between the old and new callbacks of Media Push?
• Overview of the Media Push using RESTful API