Quickstart using middleware

To streamline the use of Agora RESTful APIs within your infrastructure, Agora’s developer community offers the open-source Agora Go Backend Middleware. This backend provides RESTful APIs for tasks such as token generation, cloud recording management, and real-time transcription. It simplifies the integration of Agora’s cloud services into your real-time voice and video applications. This guide shows you how to implement cloud recording using the community middleware.

Understand the tech

The following figure illustrates the cloud recording workflow you implement by integrating the middleware micro service.

Set up and run the Go backend middleware

Take the following steps to set up and run the middleware project:

Clone the repository

_1git clone https://github.com/AgoraIO-Community/agora-go-backend-middleware.git
Install dependencies
Ensure you have Go installed on your system. Navigate to the project directory and install the project dependencies:

_2cd agora-go-backend-middleware _2go mod download
Configure environment variables

Copy the example .env file and update it with your Agora App ID, App Certificate, and cloud storage parameters:

_1cp .env.example .env

Update the following variables in the .env file:
- APP_ID: Your Agora App ID.
- APP_CERTIFICATE: Your Agora App Certificate.
- CUSTOMER_ID: Your customer ID
- CUSTOMER_SECRET: Your Customer Secret
- STORAGE_VENDOR: Cloud storage vendor (e.g., AWS, GCP).
- STORAGE_REGION: Region of your cloud storage.
- STORAGE_BUCKET: Bucket name.
- STORAGE_ACCESS_KEY: Cloud storage access key.
- STORAGE_SECRET_KEY: Cloud storage secret key.
Run the middleware:
Start the middleware using the following command:

_1go run cmd/main.go

The middleware runs on the default port, for example localhost:8080.

Implement Cloud Recording using middleware

This section explains the RESTful API calls to the backend middleware for starting, managing, and stopping a Cloud Recording session.

Start recording

To start a Cloud Recording session refer to the following examples:

info

The command-line examples in this guide are for demonstration purposes only. Do not use them directly in a production environment. Implement RESTful API requests through your application server.

Basic example

_8curl -X POST http://localhost:8080/cloud_recording/start \ _8 -H "Content-Type: application/json" \ _8 -d '{ _8 "channelName": "test_channel", _8 "sceneMode": "realtime", _8 "recordingMode": "mix", _8 "excludeResourceIds": [] _8 }'
Advanced example

_41curl -X POST http://localhost:8080/cloud_recording/start \ _41 -H "Content-Type: application/json" \ _41 -d '{ _41 "channelName": "testChannel", _41 "sceneMode": "realtime", _41 "recordingMode": "mix", _41 "excludeResourceIds": [], _41 "recordingConfig": { _41 "channelType": 0, _41 "decryptionMode": 1, _41 "secret": "your_secret", _41 "salt": "your_salt", _41 "maxIdleTime": 120, _41 "streamTypes": 2, _41 "videoStreamType": 0, _41 "subscribeAudioUids": ["#allstream#"], _41 "unsubscribeAudioUids": [], _41 "subscribeVideoUids": ["#allstream#"], _41 "unsubscribeVideoUids": [], _41 "subscribeUidGroup": 0, _41 "streamMode": "individual", _41 "audioProfile": 1, _41 "transcodingConfig": { _41 "width": 640, _41 "height": 360, _41 "fps": 15, _41 "bitrate": 500, _41 "maxResolutionUid": "1", _41 "layoutConfig": [ _41 { _41 "x_axis": 0, _41 "y_axis": 0, _41 "width": 640, _41 "height": 360, _41 "alpha": 1, _41 "render_mode": 1 _41 } _41 ] _41 } _41 } _41}'

Stop recording

To stop an ongoing cloud recording session:

curl -X POST http://localhost:8080/cloud_recording/stop \
  -H "Content-Type: application/json" \
  -d '{
    "cname": "test_channel",
    "uid": "uid-from-start-response",
    "resourceId": "resource-id-from-start-response",
    "sid": "sid-from-start-response",
    "recordingMode": "mix",
    "async_stop": false
  }'

Get Recording Status

