Broadcast Streaming events

The Agora Notification Callback Service (NCS) server sends the message notification callbacks of Broadcast Streaming as HTTPS POST requests to your server. The data format is JSON, the character encoding is UTF-8, and the signature algorithm is HMAC/SHA1 or HMAC/SHA256.

Request header

The header of the message notification callbacks contains the following fields:

Field name	Value
`Content-Type`	`application/json;charset=utf-8`
`Agora-Signature`	The signature value is generated by using the secret and the HMAC/SHA1 algorithm. You need to use the secret and HMAC/SHA1 algorithm to verify this signature value. For more details, see Signature Verification.
`Agora-Signature-V2`	The signature value is generated by using the secret and the HMAC/SHA256 algorithm. You need to use the secret and the HMAC/SHA256 algorithm to verify this signature value. For more details, see Signature Verification.

Request body

The request body of the message notification callbacks contains the following fields:

Field	Type	Description
`noticeId`	String	The notification ID, identifying the notification for each event sent from the Agora server.
`productId`	Integer	The service ID. A value of 7 indicates the Broadcast Streaming service.
`eventType`	Integer	The event type of the notification. For more details, see the Event Types of Broadcast Streaming.
`notifyMs`	Integer	The Unix timestamp (ms) of the event notification that the Agora NCS server sends to your server. This value is updated when Retry is notified.
`payload`	JSON Object	The content of the event notification. The `payload` varies with the `eventType`. For more details, see the Event Types of Broadcast Streaming.

An example of the request body of message notification callbacks:

{
    "noticeId": "2000001428:4330:107",
    "productId": 7,
    "eventType": 0,
    "notifyMs": 1611566412672,
    "payload": {...}
}

The event types of Broadcast Streaming

The Agora NCS can send notification of the following event types in the Broadcast Streaming service:

eventType	event_name	Description
1	`publish_start`	The stream pushing starts.
2	`publish_end`	The stream pushing ends.
11	`publish_media_info`	The media information on stream pushing is reported.
3	`new_custom_record_file`	The new custom record file is generated.
4	`new_custom_snapshot_file`	The new custom snapshot file is generated.
5	`new_custom_moderation_result`	The notification of new custom moderation results is sent.
101	`new_standard_record_file`	The new standard record file is generated.
102	`new_standard_snapshot_file`	The new standard snapshot file is generated.
103	`new_standard_moderation_result`	The notification of new standard moderation results is sent.

1 publish_start

eventType 1 indicates that the stream pushing starts, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name, that is, `publish_start`.
`domain`	String	The stream-pushing domain name.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`clientIp`	String	The client IP.
`nodeIp`	String	The node IP.

An example of the payload:

{
   "eventName": "publish_start",
   "domain": "test.agora.io",
   "entryPoint": "live",
   "streamName": "test_stream",
   "clientIp": "253.199.199.199",
   "nodeIp": "253.199.199.199"
}

2 publish_end

eventType 2 indicates that the stream pushing ends, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name, that is, `publish_end`.
`domain`	String	The stream-pushing domain name.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`clientIp`	String	The client IP.
`nodeIp`	String	The node IP.

An example of the payload:

{
   "eventName": "publish_end",
   "domain": "test.agora.io",
   "entryPoint": "live",
   "streamName": "test_stream",
   "clientIp": "253.199.199.199",
   "nodeIp": "253.199.199.199"
}

11 publish_media_info

eventType 11 indicates that the media information on stream pushing is reported, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name, that is, `publish_media_info`.
`domain`	String	The stream-pushing domain name.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`videoCodec`	String	The video codec.
`videoFps`	Integer	The video frame rate (fps).
`videoRate`	Integer	The video bitrate (bps).
`height`	Integer	The height of the video.
`width`	Integer	The width of the video.
`audioCodec`	String	The audio codec.

An example of the payload:

{
    "eventName": "publish_media_info",
    "domain": "test.agora.io",
    "entryPoint": "live",
    "streamName": "test_stream",
    "videoCodec": "H264",
    "videoFps": "29",
    "videoRate": "1216568",
    "height": "720",
    "width": "1080",
    "audioCodec": "AAC"
}

3 new_custom_record_file

