Help Center/ SparkRTC/ API Reference/ Examples/ Example 2: Creating a Mixed Stream Recording Job

Updated on 2023-04-06 GMT+08:00

View PDF

Example 2: Creating a Mixed Stream Recording Job

Scenarios

Example 1: Creating a Single Stream Recording Job describes how to record audio and video streams of each user in a room and save them into independent files. This section describes how to record multiple streams of users in a room and save them into one file by calling the SparkRTC APIs.

Prerequisites

You have obtained the SparkRTC endpoint rtc-api.myhuaweicloud.com.
You have created an OBS bucket for storing recording files and authorized SparkRTC to access the OBS bucket.

Procedure

Obtain a user token for authenticating the calling of SparkRTC APIs.

Obtain username, password, and domainname in My Credentials and call the following API to obtain the token. For details, see Making an API Request.

POST https://iam.myhuaweicloud.com/v3/auth/tokens
Content-Type: application/json
{
  "auth": {
    "identity": {
      "methods": [
        "password"
      ],
      "password": {
        "user": {
          "name": "username", //Username
          "password": "password", //Login password
          "domain": {
            "name": "domainname" //Name of the account to which the user belongs
          }
        }
      }
    },
    "scope": {
      "domain": {
         "name": "domainname"  //Name of the account to which the user belongs
      }
    }
  }
}

Information in the red box in Figure 1 indicates the obtained user token.

Figure 1 Obtaining a user token
Click to enlarge

Call the API for creating a SparkRTC application.
1. Select the POST request method and enter the URI.
```
https://rtc-api.myhuaweicloud.com/v2/apps
```
2. In the request header, add X-Auth-Token and set its value to the token obtained in 1.
3. Specify the following parameter in the request body:
```
{
  "app_name" : "rtctest"
}
```
4. If the request is successful, the ID of the created application is returned.
```
{
	"app_id": "5ff9701f2346968bb306cb43",
}
```

Call the API for creating or updating a recording template to create a recording template.

Select the POST request method and enter the URI.

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-rules

In the request header, add X-Auth-Token and set its value to the token obtained in 1.

Specify the following parameters in the request body:

{
	"obs_addr": {
		"bucket": "obsName",
		"location": "cn-north-4",
		"object": "Record/",
		"project_id": "01234567890123456789012345678901"
	},
	"record_formats": ["MP4"],
	"mp4_config": {}
}

If the request is successful, the created recording template is returned.

{
	"app_id": "5ff9701f2346968bb306cb43",
	"rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab",
	"create_time": "2021-04-21T10:29:33Z",
	"hls_config": {
		"record_cycle": 0,
		"record_max_duration_to_merge_file": 0
	},
	"mp4_config": {
		"record_cycle": 7200,
		"record_max_duration_to_merge_file": 0,
		"record_prefix": "Record/{publish_domain}/{app}/{record_type}/{record_format}/{stream}_{file_start_time}/{stream}_{file_start_time}"
	},
	"obs_addr": {
		"bucket": "obsName",
		"location": "cn-north-4",
		"object": "Record/",
		"project_id": "01234567890123456789012345678901"
	},
	"record_formats": [
		"MP4"
	],
	"update_time": "2021-04-21T10:29:33Z"
}

Call the API for configuring a SparkRTC recording event callback.

Select the PUT request method and enter the URI.

https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-callback

In the request header, add X-Auth-Token and set its value to the token obtained in 1.

Specify the following parameters in the request body:

{
	"url": "http://mydomain.com/callback",
	"auth_key": "8923ab8c2dcef4538923ab8c2dcef453"
}

If the request is successful, information about the created callback is returned.

{
	"app_id": "5ff9701f2346968bb306cb43",
	"record_callback": {
		"auth_key": "8923ab8c2dcef4538923ab8c2dcef453",
		"update_time": "2021-04-07T12:05:18.0718Z",
		"url": "http://mydomain.com/callback",
		"notify_event_subscription": [
			"RECORD_NEW_FILE_START",
			"RECORD_FILE_COMPLETE",
			"CLOUD_RECORD_OVER"
		]
	}
}

An end user joins a SparkRTC room using the SparkRTC app. For details about the integration development of the SparkRTC app, see Client SDK.
Call the API for starting a mixed stream recording job to create a recording job.
1. Select the POST request method and enter the URI.
```
https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs
```
2. In the request header, add X-Auth-Token and set its value to the token obtained in 1.
3. Specify the following parameters in the request body:
```
{
	"mix_param": {
		"room_id": "room001",
		"encode_template": "1920x1080_30_4620",
		"max_idle_time": 30,
		"layout_template": "nine_grids_view" //If the video layout is in screen sharing mode, set this parameter to screen_share_left or screen_share_right.
	},
	"record_param": {
		"record_rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab"
	}
}
```
  layout_template: video layout template.
  - nine_grids_view: adaptive gallery view template.
    Images of each user are tiled and have the same size. The size and position of each image are dynamically adjusted based on the number of users. A maximum of 25 images are supported. The following figure shows the layouts with different numbers of users.
    - If the aspect ratio of the actual video stream is different from that of the screen, a video image will be cropped to adapt to the screen size.
    - If a user exits the room, the image of this user will be replaced by the next user who enters the room.
    - If there are not enough users in the room, the rest of the screen displays a background color.
    - A user who only sends audio still occupies a screen.
    - A background image is supported. If there are not enough users in the room, the rest of the screen displays a background image.
  - screen_share_left and screen_share_right: adaptive screen sharing templates with the main screen on the left or right.
    A shared screen or a presenter view is displayed in the main screen on the right or left. Other users are arranged vertically on the side of the main screen. A maximum of 17 screens are supported. The following figures show the layouts with different numbers of users.
    - The main screen displays a presenter view or a shared screen.
    - The main screen displays the video of a specific user. If no user is specified or the specified user does not enter the room, the main screen displays the background color.
    - Images in the main screen on the left are zoomed in or out to display the complete content. Images in the small screens on the right are cropped to adapt to the screen size.
    - The small screens of users on the right are sorted by the time when they enter the room.
    - If a user in the right small screen exits the room, the image of this user will be replaced by the next user who enters the room.
    - If there are not enough users in the room, the rest of the screen displays a background color.
    - A user who only sends audio still occupies a screen.
    - A background image is supported. If there are not enough users in the room, the rest of the screen displays a background image.
4. If the request is successful, information about the mixed stream recording job is returned.
```
{
	"app_id": "5ff9701f2346968bb306cb43",
	"create_time": "2021-04-21T11:47:32Z",
	"job_id": "607f9fc100d861eeefff9b300b388dab",
	"job_unique_id": "87b1f2b8da9c44cd",
	"mix_param": {
		"room_id": "room001",
		"layout_template": "nine_grids_view",
		"encode_template": "1920x1080_30_4620",
		"max_idle_time": 30
	},
	"push_param": {
		"rtmp_urls": null
	},
	"record_param": {
		"record_rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab"
	},
	"room_id": "room001",
	"start_time": "2021-04-21T11:47:32Z",
	"state": "INIT",
	"stop_time": "0001-01-01T00:00:00Z",
	"stream_name": "m_607f9fc100d861eeefff9b300b388dab_room001",
	"update_time": "2021-04-21T11:47:32Z"
}
```
After the audio or video interaction is complete in the SparkRTC room, obtain the recording files from the configured OBS bucket.