Skip to main content

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 nameValue
Content-Typeapplication/json;charset=utf-8
Agora-SignatureThe 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-V2The 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:

FieldTypeDescription
noticeIdStringThe notification ID, identifying the notification for each event sent from the Agora server.
productIdIntegerThe service ID. A value of 7 indicates the Broadcast Streaming service.
eventTypeIntegerThe event type of the notification. For more details, see the Event Types of Broadcast Streaming.
notifyMsIntegerThe Unix timestamp (ms) of the event notification that the Agora NCS server sends to your server. This value is updated when Retry is notified.
payloadJSON ObjectThe 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:


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

The event types of Broadcast Streaming

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

eventTypeevent_nameDescription
1publish_startThe stream pushing starts.
2publish_endThe stream pushing ends.
11publish_media_infoThe media information on stream pushing is reported.
3new_custom_record_fileThe new custom record file is generated.
4new_custom_snapshot_fileThe new custom snapshot file is generated.
5new_custom_moderation_resultThe notification of new custom moderation results is sent.
101new_standard_record_fileThe new standard record file is generated.
102new_standard_snapshot_fileThe new standard snapshot file is generated.
103new_standard_moderation_resultThe 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:

FieldData typeMeaning
eventNameStringThe event name, that is, publish_start.
domainStringThe stream-pushing domain name.
entryPointStringThe entry point name.
streamNameStringThe stream name.
clientIpStringThe client IP.
nodeIpStringThe node IP.

An example of the payload:


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

2 publish_end

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

FieldData typeMeaning
eventNameStringThe event name, that is, publish_end.
domainStringThe stream-pushing domain name.
entryPointStringThe entry point name.
streamNameStringThe stream name.
clientIpStringThe client IP.
nodeIpStringThe node IP.

An example of the payload:


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

11 publish_media_info

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

FieldData typeMeaning
eventNameStringThe event name, that is, publish_media_info.
domainStringThe stream-pushing domain name.
entryPointStringThe entry point name.
streamNameStringThe stream name.
videoCodecStringThe video codec.
videoFpsIntegerThe video frame rate (fps).
videoRateIntegerThe video bitrate (bps).
heightIntegerThe height of the video.
widthIntegerThe width of the video.
audioCodecStringThe audio codec.

An example of the payload:


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

3 new_custom_record_file

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

FieldData typeMeaning
eventNameStringThe event name, that is, new_custom_record_file.
entryPointStringThe entry point name.
streamNameStringThe stream name.
fileNameStringThe 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:


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

    4 new_custom_snapshot_file

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

    FieldData typeMeaning
    eventNameStringThe event name, that is, new_custom_snapshot_file.
    entryPointStringThe entry point name.
    streamNameStringThe stream name.
    fileNameStringThe 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:


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

    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:

    FieldData typeMeaning
    eventNameStringThe event name: that is, new_custom_moderation_result.
    entryPointStringThe entry point name.
    streamNameStringThe stream name.
    fileNameStringThe 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.
  • resultsJSONThe 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 Video SDK 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.
    suggestionStringImage 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:


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

    101 new_standard_record_file

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

    FieldData typeMeaning
    eventNameStringThe event name, that is, new_standard_record_file.
    entryPointStringThe entry point name.
    streamNameStringThe stream name.
    fileNameStringThe 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:


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

    102 new_standard_snapshot_file

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

    FieldData typeMeaning
    eventNameStringThe event name, that is, new_custom_snapshot_file.
    entryPointStringThe entry point name.
    streamNameStringThe stream name.
    fileNameStringThe 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:


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

    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:

    FieldData typeMeaning
    eventNameStringThe event name: that is, new_custom_moderation_result.
    entryPointStringThe entry point name.
    streamNameStringThe stream name.
    fileNameStringThe 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.
  • resultsJSONThe 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 Video SDK 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.
    suggestionStringImage 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:


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

    Page Content