Media Push (Web SDK 4.x)

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 have read the quickstart guides and implemented basic real-time audio and video functions in your project.

Follow these steps to push streams to the CDN:

1. Before publishing the stream, call AgoraRTCClient.setLiveTranscoding for the hosts in the channel to set the configurations for transcoding, such as the resolution, bitrate, frame rate, background color, and watermarks. If you want to manage the layout of multiple hosts in the Media Push, set the transcodingUsers parameter, as shown in the following sample code.

2. Call AgoraRTCClient.startLiveStreaming for the hosts in the channel to publish their local stream to a CDN address. Use the transcodingEnabled parameter to set whether or not to enable transcoding.

3. Call AgoraRTCClient.stopLiveStreaming for the hosts in the channel to remove a CDN address.

4. Listen for the AgoraRTCClient.on("live-streaming-error") and AgoraRTCClient.on("live-streaming-warning") events to get the errors and warnings that occur during Media Push.

Sample code

The client object in the following sample code is created by calling AgoraRTC.createClient.

// CDN transcoding configurations.
const LiveTranscoding = {
  // Width of the video (px). The default value is 640.
  width: 640,
  // Height of the video (px). The default value is 360.
  height: 360,
  // Bitrate of the video (Kbps). The default value is 400.
  videoBitrate: 400,
  // Frame rate of the video (fps). The default value is 15.
  videoFramerate: 15,
  audioSampleRate: AgoraRTC.AUDIO_SAMPLE_RATE_48000,
  audioBitrate: 48,
  audioChannels: 1,
  videoGop: 30,
  // 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.
  videoCodecProfile: AgoraRTC.VIDEO_CODEC_PROFILE_HIGH,
  userCount: 1,
  userConfigExtraInfo: "",
  backgroundColor: 0x000000,
  // Add an online PNG watermark image to the video. You can add only one watermark.
  watermark: {
          url: "http://www.com/watermark.png",
          x: 0,
          y: 0,
          width: 160,
          height: 160,
      },
  // Set the layout for each user.
  transcodingUsers: [{
          x: 0,
          y: 0,
          // If you don't want to show a user's video, set both the width and height to 1 to make the user's viewport a dot.
          // Do not set the width and height to 0 at the same time. If you do so, the SDK throws an error.
          width: 640,
          height: 360,
          zOrder: 0,
          alpha: 1.0,
          // The uid must be identical to the uid used in AgoraRTCClient.join.
          uid: 1232,
        }],
};

// This is an asynchronous method. Please ensure that the asynchronous operation completes before conducting the next operation.
client.setLiveTranscoding(LiveTranscoding).then(() => {
  console.log("set live transcoding success");
});

// Add 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 setLiveTranscoding. Agora does not recommend transcoding in the case of a single host.
// This is an asynchronous method. Please ensure that the asynchronous operation completes before conducting the next operation.
client.startLiveStreaming("your RTMP URL", true).then(() => {
  console.log("start live streaming success");
})

// Remove a URL and stop live streaming. This is an asynchronous method. Please ensure that the asynchronous operation completes before conducting the next operation.
client.stopLiveStreaming("your RTMP URL").then(() => {
  console.log("stop live streaming success");
})

API reference

• AgoraRTCClient.setLiveTranscoding
• AgoraRTCClient.startLiveStreaming
• AgoraRTCClient.stopLiveStreaming
• AgoraRTCClient.on("live-streaming-error")
• AgoraRTCClient.on("live-streaming-warning")

Considerations

• A maximum of 17 hosts can be supported in the same live-broadcast channel.
• Set the value of videoBitrate according to the Video Bitrate Table. If you set a bitrate beyond the recommended range, the SDK automatically adjusts it to a value within the range.
• To prevent logic errors, Agora suggests using different URLs for Media Push with transcoding and Media Push without transcoding.
• In the case of a single host, Agora does not recommend transcoding. You can skip Step 1, and call Client.startLiveStreaming directly with enableTranscoding set as false. Please use AgoraRTC.createClient({mode: "live", codec: "h264"}) in this case.