Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

You are looking at Interactive Live Streaming v3.x Docs. The newest version is  Interactive Live Streaming 4.x

Android
iOS
macOS
Windows C++
Windows C#
Unity
Flutter
React Native
Electron
Cocos Creator
Cocos2d-x

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.

The Media Push service is not free. Agora charges for the use of this service based on the transcoding configuration and streaming duration. See Pricing for Media Push. If you additionally enable the LBHQ feature, discuss the charges with sales-us@agora.io.

1646028684726

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.

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

  2. 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.

  1. 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:

1638787335427

  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.

    • If you need to stop the live streaming at multiple addresses, call stop multiple times and pass in the corresponding CDN addresses.
    • After stopping the streaming, you can receive the onRtmpStreamingStateChanged callback reporting the streaming state as IDLE(0). If you receive another streaming state, see Exception Handling for Media Push.

Streaming without transcoding

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

1638787318955

  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.

    • If you need to stop the live streaming at multiple addresses, call stop multiple times and pass in the corresponding CDN addresses.
    • After stopping the streaming, you can receive the onRtmpStreamingStateChanged callback reporting the streaming state as IDLE(0). If you receive another streaming state, see Exception Handling for Media Push.

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 RTMPStreaming.

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.

ResolutionFrame rate (fps)Bitrate (Kbps)
160 × 12015130
120 × 12015100
320 × 18015280
180 × 18015200
240 × 18015240
320 × 24015400
240 × 24015280
424 × 24015440
640 × 36015800
360 × 36015520
640 × 360301200
360 × 36030800
480 × 36015640
480 × 36030980
640 × 480151000
480 × 48015800
640 × 480301500
480 × 480301200
848 × 480151220
848 × 480301860
640 × 48010800
1280 × 720152260
1280 × 720303420
960 × 720151820
960 × 720302760

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 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.

    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 calls the addPublishStreamUrl method to add a media stream to the CDN. The address can be dynamically added or deleted after the stream is pushed.

    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.


_38
// Java
_38
// CDN transcoding settings.
_38
LiveTranscoding config = new LiveTranscoding();
_38
config.audioSampleRate = TYPE_44100;
_38
config.audioChannels = 2;
_38
config.audioBitrate = 48;
_38
// Width of the video (px). The default value is 360.
_38
config.width = 360;
_38
// Height of the video (px). The default value is 640.
_38
config.height = 640;
_38
// Video bitrate of the video (Kbps). The default value is 400.
_38
config.videoBitrate = 400;
_38
// Video framerate of the video (fps). The default value is 15. Agora adjusts all values over 30 to 30.
_38
config.videoFramerate = 15;
_38
// If userCount > 1,set the layout for each user with transcodingUser.
_38
config.userCount = 1;
_38
// 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.
_38
config.videoCodecProfile = HIGH;
_38
_38
// Sets the output layout for each user.
_38
LiveTranscoding transcoding = new LiveTranscoding();
_38
LiveTranscoding.TranscodingUser user = new LiveTranscoding.TranscodingUser();
_38
user.uid = 123456;
_38
transcoding.addUser(user);
_38
user.x = 0;
_38
user.audioChannel = 0;
_38
user.y = 0;
_38
user.width = 640;
_38
user.height = 720;
_38
_38
// CDN transcoding settings when using transcoding.
_38
rtcEngine.setLiveTranscoding(transcoding);
_38
_38
// 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.
_38
rtcEngine.addPublishStreamUrl(url, true);
_38
_38
// Removes a URL to which the host pushes a stream.
_38
rtcEngine.removePublishStreamUrl(url);

API reference

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

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

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

Interactive Live Streaming