Media Gateway quickstart

Media Gateway enables users to push content to Agora SD-RTN™ using standard streaming protocols such as RTMP and SRT. The channel host automatically publishes this streamed content to the correct channel. Possible use cases are:

• Enrich the viewing experience with commentary: Seamlessly inject high-definition video source streams into interactive channels to enhance the viewing experience. Multiple anchors from different locations watch and interact in real-time, adding depth to the media with their commentary.

• Low-latency distribution scenarios: Distribute content to viewers in a faster and more stable way than using a Content Deliver Network (CDN). In scenarios such as online auctions and bidding platforms, bidders receive a real-time video feed enabling them to swiftly place their bids.

• Recording to live broadcast: Enhance content quality and reduce live production complexity by injecting prerecorded media into a live broadcast. For example, a teacher records aspects of a lesson in advance and adds it to a live classroom. All students and teaching assistants watch the teacher's lecture, and interact in real-time.

• Avoid interruptions due to host switching: Background music is played continuously in a chat room without interruptions if the host leaves the channel.

Using Media Gateway RESTful API, you generate a streaming key. This key allows you to push online media streams as live video source streams into Agora channels.

With Media Gateway, you can employ advanced transcoding capabilities on media streams for enhanced distribution. To enable and configure transcoding options, you use the Media Gateway RESTful API. When transcoding is enabled, you can set parameters such as resolution, frame rate, bit rate, and whether to enable video streams with high and low resolutions.

To activate the Media Gateway, contact Agora support. When you activate Media Gateway, you specify your access area to optimize the transmission quality of the media stream.

The Media Gateway RESTful API supports the following interfaces:

API	Description
Create	Acquire a stream key. You use the stream key to Configure, Query and Delete the stream.
Configure	Set the video and audio transcoding configuration. By default, the video stream is pushed directly to the Agora channel without transcoding. If you need to transcode, use this interface to set the relevant parameters.
Query	Query information about stream keys, such as the bound UID, the bound channel name, and validity.
Delete	Destroy a stream key.

To use the Media Gateway RESTful API and obtain the relevant code, refer to the API reference. If you need to push multiple streams to the same channel, use a unique uid to generate each stream key.

The stream key generation method depends on whether you use the Agora domain name or a custom domain name. To use the Agora domain name, create a stream key using the Media Gateway RESTful API.

When using your own domain name for streaming, the stream key can be generated locally. Contact Agora technical support to bind your custom domain name. To generate a stream key locally, you use the following information:

• The App Id of the Agora project from Agora Console.
• The App certificates corresponding to your App Id.
• A channel name.
• The user Id of the anchor in the Agora channel.
• The effective duration (seconds) of the stream keys.

The following Node.js sample code demonstrates how to generate a stream key:

_35

const crypto = require('crypto');

_35

const msgpack = require('msgpack-lite');

_35

_35

appcert = "" // Your App certificate from Agora console

_35

channel = ""; // A Video SDK channel name

_35

uid = ""; // The uid of the anchor in the channel

_35

expiresAfter = 86400; // Valid duration of stream key (seconds)

_35

_35

const expiresAt = Math.floor(Date. now() / 1000) + expiresAfter;

_35

_35

const rtcInfo = {

_35

C: channel,

_35

U: uid,

_35

E: expiresAt,

_35

};

_35

_35

// Serialize using msgpack

_35

const data = msgpack.encode(rtcInfo);

_35

_35

// Randomly generate an initialization vector

_35

const iv = crypto.randomBytes(16);

_35

_35

// Use App certificate as encryption key

_35

const key = Buffer.from(appcert, 'hex');

_35

_35

// Create an AES-128 CTR encryptor

_35

const encrypter = crypto.createCipheriv('aes-128-ctr', key, iv);

_35

_35

// Encrypt the data

_35

const encrypted = Buffer.concat([iv, encrypter.update(data), encrypter.final()]);

_35

_35

// Base64 conversion

_35

const streamkey = encrypted.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/\=+$/, '');

_35

_35

console.log(`streamkey is ${streamkey}`);

This section shows you how to test Agora Media Gateway using OBS Studio, a free and open-source, cross-platform streaming app. Take the following steps to start streaming using OBS Studio:

1. Download and install OBS studio.

2. From the main screen, select Settings and switch to the Stream tab.

3. Fill in the following information:

   

   • Service: From the dropdown list, select Custom...

   • Server: Enter the scheme rtmp://, followed by the unified Agora domain name, or your own domain name. The unified Agora domain name is rtls-ingress-prod-<region>.agoramdn.com. Replace <region> with the code for your geographical region. You also need to append /live after the domain name.

     For example: rtmp://rtls-ingress-prod-na.agoramdn.com/live

     The supported regions and their codes are:

     • na: North America
     • eu: Europe
     • ap: Asia, except Mainland China
     • cn: Mainland China

     To use your own domain name, please contact Agora technical support for configuration.

   • Stream key: A valid stream key, acquired using the Media Gateway RESTful API or generated locally, that corresponds to your server domain name.

4. Set streaming options to avoid B-frames in source streams:

   To avoid compatibility issues with Agora viewer on the web when transcoding is not enabled, and the source stream contains B-frames, use one of the following methods in OBS studio:

   • Add a x264 encoding parameter

     In OBS Studio, go to Settings > Output > Encoder Settings, and set the x264 Options to bframes=0

     

   • Add a Tune parameter

     In OBS Studio, go to Settings > Output > Encoder Settings, and set the Tune parameter to zerolatency

     

   Save the configuration and return to the main screen.

5. Under Sources, press + to add a new source then select Media Source from the menu. Type in a name for your source and Browse to select a video file.

6. Generate a temporary token in Agora Console for the same channel name you used to generate the stream key but use a different uid.

7. In your browser, navigate to the Agora web demo and update App ID, Channel, and Token with the values for your temporary token, then click Join.

8. In OBS Studio, press Start Streaming to begin streaming to your Agora Channel.

   You see a video stream displayed in the channel, with the uid you used to generate the stream key.

9. Use the Configure, Query, and Delete Media Gateway RESTful API interfaces to manage your stream.

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

Refer to the Media Gateway RESTful API for parameter details and to obtain the calling code for your platform.

Media Gateway supports the following media streaming formats and protocols:

• Video codec: H.264, H.265
• Audio codec: AAC, OPUS
• Streaming protocol: RTMP, SRT
• Media format: FLV, MPEG-TS