Help Center/ SparkRTC/ API Reference/ Examples/ Example 1: Creating a Single Stream Recording Job
Updated on 2023-04-06 GMT+08:00

Example 1: Creating a Single Stream Recording Job

Scenarios

If you need to record real-time audios and videos in a room, join the room and call the recording API to create a single stream recording job.

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

  1. 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

  2. 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",
      }

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

    1. Select the POST request method and enter the URI.
      https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-rules
    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:
      {
      	"obs_addr": {
      		"bucket": "obsName",
      		"location": "cn-north-4",
      		"object": "Record/",
      		"project_id": "01234567890123456789012345678901"
      	},
      	"record_formats": ["MP4"],
      	"mp4_config": {}
      }
    4. 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"
      }

  4. Call the API for configuring a SparkRTC recording event callback.

    1. Select the PUT request method and enter the URI.
      https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/record-callback
    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:
      {
      	"url": "http://mydomain.com/callback",
      	"auth_key": "8923ab8c2dcef4538923ab8c2dcef453"
      }
    4. 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"
      		]
      	}
      }

  5. An end user joins a SparkRTC room using the SparkRTC app. For details about the integration development of the SparkRTC app, see Client SDK.
  6. Call the API for starting a single 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}/individual-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:
      {
      	"room_id": "room001",
      	"user_id": "user001",
      	"is_record_audio": true,
      	"video_type": "CAMERASTREAM",
      	"resolution": "1280*720",
      	"resolution_policy": "DOWNWARD",
      	"max_idle_time": 30,
      	"record_param": {
      		"record_rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab"
      	}
      }
    4. If the request is successful, information about the recording job is returned.
      {
      	"app_id": "5ff9701f2346968bb306cb43",
      	"create_time": "2021-04-21T10:51:55Z",
      	"is_record_audio": true,
      	"job_id": "607f87cf00d861eeefffa6c88054cdab",
      	"job_unique_id": "a77bb33dbdc948d8",
      	"max_idle_time": 30,
      	"push_param": {
      		"rtmp_urls": null
      	},
      	"record_files": null,
      	"record_param": {
      		"record_rule_id": "5d0ec2c53a2c15625017adb8bbbcd9ab"
      	},
      	"resolution_policy": "DOWNWARD",
      	"resolution": "1280*720",
      	"room_id": "room001",
      	"start_time": "2021-04-21T10:51:55Z",
      	"state": "INIT",
      	"stop_time": "0001-01-01T00:00:00Z",
      	"stream_name": "s_607f87cf00d861eeefffa6c88054cdab_room001_user001",
      	"update_time": "2021-04-21T10:51:55Z",
      	"user_id": "user001",
      	"video_type": "CAMERASTREAM"
      }

  7. After the audio or video interaction is complete in the SparkRTC room, obtain the recording files from the configured OBS bucket.