eventType 3 indicates that the new custom record file is generated, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name, that is, `new_custom_record_file`.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`fileName`	String	The file name. The naming formats are as follows: MP4 file: `{entryPoint}/{streamName}/{sessionid}_{sessiondate}_{sliceid}_{filedate}.mp4`. M3U8 file: `{entryPoint}/{streamName}/{sessionid}_{sessiondate}.m3u8`. The variables represent the following information: `sessionid`: The recording ID, the unique identifier of the current recording. `sessiondate`: The time when the recording starts. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019. `sliceid`: The slice ID, starting from 0. Large mp4 files should be sliced. `filedate`: The time when the record file is created. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019.

An example of the payload:

{
   "eventName": "new_custom_record_file",
   "entryPoint": "live",
   "streamName": "test_stream",
   "fileName": "live/test_stream/536694d6ef4b06c137b0e8a0a3f225a7_20211122094718109_0_20211123051243120.mp4"
}

4 new_custom_snapshot_file

eventType 4 indicates that the new custom snapshot file is generated, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name, that is, `new_custom_snapshot_file`.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`fileName`	String	The file name of the new snapshot. The naming format is `{entryPoint}/{streamName}/{sessionid}_{sessiondate}_{filedate}.jpg`, and the variables represent the following information: `sessionid`: The recording ID, the unique identifier of the current recording. `sessiondate`: The time when the recording starts. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019. `filedate`: The time when the snapshot file is created. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, and second. For example, 20190611083246 represents 8:32:46, June 11, 2019.

An example of the payload:

{
   "eventName": "new_custom_snapshot_file",
   "entryPoint": "live",
   "streamName": "test_stream",
   "fileName": "live/test_stream/536694d6ef4b06c137b0e8a0a3f225a7_20211122094718109_20211123051243.jpg",
}

5 new_custom_moderation_result

eventType 5 indicates that the notification of new custom moderation results is sent, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name: that is, `new_custom_moderation_result`.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`fileName`	String	The file name of the new snapshot. The naming format is `{entryPoint}/{streamName}/{sessionid}_{sessiondate}_{filedate}.jpg`, and the variables represent the following information: `sessionid`: The recording ID, the unique identifier of the current recording. `sessiondate`: The time when the recording starts. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019. `filedate`: The time when the snapshot file is created. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, and second. For example, 20190611083246 represents 8:32:46, June 11, 2019.
`results`	JSON	The new moderation result contains the following fields: `porn`: JSON type. The new moderation result contains the following fields: `outputs`: JSON type. The possibility that the image is neutral, pornographic, or sexually suggestive. `Neutral`: Float type. The possibility that the image does not contain inappropriate content. This result means that there is no inappropriate content contained in the image, but there may be proper or moderate body nudity and body curves. `porn`: Float type. The possibility that the image is pornographic. This result means the image contains nudity that includes genitals, sexual behaviors, and cues, or puts excessive emphasis on sexual characteristics. `sexy`: Float type. The possibility that the image is sexually suggestive. This result means the image contains substantial nudity or the outline of the male or female sexual features, but no genital exposure. `scene`: String type, the content moderation result. This result is the RTC video intelligent moderation based on the three floating-point values in the `outputs`. `scene` returns the following information: `"neutral"`: The image does not contain inappropriate elements. `"porn"`: The image is pornographic. `"sexy"`: The image is sexually suggestive.
`suggestion`	String	Image processing description. `"Pass"`: The image does not contain inappropriate elements, therefore it is approved. `"block"`: The image is pornographic, therefore it is blocked. `"review"`: The image is judged to be sexually suggestive, therefore it is either approved or flagged for further review according to your particular scenario. According to your own scenario, you could consider such images to be neutral, requiring no action to be taken, or in need of human moderation. For example, for social applications with a higher tolerance for sexual suggestiveness, the images could be considered to be neutral; for education applications where this is not appropriate, the images likely need human moderation.

An example of the payload:

{
    "eventName": "new_custom_moderation_result",
    "entryPoint": "live",
    "streamName": "test_stream",
    "results": {
        "porn": {
            "outputs": {
                "sexy": 0.00188077823,
                "neutral": 0.915607393,
                "porn": 0.082511887
            },
            "scene": "neutral"
        }
    },
    "fileName": "live/test_stream/536694d6ef4b06c137b0e8a0a3f225a7_20211122094718109_20211123051243.jpg",
    "suggestion": "pass"
}

101 new_standard_record_file