During the recording, call the status endpoint to query the recording status as required.

curl -X GET "http://localhost:8080/cloud_recording/status?resourceId=your-resource-id&sid=your-sid&mode=mix"

Update Subscriber List

To update the subscriber list during a recording session, refer to the following example:

curl -X POST http://localhost:8080/cloud_recording/update/subscriber-list \
  -H "Content-Type: application/json" \
  -d '{
    "cname": "test_channel",
    "uid": "uid-from-start-response",
    "resourceId": "your-resource-id",
    "sid": "your-sid",
    "recordingMode": "mix",
    "recordingConfig": {
      "streamSubscribe": {
        "audioUidList": {
          "subscribeAudioUids": ["2345", "3456"]
        },
        "videoUidList": {
          "subscribeVideoUids": ["2345", "3456"]
        }
      }
    }
  }'

Update Layout

To update the layout of a recording session, refer to the following example:

curl -X POST http://localhost:8080/cloud_recording/update/layout \
  -H "Content-Type: application/json" \
  -d '{
    "cname": "test_channel",
    "uid": "uid-from-start-response",
    "resourceId": "your-resource-id",
    "sid": "your-sid",
    "recordingMode": "mix",
    "recordingConfig": {
      "mixedVideoLayout": 1,
      "backgroundColor": "#000000",
      "layoutConfig": [
        {
          "uid": "2345",
          "x_axis": 0,
          "y_axis": 0,
          "width": 360,
          "height": 640,
          "alpha": 1,
          "render_mode": 1
        }
      ]
    }
  }'

{
  "channelName": "string",
  "uid": "string",
  "recordingConfig": {
    // RecordingConfig fields
  },
  "storageConfig": {
    // StorageConfig fields
  }
}

Response

{
  "resourceId": "string",
  "sid": "string",
  "timestamp": "string"
}

{
  "cname": "string",
  "uid": "string",
  "resourceId": "string",
  "sid": "string",
  "recordingMode": "string",
  "async_stop": boolean
}

Response

{
  "resourceId": "string",
  "sid": "string",
  "serverResponse": {
    "fileListMode": "string",
    "fileList": [
      {
        "fileName": "string",
        "trackType": "string",
        "uid": "string",
        "mixedAllUser": boolean,
        "isPlayable": boolean,
        "sliceStartTime": number
      }
    ]
  },
  "timestamp": "string"
}

resourceId: string
sid: string
mode: string

Response

{
  "resourceId": "string",
  "sid": "string",
  "serverResponse": {
    "fileListMode": "string",
    "fileList": [
      {
        "fileName": "string",
        "trackType": "string",
        "uid": "string",
        "mixedAllUser": boolean,
        "isPlayable": boolean,
        "sliceStartTime": number
      }
    ]
  },
  "timestamp": "string"
}

{
  "cname": "string",
  "uid": "string",
  "resourceId": "string",
  "sid": "string",
  "recordingMode": "string",
  "recordingConfig": {
    // UpdateSubscriptionClientRequest fields
  }
}

Response

{
  "cname": "string",
  "uid": "string",
  "resourceId": "string",
  "sid": "string",
  "timestamp": "string"
}

{
  "cname": "string",
  "uid": "string",
  "resourceId": "string",
  "sid": "string",
  "recordingMode": "string",
  "recordingConfig": {
    // UpdateLayoutClientRequest fields
  }
}

Response

{
  "cname": "string",
  "uid": "string",
  "resourceId": "string",
  "sid": "string",
  "timestamp": "string"
}

Replace localhost:8080 with your server's address, if it is different.

Quickstart using middleware

Understand the tech

Set up and run the Go backend middleware

Implement Cloud Recording using middleware

Start recording

Stop recording

Get Recording Status

Update Subscriber List

Update Layout

Cloud Recording Middleware API Reference

Start Recording

Endpoint

Request Body

Response

Stop Recording

Endpoint

Request Body

Response

Get Recording Status

Endpoint

Query Parameters

Response

Update Subscriber List

Endpoint

Request Body

Response

Update Layout

Endpoint

Request Body

Response