Media Gateway quickstart

To push online media streams as live video source streams into Agora channels using Media Gateway, you need to obtain a server domain name and streaming key. Taking the OBS streaming software as an example, you configure the server's domain name and streaming key in the following way:

This page explains how to obtain the server domain name and generate a streaming key.

In order to follow this procedure you must:

• Have a project that implements an RTC product (Interactive Live Streaming, Broadcast Streaming, Video Calling, Voice Calling)
• Generate app ID, app certificate, customer ID, and customer secret
• Pass basic HTTP or HMAC authentication

You can use Agora’s unified domain name or your own one. The server appends the /live suffix to the domain name.

• The Agora's unified domain name is rtls-ingress-prod-<region>.agoramdn.com. Replace <region> with the code for your geographical region.

  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, contact technical support for configuration.

The stream key generation method depends on whether you use the Agora's domain name or a custom domain name.

• If you use Agora's domain name, create a stream key using the Media Gateway RESTful API.
• If you use your own domain name, you can either call the Media Gateway RESTful API or generate the key locally.

Create and publish the streaming key by calling the following endpoint:

PUT https://api.agora.io/:region/v1/projects/:appId/rtls/ingress/streamkeys

See API reference for details.

Info

To explore the RESTful API parameters, obtain sample code in various client languages, or test Media Gateway requests, refer to the Postman API reference.

Note

Before starting, make sure you have configured your domain name by contacting technical support.

To generate a stream key locally, you use the following information:

• The app ID of the Agora project from Agora Console.
• The app certificate corresponding to your app ID.
• channelName: The channel name.
• uid: The user ID of the host in the channel.
• expiresAfter: The effective duration of the stream key, in seconds.
• template (Optional): The associated flow configuration template. See API reference for details.

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

Note

The following example code relies on the msgpack-lite module. If you haven't installed it yet, execute npm install msgpack-lite and run node app.js in the project root directory .

_37

const crypto = require('crypto');

_37

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

_37

_37

appcert = "" // Your app certificate from Agora

_37

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

_37

uid = ""; // The UID of the host in the channel

_37

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

_37

_37

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

_37

_37

const rtcInfo = {

_37

C: channel,

_37

U: uid,

_37

E: expiresAt,

_37

// If you are not sure whether to use the flow configuration template, keep the following line commented

_37

// T: templateId,

_37

};

_37

_37

// Serialize using msgpack

_37

const data = msgpack.encode(rtcInfo);

_37

_37

// Randomly generate an initialization vector

_37

const iv = crypto.randomBytes(16);

_37

_37

// Use app certificate as encryption key

_37

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

_37

_37

// Create an AES-128 CTR encryptor

_37

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

_37

_37

// Encrypt the data

_37

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

_37

_37

// Base64 conversion

_37

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

_37

_37

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

In case of intercommunication with the web client, transcoding is not enabled by default. To ensure the best experience for web viewers, make sure that the streaming software uses the following encoding parameters:

• Key frame interval (GOP): 2s
• Video profile: baseline
• x264 options: threads=6
• Frame rate (FPS): At 1080 resolution, the frame rate must not exceed 30; for resolutions below that, the frame rate must not exceed 60 (if not necessary, 30 is sufficient).

Taking the OBS streaming software as an example, configure it as shown below:

1. On the Settings > Output > Live page, configure the video profile, keyframe interval, and x264 options.

   

2. On the Settings > Video page, configure common frame rates.

   

After completing the configuration, you can push RTMP or SRT protocol streams to Agora channels, and these streams will be published to the corresponding channels by the host.

By default, after the Media Gateway receives the pushed stream, it will not transcode it and will directly publish it to the Agora channel. If you want to transcode the streams, use the stream configuration template API to implement related functions.

Agora Go Backend Middleware is an open-source microservice that exposes a RESTful API designed to simplify Media Gateway interactions with Agora. Written in Golang and powered by the Gin framework, this community project serves as a middleware to bridge front-end applications using Agora's Video SDK or Voice SDK with Agora's RESTful APIs.