eventType 101 indicates that the new standard record file is generated, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name, that is, `new_standard_record_file`.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`fileName`	String	The file name. The naming formats are as follows: MP4 file: `record/{entryPoint}/{streamName}/{sessionid}_{sessiondate}_{sliceid}_{filedate}.mp4`. M3U8 file: `record/{entryPoint}/{streamName}/{sessionid}_{sessiondate}.m3u8`. The variables represent the following information: `sessionid`: The recording ID, the unique identifier of the current recording. `sessiondate`: The time when the recording starts. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019. `sliceid`: The slice ID, starting from 0. Large mp4 files should be sliced. `filedate`: The time when the record file is created. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019.

An example of the payload:

{
   "eventName": "new_standard_record_file",
   "entryPoint": "live",
   "streamName": "test_stream",
   "fileName": "record/live/test_stream/536694d6ef4b06c137b0e8a0a3f225a7_20211122094718109_0_20211123051243120.mp4"
}

102 new_standard_snapshot_file

eventType 4 indicates that the new standard snapshot file is generated, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name, that is, `new_custom_snapshot_file`.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`fileName`	String	The file name of the new snapshot. The naming format is `snapshot/{entryPoint}/{streamName}/{sessionid}_{sessiondate}_{filedate}.jpg`, and the variables represent the following information: `sessionid`: The recording ID, the unique identifier of the current recording. `sessiondate`: The time when the recording starts. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019. `filedate`: The time when the snapshot file is created. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, and second. For example, 20190611083246 represents 8:32:46, June 11, 2019.

An example of the payload:

{
   "eventName": "new_custom_snapshot_file",
   "entryPoint": "live",
   "streamName": "test_stream",
   "fileName": "snapshot/live/test_stream/536694d6ef4b06c137b0e8a0a3f225a7_20211122094718109_20211123051243.jpg",
}

103 new_standard_moderation_result

eventType 103 indicates that the notification of new standard moderation results is sent, and the payload contains the following fields:

Field	Data type	Meaning
`eventName`	String	The event name: that is, `new_custom_moderation_result`.
`entryPoint`	String	The entry point name.
`streamName`	String	The stream name.
`fileName`	String	The file name of the new snapshot. The naming format is `snapshot/{entryPoint}/{streamName}/{sessionid}_{sessiondate}_{filedate}.jpg`, and the variables represent the following information: `sessionid`: The recording ID, the unique identifier of the current recording. `sessiondate`: The time when the recording starts. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, second, and millisecond. For example, 20190611073246073 represents 7:32:46.073, June 11, 2019. `filedate`: The time when the snapshot file is created. The time zone is UTC+0, and the variable value consists of year, month, day, hour, minute, and second. For example, 20190611083246 represents 8:32:46, June 11, 2019.
`results`	JSON	The new moderation result contains the following fields: `porn`: JSON type. The new moderation result contains the following fields: `outputs`: JSON type. The possibility that the image is neutral, pornographic, or sexually suggestive. `Neutral`: Float type. The possibility that the image does not contain inappropriate content. This result means that there is no inappropriate content contained in the image, but there may be proper or moderate body nudity and body curves. `porn`: Float type. The possibility that the image is pornographic. This result means the image contains nudity that includes genitals, sexual behaviors, and cues, or puts excessive emphasis on sexual characteristics. `sexy`: Float type. The possibility that the image is sexually suggestive. This result means the image contains substantial nudity or the outline of the male or female sexual features, but no genital exposure. `scene`: String type, the content moderation result. This result is the RTC video intelligent moderation based on the three floating-point values in the `outputs`. `scene` returns the following information: `"neutral"`: The image does not contain inappropriate elements. `"porn"`: The image is pornographic. `"sexy"`: The image is sexually suggestive.
`suggestion`	String	Image processing description. `"Pass"`: The image does not contain inappropriate elements, therefore it is approved. `"block"`: The image is pornographic, therefore it is blocked. `"review"`: The image is judged to be sexually suggestive, therefore it is either approved or flagged for further review according to your particular scenario. According to your own scenario, you could consider such images to be neutral, requiring no action to be taken, or in need of human moderation. For example, for social applications with a higher tolerance for sexual suggestiveness, the images could be considered to be neutral; for education applications where this is not appropriate, the images likely need human moderation.

An example of the payload:

{
    "eventName": "new_standard_moderation_result",
    "entryPoint": "live",
    "streamName": "test_stream",
    "results": {
        "porn": {
            "outputs": {
                "sexy": 0.00188077823,
                "neutral": 0.915607393,
                "porn": 0.082511887
            },
            "scene": "neutral"
        }
    },
    "fileName": "snapshot/live/test_stream/536694d6ef4b06c137b0e8a0a3f225a7_20211122094718109_20211123051243.jpg",
    "suggestion": "pass"
}