From fdad390bc4962c80c66c228e796e15d902a7fd76 Mon Sep 17 00:00:00 2001 From: kelzr Date: Fri, 21 Apr 2023 14:37:11 +0800 Subject: [PATCH] [CT] sync --- markdown/cloud-transcoder/API Ref | 639 -------------------- markdown/cloud-transcoder/api.md | 807 ++++++++++++++++++++++++++ markdown/cloud-transcoder/overview.md | 32 + markdown/cloud-transcoder/webhook.md | 270 +++++++++ 4 files changed, 1109 insertions(+), 639 deletions(-) delete mode 100644 markdown/cloud-transcoder/API Ref create mode 100644 markdown/cloud-transcoder/api.md create mode 100644 markdown/cloud-transcoder/overview.md create mode 100644 markdown/cloud-transcoder/webhook.md diff --git a/markdown/cloud-transcoder/API Ref b/markdown/cloud-transcoder/API Ref deleted file mode 100644 index 77c8f211991..00000000000 --- a/markdown/cloud-transcoder/API Ref +++ /dev/null @@ -1,639 +0,0 @@ -Agora provides cloud transcoding service for single or multi-hosted interactive streaming scenarios and supports transcoding and stream mixing on the Agora server to push the streams of multiple hosts to the Agora RTC channel. Audience users in the RTC channel only need to subscribe to the transcoded and mixed streams to watch the live broadcast. - -When you use the cloud transcoding service, audience users do not need to subscribe to the streams of multiple hosts. This can significantly reduce downstream bandwidth use and help improve performance on user devices. - -This page describes how to implement cloud transcoding through RESTful API. - -## Prerequisites - -- Agora RESTful API requires Basic HTTP authentication. Make sure to complete [HTTP Basic Authentication](https://docs.agora.io/en/video-calling/reference/restful-authentication). -- Cloud transcoding is a sub-service of cloud recording. Make sure that the cloud recording service is enabled. See [Project setup](https://docs.agora.io/en/cloud-recording/get-started/getstarted#project-setup). - -## Understand the tech - -The process of transcoding and mixing multiple streams on the Agora server is equivalent to creating a cloud transcoder. The multiple streams before transcoding are the input of the cloud transcoder, and the stream after transcoding is the output. - -You can control the cloud transcoder through the cloud transcoding RESTful API: - -- `Acquire`: Before starting cloud transcoding, you must obtain a cloud transcoding resource for cloud transcoding tasks. -- `Create`: Create a cloud transcoder. The Agora server starts transcoding and mixing the multiple streams you specify into a single stream and pushes it to the Agora RTC channel. -- `Delete`: Destroy the cloud transcoder. The Agora server stops transcoding and mixing streams. -- `Query`: Query the information of the cloud transcoder. The Agora server queries the cloud transcoder you specify. - -## Acquire: Obtain a cloud transcoding resource - -Before starting a cloud transcoding task, you must call the `Acquire` method to obtain a cloud transcoding resource. - -After calling this method successfully, you can get a builderToken in the response body. The validity period of the builderToken is 5 minutes, and you need to use the builderToken to start cloud transcoding within 5 minutes. A builderToken can only be used for one cloud transcoding task. - -### HTTP request - -```http -POST https://api.agora.io/v1/projects//rtsc/cloud-transcoder/builderTokens -``` - -`appId`: (Required) String type parameter. The App ID provided by Agora for each developer. You can get an App ID after creating a project in Agora Console. The App ID identifies each project. - -#### Request header - -- `Content-Type`: `application/json` -- `Authorization`: The value of this field should refer to the `authentication `[instructions ](https://docs.agora.io/en/faq/restful_authentication) - -#### Request body - -The following parameters need to be passed in the request body: - -| Field | Type | Description | -| :----------- | :----------- | :----------------------------------------------------------- | -| `instanceId` | (Required)String | User-specified instance ID. The length must be a maximum of 64 characters. The supported character set range is as follows:
  • All lowercase English letters (a-z)
  • All uppercase English letters (A-Z)
  • Numbers 0-9
  • "-", "_"
    You can use one `instanceId` to generate multiple builderTokens, but only one builderToken can be used to initiate a request in a task. | - -The request body example: - -```json -{ - "instanceId" : "abc13328" -} -``` - -### HTTP response - -#### Response header - -`X-Request-ID`: UUID (Universal Unique Identifier), which identifies this request. -
    • If there is an error in the request, print out the value in the log to troubleshoot the problem.
    • If the response status code of this request is not 2XX, this field might not appear in the response header.
    - -#### Response body - -The response body contains the following fields: - -| Field | Type | Description | -| :----------- | :----- | :---------------------------------------------------- | -| `tokenName` | String | The value of builderToken, which needs to be passed in when calling other methods later. | -| `createTs` | Number | The Unix timestamp in seconds when the builderToken was generated. | -| `instanceId` | Number | The `instanceId` set in request body. | - -Response body example: - -```json -{ - "createTs": 1661324606, - "instanceId": "abc13328", - "tokenName": "nUwUbQf9Zg6tsgtLslGnDg0lk8RYaUE0***" -} -``` - -## Create: Start the task for creating a cloud transcoder - -### HTTP request - -``` -POST https://api.agora.io/v1/projects//rtsc/cloud-transcoder/tasks?builderToken= -``` - -#### Path parameter - -`appId`: (Required) String type parameter. The App ID provided by Agora for each developer. You can get an App ID after creating a project in Agora Console. The App ID identifies each project. - -#### Query parameter - -`builderToken`: (Required)String. Obtain the value of the builderToken through the `Acquire` method.`` - -#### Request header - -- `Content-Type`: `application/json` -- `Authorization`: The value of this field should refer to the `authentication `[instructions ](https://docs.agora.io/en/faq/restful_authentication) - -#### Request body - -The request body is the `services` field of JSON Object type. The field structure is shown in the following figure: - -![](https://web-cdn.agora.io/docs-files/1664351637544) - -- `services` contains the following fields: - - | Field | Type | Description | - | :---------------------------------- | :---------------- | :----------------------------------------------------------- | - | cloudTranscoder | (Required)JSON Object | Service name, set by the developer. The service name used in a cloud transcoder must be unique. | - | cloudTranscoder.serviceType | (Required)String | Service type. Cloud transcoding: `cloudTranscoderV2`. | - | cloudTranscoder.config | (Required)JSON Object | The cloud transcoding parameter settings. Used to set the business parameters of the cloud transcoder. | - | cloudTranscoder.config.transcoder | (Required)String | An object of the cloud transcoder. | - -- **`transcoder`** contains the following fields: - - | Field | Type | Description | - | :--------------------------------- | :---------------- | :----------------------------------------------------------- | - | idleTimeOut | (Optional)Number | The maximum amount of time (seconds) that the cloud transcoder is idle. Idle means that all hosts corresponding to the audio and video streams processed by the cloud transcoder have left the channel. After the idle state exceeds the set `idleTimeOut`, the cloud transcoder is destroyed automatically. The value range is [1,86400], and the default value is 300. | - | audioInputs[] | (Optional)JSON Object | The audio input source configuration for cloud transcoder.
  • If you do not pass a value, Agora use the input source corresponding to `videoInputs[].rtc.rtcUid` as the audio input source of the cloud transcoder. This method is suitable for scenarios where both the audio and video of the host are transcoded.
  • If you pass a value, Agora transcode and mixes the audio input source you specify. This value method is suitable for scenarios where the `audioInputs[].rtc.rtcUid` and `videoInputs[].rtc.rtcUid` are not exactly the same, that is, the video of some hosts is transcoded but the audio is not transcoded. | - | audioInputs[].rtc | (Required)JSON Array | The RTC audio input source for cloud transcoder. Multiple RTC input sources are supported. | - | audioInputs[].rtc.rtcChannel | (Required)String | The name of the RTC channel to which the input source belongs. Currently Agora only supports subscribing to the audio and video sources of a single channel. The audio and video sources must belong to the same channel. | - | audioInputs[].rtc.rtcUid | (Required)Number | The UID corresponding to the input source. The same UID is not allowed within an RTC channel. | - | audioInputs[].rtc.rtcToken | (Required)String | The token required to enter the RTC channel is used to ensure the security of the channel. See [Secure authentication with tokens](https://docs.agora.io/en/interactive-live-streaming/develop/authentication-workflow).| - | videoInputs[] | (Required)JSON Array | The video input configuration for cloud transcoder. | - | videoInputs[].rtc | (Required)JSON Array | The RTC video input source for the cloud transcoder. Multiple RTC input sources are supported. | - | videoInputs[].rtc.rtcChannel | (Required)String | The name of the RTC channel to which the video input source belongs. Currently Agora only supports subscribing to audio and video sources of a single channel. The audio and video sources must belong to the same channel. | - | videoInputs[].rtc.rtcUid | (Required)Number | The UID corresponding to the video input source. | - | videoInputs[].region | (Required)JSON Object | The position of the video input source picture on the canvas. | - | videoInputs[].region.x | (Required)Number | The x coordinate (pixels) of the video on the canvas. The horizontal position of the canvas relative to the origin, where the upper left corner of the canvas is the origin, and the x-coordinate is the upper left corner of the canvas. The value range is [0,3840]. | - | videoInputs[].region.y | (Required)Number | The y coordinate (pixels) of the video on the canvas. The vertical position of the canvas relative to the origin, where the upper left corner of the canvas is the origin, and the y-coordinate is the upper left corner of the canvas. The value range is [0,3840]. | - | videoInputs[].region.width | (Required)Number | The width (pixels) of the video. The value range is [120,3840]. | - | videoInputs[].region.height | (Required)Number | The height (pixels) of the video. The value range is [120,3840]. | - | videoInputs[].region.zOrder | (Required)Number | The layer number of the video. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer. | - | videoInputs [].placeholderImageUrl | (Required)String | The URL of the placeholder image when the user is offline. This url must be a valid URL with a `jpg` or `png` suffix. | - | canvas | (Required)JSON Object | The canvas that hosts the cloud transcoder video mixing. | - | canvas.height | (Required)Number | The height (pixel) of the canvas. The value range is [120,3840]. | - | canvas.width | (Required)Number | The width (pixel) of the canvas. The value range is [120,3840]. | - | canvas.color | (Required)String | The background color of the canvas. RGB color value, expressed as a decimal number. For example, 0 is black, 255 is blue. The value range is [0,16777215]. | - | canvas.backgroundImage | (Optional)String | The background color of the canvas. This URL must be valid with a `jpg` or `png` suffix. | - | canvas.fillMode | (Optional)String | The fill mode of the canvas background image.
  • (Default) `FILL`: Scales the screen while maintaining the aspect ratio and cropping in the center.
    ![img](https://web-cdn.agora.io/docs-files/1628837665989)
  • `FIT`:In order to maintain the aspect ratio, zoom the screen to fully display the image.
    ![img](https://web-cdn.agora.io/docs-files/1628837708782) | - | waterMarks [] | (Optional)JSON Array | Watermark input configuration for cloud transcoder. | - | waterMarks [].imageUrl | (Required)String | The URL of the image. This URL must be valid with a `jpg` or `png` suffix. | - | waterMarks [].fillMode | (Optional)String | The adaptation mode of the watermark.
  • (Default) `FILL`: Scales the screen while maintaining the aspect ratio, and cropping in the center.
    ![ img](https://web-cdn.agora.io/docs-files/1628837665989)
  • `FIT`: In order to maintain the aspect ratio, zoom the screen to fully display the image.
    ![img](https://web-cdn.agora.io/docs-files/1628837708782) | - | waterMarks [].region | (Required)JSON Object | The position of the watermark on the canvas. | - | waterMarks [].region.x | (Required)Number | The x coordinate (pixels) of the watermark on the canvas. The horizontal position relative to the origin, where the upper left corner of the canvas is the origin, and the x-coordinate is the upper left corner of the canvas. The value range is [0,3840]. | - | waterMarks [].region.y | (Required)Number | The y coordinate (pixels) of the watermark on the canvas. The vertical position of the canvas relative to the origin, where the upper left corner of the canvas is the origin, and the y-coordinate is the upper left corner of the canvas. The value range is [0,3840]. | - | waterMarks [].region.width | (Required)Number | The width (pixels) of the watermark. The value range is [120,3840]. | - | waterMarks [].region.height | (Required)Number | The height (pixels) of the watermark. The value range is [120,3840]. | - | waterMarks.region.zOrder[] | (Required)Number | The layer number of the watermark image. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer. | - | outputs.rtc | (Required)JSON Object | The output configuration for cloud transcoder. | - | outputs.rtc.rtcChannel | (Required)String | The name of the RTC channel to which the output video belongs. | - | outputs.rtc.rtcToken | (Required)String | The token required to enter the RTC channel is used to ensure the security of the channel. | - | outputs.rtc.rtcUid | (Required)Number | The user ID. | - | outputs.audioOption | (Optional)JSON Object | The transcoding configuration for the mixed audio stream. If you do not pass a value, the audio property of Agora transcoding output is `AUDIO_PROFILE_DEFAULT`, which is a 48 kHz sampling rate, music encoding, mono, and a maximum encoding bitrate of 64 Kbps. | - | outputs.audioOption.profileType | (Optional)String | Audio profiles. The values supported are as follows:
  • `AUDIO_PROFILE_DEFAULT`: (Default) A sample rate of 48 kHz, music encoding, mono, and a maximum encoding bitrate of 64 Kbps.
  • `AUDIO_PROFILE_SPEECH_STANDARD`: A sample rate of 32 kHz, audio encoding, mono, and a bitrate of up to 18 Kbps.
  • `AUDIO_PROFILE_MUSIC_STANDARD`: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 64 Kbps.
  • `AUDIO_PROFILE_MUSIC_STANDARD_STEREO`: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 80 Kbps.
  • `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`: A sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 96 Kbps.
  • `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`: A sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 128 Kbps. | - | outputs.videoOption | (Required)JSON Object | Transcoding configuration for mixed video stream. | - | outputs.videoOption.fps | (Optional)Number | The frame rate (fps) of the output video. The value range is [1,30]. The default value is 15. | - | outputs.videoOption.codec | (Required)String | The codec for the output video. The supported value is `"H264"`. | - | outputs.videoOption.bitrate | (Optional)Number | The bitrate of the output video. The value range is [1,10000]. If you don't pass a value, Agora automatically sets the video bitrate based on network conditions and other video properties. | - | outputs.videoOption.width | (Required)Number | The width (pixels) of the video. The value range is [120,3840]. | - | outputs.videoOption.height | (Required)Number | The height (pixels) of the output video. The value range is [120,3840]. | - -#### Request body example - -**Seneario 1: Audio and video trascoding with canvas and watermark** - -This example is transcoding and mixing the audio and video streams of two hosts with the user IDs `"123"` and `"456"` and publishing them into the channel "test". - -```json -{ - "services":{ - "cloudTranscoder":{ - "serviceType":"cloudTranscoderV2", - "config":{ - "transcoder":{ - "idleTimeout":300, - "audioInputs":[ - { - "rtc":{ - "rtcChannel":"test01", - "rtcUid": 123, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - } - }, - { - "rtc":{ - "rtcChannel":"test01", - "rtcUid": 456, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - } - } - ], - "canvas":{ - "width":960, - "height":480, - "color":0, - "backgroundImage":"https://XXXX.jpg"， - "fillMode": "FIT" - }, - "waterMarks":[ - { - "imageUrl":"https://XXXX.png", - "region":{ - "x":0, - "y":0, - "width":100, - "height":100, - "zOrder":50 - } - } - ], - "videoInputs":[ - { - "rtc":{ - "rtcChannel":"test01", - "rtcUid": 123, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - }, - "placeholderImageUrl":"https://XXXX.jpg", - "region":{ - "x":0, - "y":0, - "width":320, - "height":360, - "zOrder":1 - } - }, - { - "rtc":{ - "rtcChannel":"test01", - "rtcUid": 456, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - }, - "placeholderImageUrl":"https://XXXX.jpg", - "region":{ - "x":320, - "y":0, - "width":320, - "height":320, - "zOrder":1 - } - } - ], - "outputs":[ - { - "rtc":{ - "rtcChannel":"test", - "rtcUid":1000, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - }, - "audioOption":{ - "profileType":"AUDIO_PROFILE_MUSIC_STANDARD" - }, - "videoOption":{ - "fps":30, - "codec":"H264", - "bitrate":800, - "width":960, - "height":480, - "lowBitrateHighQuality":false - } - } - ] - } - } - } - } -} -``` - -**Scenario 2: Audio only with canvas** - -```json -{ - "services":{ - "cloudTranscoder":{ - "serviceType":"cloudTranscoderV2", - "config":{ - "transcoder":{ - "idleTimeout":180, - "audioInputs":[ - { - "rtc":{ - "rtcChannel":"test01", - "rtcUid": 123, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - } - }, - { - "rtc":{ - "rtcChannel":"test01", - "rtcUid": 456, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - } - } - ], - "canvas":{ - "width":960, - "height":480, - "color":0, - "backgroundImage":"https://XXXX.jpg" - }, - "outputs":[ - { - "rtc":{ - "rtcChannel":"test02", - "rtcUid":1000, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - }, - "audioOption":{ - "profileType":"AUDIO_PROFILE_MUSIC_STANDARD" - } - } - ] - } - } - } - } -} -``` - -**Scenario 3: Audio mixing for all users in the channel with canvas** - -```json -{ - "services":{ - "cloudTranscoder":{ - "serviceType":"cloudTranscoderV2", - "config":{ - "transcoder":{ - "idleTimeout":180, - "audioInputs":[ - { - "rtc":{ - "rtcChannel":"test01", - "rtcUid": 0, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - } - } - ], - "canvas":{ - "width":960, - "height":480, - "color":0, - "backgroundImage":"https://XXXX.jpg" - }, - "outputs":[ - { - "rtc":{ - "rtcChannel":"test02", - "rtcUid":1000, - "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7063" - }, - "audioOption":{ - "profileType":"AUDIO_PROFILE_MUSIC_STANDARD" - } - } - ] - } - } - } - } -} -``` - -### HTTP response - -#### Response header - -`X-Request-ID`: UUID (Universal Unique Identifier), which identifies this request. -
    • If there is an error in the request, print out the value in the log to troubleshoot the problem.
    • If the response status code of this request is not 2XX, this field might not appear in the response header.
    - -#### Response body - -The field structure contained in the response body is shown in the following figure: - -![](https://web-cdn.agora.io/docs-files/1664351656358) - -The meanings of the fields are shown in the following table: - -| Field | Type | Description | -| :------------------------------------------- | :----------- | :----------------------------------------------------------- | -| taskId | JSON Object | The task ID, which is the UUID, is used to identify the cloud transcoder created by this request. | -| createTs | Number | The Unix timestamp (seconds) when the cloud transcoding task was created. | -| status | String | The running status of the create task:
  • `IDLE`: The task is not started.
  • `PREPARED`: The task has received a request to start.
  • `STARTING`: The task is starting.
  • `CREATED`: The task initialization is completed.
  • `STARTED`: The task has been started.
  • `IN_PROGRESS`: The task is in progress.
  • `STOPPING`: The task is stopping.
  • `STOPPED`: The task has been stopped.
  • `EXIT`: The task exits normally.
  • `FAILURE_STOP`: The task exits abnormally. | -| services | JSON Object | The service information included in the task. | -| services.cloudTranscoder | JSON Object | The service name. | -| services.cloudTranscoder.serviceType | String | Service type. Cloud transcoding: `cloudTranscoderV2`. | -| services.cloudTranscoder.config | JSON Object | The service parameters. | -| services.cloudTranscoder.config.transcoder | (Required)String | The cloud transcoder object. For the fields and meanings included in the cloud transcoder object, refer to the fields and meanings in the request body. | -| services.cloudTranscoder.createTs | Number | The unix timestamp (seconds) when the cloud transcoder was created. | -| services.cloudTranscoder.status | String | The running status of the service:
  • `serviceIdle`:The service is not started.
  • `serviceReady`: The service is ready.
  • `serviceStarted`: The service has been started.
  • `serviceInProgress`: The service is in progress.
  • `serviceCompleted`: The service has been stopped and the tasks are all completed.
  • `servicePartialCompleted`: The service has been stopped and the task is partially completed.
  • `serviceValidationFailed`: The service parameter validation failed.
  • `serviceAbnormal`: The service exited abnormally.
  • `serviceUnknown`: The service status is unknown. | -| services.cloudTranscoder.message | String | The execution information of the service, describing the specific cause of the service exception. | -| services.cloudTranscoder.details | JSON Object | The execution details of the service. | -| eventHandlers | String | Reserved fields. | -| execution | JSON Object | Reserved fields. | -| execution.workflows | String | Reserved fields. | -| properties | String | Reserved fields. | -| sequenceId | String | Reserved fields. | -| variables | JSON Object | Reserved fields. | -| workflows | JSON Object | Reserved fields. | - -Response body example: - -```json -{ - "createTs": 1661324613, - "eventHandlers": {}, - "execution": { - "workflows": {} - }, - "properties": {}, - "sequenceId": "0", - "services": { - "cloudTranscoder": { - "config": {}, - "createTs": 1661324614, - "details": {}, - "message": "", - "serviceType": "cloudTranscoderV2", - "status": "serviceReady" - } - }, - "status": "STARTED", - "taskId": "609f28f2644f1ae1ceb041b7047e39aa", - "variables": {}, - "workflows": {} -} -``` - -## Delete: Destroy the cloud transcoder - -### HTTP request - -``` -DELETE https://api.agora.io/v1/projects//rtsc/cloud-transcoder/tasks/?builderToken= -``` - -#### Path parameter - -- `appId`: (Required) String type parameter. The App ID provided by Agora for each developer. You can get an App ID after creating a project in Agora Console. The App ID identifies each project. -- `taskId`: The task ID of the cloud transcoder, which is UUID, used to identify the cloud transcoder created by this request. - -#### Query parameter - -`builderToken`: (Required)String. Obtain the value of the builderToken through the `Acquire` method.`` - -#### Request header - -- `Content-Type`: `application/json` -- `Authorization`: The value of this field should refer to the `authentication `[instructions ](https://docs.agora.io/en/faq/restful_authentication) - -### HTTP response - -#### Response header - -`X-Request-ID`: UUID (Universal Unique Identifier), which identifies this request. -
    • If there is an error in the request, print out the value in the log to troubleshoot the problem.
    • If the response status code of this request is not 2XX, this field might not appear in the response header.
    - -#### Response body - -The response body contains the following fields: - -![](https://web-cdn.agora.io/docs-files/1664351673569) - -The meanings of the fields are shown in the following table: - -| Field | Type | Description | -| :------------------------------------------- | :----------- | :----------------------------------------------------------- | -| taskId | JSON Object | The task ID, which is UUID, is used to identify the cloud transcoder created by this request. | -| createTs | Number |The unix timestamp (seconds) when the task was created. | -| status | String | The running status of the create task:
  • `IDLE`: The task is not started.
  • `PREPARED`: The task has received a request to start.
  • `STARTING`: The task is starting.
  • `CREATED`: The task initialization is completed.
  • `STARTED`: The task has been started.
  • `IN_PROGRESS`: The task is in progress.
  • `STOPPING`: The task is stopping.
  • `STOPPED`: The task has been stopped.
  • `EXIT`: The task exits normally.
  • `FAILURE_STOP`: The task exits abnormally. | -| services | JSON Object | Service information included in the task. | -| services.cloudTranscoder | JSON Object | The service name. | -| services.cloudTranscoder.serviceType | String | Service type. Cloud transcoding: `cloudTranscoderV2`. | -| services.cloudTranscoder.config | JSON Object | The service parameters. | -| services.cloudTranscoder.config.transcoder | (Required)String | The cloud transcoder object. For the fields and meanings included in the cloud transcoder object, refer to the fields and meanings in the request body. | -| services.cloudTranscoder.createTs | Number | The unix timestamp (seconds) when the cloud transcoder was created. | -| services.cloudTranscoder.status | String | The running status of the service:
  • `serviceIdle`:The service is not started.
  • `serviceReady`: The service is ready.
  • `serviceStarted`: The service has been started.
  • `serviceInProgress`: The service is in progress.
  • `serviceCompleted`: The service has been stopped and the tasks are all completed.
  • `servicePartialCompleted`: The service has been stopped and the task is partially completed.
  • `serviceValidationFailed`: The service parameter validation failed.
  • `serviceAbnormal`: The service exited abnormally.
  • `serviceUnknown`: The service is in unknown status. | -| services.cloudTranscoder.message | String | The execution information of the service, describing the specific cause of the service exception. | -| services.cloudTranscoder.details | JSON Object | The execution details of the service. | -| eventHandlers | String | Reserved fields. | -| execution | JSON Object | Reserved fields. | -| execution.workflows | String | Reserved fields. | -| properties | String | Reserved fields. | -| sequenceId | String | Reserved fields. | -| variables | JSON Object | Reserved fields. | -| workflows | JSON Object | Reserved fields. | - -Response body example: - -```json -{ - "createTs": 1661324613, - "eventHandlers": {}, - "execution": { - "workflows": {} - }, - "properties": {}, - "sequenceId": "0", - "services": { - "cloudTranscoder": { - "config": {}, - "createTs": 1661324614, - "details": {}, - "message": "OnSlaveServiceStopped", - "serviceType": "cloudTranscoderV2", - "status": "serviceCompleted" - } - }, - "status": "STOPPED", - "taskId": "609f28f2644f1ae1ceb041b7047e39aa", - "variables": {}, - "workflows": {} -} -``` - -## Query: Query cloud transcoder status information - -### HTTP request - -``` -GET https://api.agora.io/v1/projects//rtsc/cloud-transcoder/tasks/?builderToken= -``` - -### Path parameter - -- `appId`: (Required) String type parameter. The App ID provided by Agora for each developer. You can get an App ID after creating a project in Agora Console. The App ID identifies each project. -- `taskId`: The task ID of the cloud transcoder, which is UUID, used to identify the cloud transcoder created by this request. - -### Query parameter - -`builderToken`: (Required)String. Obtain the value of the builderToken through the `Acquire` method.```` - -#### Request header - -- `Content-Type`: `application/json` -- `Authorization`: The value of this field should refer to the `authentication `[instructions ](https://docs.agora.io/en/faq/restful_authentication) - -### HTTP response - -#### Response header - -`X-Request-ID`: UUID (Universal Unique Identifier), which identifies this request. -
    • If there is an error in the request, print out the value in the log to troubleshoot the problem.
    • If the response status code of this request is not 2XX, this field might not appear in the response header.
    - -#### Response body - -The response body contains the following fields: - -![](https://web-cdn.agora.io/docs-files/1664351715856) - -The meanings of the fields are shown in the following table: - -| Field | Type | Description | -| :------------------------------------------- | :----------- | :----------------------------------------------------------- | -| taskId | JSON Object | The task ID, which is the UUID, is used to identify the cloud transcoder created by this request. | -| createTs | Number | The unix timestamp (seconds) when the task was created. | -| status | String | The running status of the create task:
  • `IDLE`: The task is not started.
  • `PREPARED`: The task has received a request to start.
  • `STARTING`: The task is starting.
  • `CREATED`: The task initialization is completed.
  • `STARTED`: The task has been started.
  • `IN_PROGRESS`: The task is in progress.
  • `STOPPING`: The task is stopping.
  • `STOPPED`: The task has been stopped.
  • `EXIT`: The task exits normally.
  • `FAILURE_STOP`: The task exits abnormally. | -| services | JSON Object |The service information included in the task. | -| services.cloudTranscoder | JSON Object | The service name. | -| services.cloudTranscoder.serviceType | String | Service type. Cloud transcoding: `cloudTranscoderV2`. | -| services.cloudTranscoder.config | JSON Object | The service parameters. | -| services.cloudTranscoder.config.transcoder | (Required)String | The cloud transcoder object. For the fields and meanings included in the cloud transcoder object, refer to the fields and meanings in the request body. | -| services.cloudTranscoder.createTs | Number | Unix timestamp (seconds) when the cloud transcoder was created. | -| services.cloudTranscoder.status | String | The running status of the service:
  • `serviceIdle`:The service is not started.
  • `serviceReady`: The service is ready.
  • `serviceStarted`: The service has been started.
  • `serviceInProgress`: The service is in progress.
  • `serviceCompleted`: The service has been stopped and the tasks are all completed.
  • `servicePartialCompleted`: The service has been stopped and the task is partially completed.
  • `serviceValidationFailed`: The service parameter validation failed.
  • `serviceAbnormal`: The service exited abnormally.
  • `serviceUnknown`: The service is in unknown status. | -| services.cloudTranscoder.message | String | Execution information of the service, describing the specific cause of the service exception. | -| services.cloudTranscoder.details | JSON Object | The execution details of the service. | -| eventHandlers | String | Reserved fields. | -| execution | JSON Object | Reserved fields. | -| execution.workflows | String | Reserved fields. | -| properties | String | Reserved fields. | -| sequenceId | String | Reserved fields. | -| variables | JSON Object | Reserved fields. | -| workflows | JSON Object | Reserved fields. | - -Response body example: - -```json -{ - "createTs": 1661420011, - "eventHandlers": {}, - "execution": { - "workflows": {} - }, - "properties": {}, - "sequenceId": "0", - "services": { - "cloudTranscoder": { - "config": {}, - "createTs": 1661420011, - "message": "OnSlaveServiceQueryUpdated", - "serviceType": "cloudTranscoderV2", - "status": "serviceInProgress" - } - }, - "status": "IN_PROGRESS", - "taskId": "c0077139e34d0949c719189a393aa7c0", - "variables": {}, - "workflows": {} -} -``` - -## Status codes - -- If the status code is `2XX`, the request is successful. -- If the status code is not `2XX`, the request fails. You can troubleshoot the problem based on the content of the `message` field in the corresponding response body. - -| Status code | Description | -| :---------------------- | :----------------------------------------------------------- | -| 200 OK | The request succeeds. | -| 201 Created | The task is already in progress, do not use the same builderToken to start the task repeatedly. | -| 202 Accepted | The server has received the task request, but has not completed the execution. Use the `Query` method to` query` the execution status. | -| 400 Bad Request | The request has a syntax error (such as a parameter error). If the App ID you fill in `appid` does not have the Cloud Transcoding permission, it also returns `400`. Process it in combination with the `message` field of the response body. | -| 401 Unauthorized | Authorization is invalid. | -| 403 Forbidden | Your App ID has not yet activated the cloud transcoder; contact Agora. | -| 404 Not Found | The cloud transcoder is not found. | -| 409 Conflict |A cloud transcoder already exists with the same name. If you want to create a new cloud transcoder, delete the old cloud transcoder with the same name first. | -| 429 Too Many Requests | The request rate exceeds the upper limit. | -| 500 Unknown | An error occurs in the Agora server. Try uploading the log files later. | -| 501 Not Implemented | This method is not implemented. | -| 503 Service Unavailable | The Agora server is temporarily overloaded or under maintenance. Use the retry mechanism or contact Agora. | -| 504 Gateway Timeout | Agora server internal error, the server acting as a gateway or proxy did not get the request from the upstream server, the upstream server is down. Contact Agora. | - -## Considerations - -This section summarizes the most important considerations for using Push Streaming RESTful API. - -- Do not do any logic to the content of the `message` field in the response body. If the request fails, troubleshoot the problem based on the status code. -- The status code of `202` only means that the server has received the task request. It does not mean that the execution is completed. You need to continue to query the execution status through the `Query` method to determine whether the task is completed. -- After receiving the `404` status code, if the `Create` request has returned successfully and the `Delete `method has not been actively called, or the idle state of the cloud transcoder exceeds the `idleTimeout` field in the request parameters, it is recommended you adopt a backoff algorithm (for example, the interval of 5 seconds, 10 seconds, 15 seconds) to call the `Query` method to confirm. -- After receiving the response status code of` 5xx`, there is generally a problem in the response process of the server. It is recommended that you use a backoff algorithm (such as 5 seconds, 10 seconds, 15 seconds interval) to call the `Query` request for confirmation. \ No newline at end of file diff --git a/markdown/cloud-transcoder/api.md b/markdown/cloud-transcoder/api.md new file mode 100644 index 00000000000..f4018548cff --- /dev/null +++ b/markdown/cloud-transcoder/api.md @@ -0,0 +1,807 @@ +声网针对多人连麦直播场景研发云端转码服务，支持在服务端将单个或多个主播的音视频流转码合流并输入到声网 RTC 频道。频道内观众仅需订阅转码合流后的音视频流即可观看直播。 + +使用云端转码服务后，观众无需订阅多个主播的音视频流，可大幅节省下行带宽压力和客户端设备性能消耗。 + +本文介绍如何通过 RESTful API 实现云端转码，以及如何保障 REST 服务高可用。 + +## 前提条件 + +- 声网 RESTful API 要求 Basic HTTP 认证，请确保完成 [HTTP 基本认证](https://docs.agora.io/cn/cloud-recording/faq/restful_authentication)。 +- 请确保已[联系声网技术支持](https://docs.agora.io/cn/Agora%20Platform/ticket?platform=All%20Platforms)开通云端转码服务。 + +## 技术原理 + +声网服务端将多路流转码合流的过程相当于创建一个 cloud transcoder。转码前的多路流是 cloud transcoder 的输入，转码后的流是 cloud transcoder 的输出。 + +你可以通过云端转码 RESTful API 控制 cloud transcoder： + +- `Acquire`：在开始云端转码前，必须先获取云端转码资源，用于云端转码任务。 +- `Create`：创建 cloud transcoder。声网服务器会开始将你指定的多路流转码合流并输入到声网 RTC 频道。 +- `Delete`：销毁 cloud transcoder。声网服务器会停止转码合流。 +- `Query`：查询 cloud transcoder 信息。声网服务器会查询你指定的 cloud transcoder 的状态信息。 + +## Acquire：获取云端转码资源 + +在开始录制前，必须先调用 `Acquire` 方法获取一个云端转码资源。 + +调用该方法成功后，你可以在响应包体中得到一个 builderToken。builderToken 的时效为 5 分钟，你需要在 5 分钟内使用该 builderToken 开始云端转码。一个 builderToken 仅可用于一次云端转码任务。 + +### HTTP 请求 + +```http +POST https://api.agora.io/v1/projects/{appId}/rtsc/cloud-transcoder/builderTokens +``` + +`appId`: String 型必填参数。声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 + +#### 请求头 + +- `Content-Type`: `application/json` +- `Authorization`: 该字段的值需参考[认证说明](https://docs.agora.io/cn/faq/restful_authentication) + +#### 请求包体 + +需要在请求包体中传入以下参数： + +| 字段 | 类型 | 描述 | +| :----------- | :----------- | :----------------------------------------------------------- | +| `instanceId` | String，必填 | 用户指定的实例 ID。长度必须在 64 个字符以内，支持的字符集范围为：
  • 所有小写英文字母（a-z）
  • 所有大写英文字母（A-Z）
  • 数字 0-9
  • "-", "_"
    一个 `instanceId` 可以生成多个 builderToken，但在一个任务中只能使用一个 builderToken 发起请求。 | + +请求包体示例： + +```json +{ + "instanceId" : "abc13328" +} +``` + +### HTTP 响应 + +#### 响应头 + +`X-Request-ID`: UUID（通用唯一识别码），用于标识本次请求。 +
    • 如果请求出错，请在日志中打印出该值，排查问题。
    • 如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。
    + +#### 响应包体 + +如果状态码为 2XX，则请求成功。响应包体包含以下字段： + +| 字段 | 类型 | 描述 | +| :----------- | :----- | :---------------------------------------------------- | +| `tokenName` | String | builderToken 的值，在后续调用其他方法时需要传入该值。 | +| `createTs` | Number | 生成 builderToken 时的 Unix 时间戳（秒）。 | +| `instanceId` | Number | 请求时设置的 `instanceId`。 | + +响应包体示例： + +```json +{ + "createTs": 1661324606, + "instanceId": "abc13328", + "tokenName": "nUwUbQf9Zg6tsgtLslGnDg0lk8RYaUE0***" +} +``` + +## Create：创建 cloud transcoder + +### HTTP 请求 + +```http +POST https://api.agora.io/v1/projects/{appId}/rtsc/cloud-transcoder/tasks?builderToken={tokenName} +``` + +#### 路径参数 + +`appId`: String 型必填字段。声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 + +#### 查询参数 + +`builderToken`: String 型必填字段。通过 `Acquire` 方法获取 builderToken 的参数值 `tokenName`。 + +#### 请求头 + +- `Content-Type`: `application/json` +- `Authorization`: 该字段的值需参考[认证说明](https://docs.agora.io/cn/faq/restful_authentication) + + +#### 请求包体 + +请求包体为 JSON Object 类型的 `services` 字段。字段结构如图所示： + +![](https://web-cdn.agora.io/docs-files/1664351637544) + +- `services` 包含如下字段： + + | 字段 | 类型 | 描述 | + | :---------------------------------- | :---------------- | :----------------------------------------------------------- | + | cloudTranscoder | JSON Object，必填 | 服务名称，开发者自行设置。需要保证一个 cloud transcoder 中使用的服务名称唯一。 | + | cloudTranscoder.serviceType | String，必填 | 服务类型。云端转码：`cloudTranscoderV2`。 | + | cloudTranscoder.config | JSON Object，必填 | 云端转码参数设置。用于设置 cloud transcoder 的业务参数。 | + | cloudTranscoder.config.transcoder | String，必填 | Cloud transcoder 的对象。 | + +- `transcoder` 包含如下字段： + + | 字段 | 类型 | 描述 | + | :--------------------------------- | :---------------- | :----------------------------------------------------------- | + | idleTimeout | Number，可选 | Cloud transcoder 处于空闲状态的最大时长（秒）。空闲指 cloud transcoder 处理的音视频流所对应的所有主播均已离开频道。空闲状态超过设置的 `idleTimeOut` 后， cloud transcoder 会自动销毁。取值范围为 [1,86400]，默认值为 300。 | + | audioInputs [] | JSON Object，可选 | Cloud transcoder 的音频输入源配置。
  • 如果你不传值，声网会将 `videoInputs[].rtc.rtcUid` 对应的输入源作为 cloud transcoder 的音频输入源。这种取值方式适用于对主播的音频和视频都转码的场景。
  • 如果你传值，声网会将你指定的音频输入源进行转码混音。这种取值方式适用于 `audioInputs[].rtc.rtcUid` 和 `videoInputs[].rtc.rtcUid` 不完全一致的场景，即部分主播的视频转码但音频不转码。 | + | audioInputs[].rtc | JSON Array，必填 | Cloud transcoder 的 RTC 音频输入源。支持多个 RTC 输入源。 | + | audioInputs[].rtc.rtcChannel | String，必填 | 输入源所属的 RTC 频道名。目前仅支持订阅单个频道的音视频源，音频源和视频源所属频道必须相同。 | + | audioInputs[].rtc.rtcUid | Number，必填 | 音频输入源所对应的 UID。RTC 频道内不允许存在相同的 UID。 | + | audioInputs[].rtc.rtcToken | String，必填 | Cloud transcoder 在进入待转码音频源所属 RTC 频道时所需设置的 Token。该值可用于确保频道安全，避免异常用户扰乱频道内其他用户。详见[使用 Token 鉴权](https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)。Cloud transcoder 在待转码音视频源所属 RTC 频道内的 UID 为声网随机分配，因此，生成 Token 时，你使用的 `uid` 必须为 0。 | + | videoInputs [] | JSON Array，必填 | Cloud transcoder 的视频输入配置。 | + | videoInputs[].rtc | JSON Array，必填 | Cloud transcoder 的 RTC 视频输入源。支持多个 RTC 输入源。 | + | videoInputs[].rtc.rtcChannel | String，必填 | 视频输入源所属的 RTC 频道名。目前仅支持订阅单个频道的音视频源，音频源和视频源所属频道必须相同。 | + | videoInputs[].rtc.rtcUid | Number，必填 | 视频输入源所对应的 UID。RTC 频道内不允许存在相同的 UID。 | + | videoInputs[].rtc.rtcToken | String，必填 | Cloud transcoder 在进入待转码视频源所属 RTC 频道时所需设置的 Token。该值可用于确保频道安全，避免异常用户扰乱频道内其他用户。详见[使用 Token 鉴权](https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)。Cloud transcoder 在待转码音视频源所属 RTC 频道内的 UID 为声网随机分配，因此，生成 Token 时，你使用的 `uid` 必须为 0。 | + | videoInputs[].region | JSON Object，必填 | 视频输入源画面在画布上的位置。 | + | videoInputs[].region.x | Number，必填 | 画面在画布上的 x 坐标 (px)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。取值范围为 [0,3840]。 | + | videoInputs[].region.y | Number，必填 | 画面在画布上的 y 坐标 (px)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。取值范围为 [0,3840]。 | + | videoInputs[].region.width | Number，必填 | 画面的宽度 (px)。取值范围为 [120,3840]。 | + | videoInputs[].region.height | Number，必填 | 画面的高度 (px)。取值范围为 [120,3840]。 | + | videoInputs[].region.zOrder | Number，必填 | 画面的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。 | + | videoInputs [].placeholderImageUrl | String，必填 | 用户离线时占位图片的 URL。必须为合法 URL，且包含 `jpg` 或 `png` 后缀。 | + | canvas | JSON Object，必填 | 承载 cloud transcoder 合图的画布。 | + | canvas.height | Number，必填 | 画布的高度 (px)。取值范围为 [120,3840]。 | + | canvas.width | Number，必填 | 画布的宽度 (px)。取值范围为 [120,3840]。 | + | canvas.color | String，必填 | 画布的背景色。RGB 颜色值，以十进制数表示。如 0 代表黑色，255 代表蓝色。取值范围为 [0,16777215]。 | + | canvas.backgroundImage | String，可选 | 画布背景图。必须为合法 URL，且包含 `jpg` 或 `png` 后缀。 | + | canvas.fillMode | String，可选 | 画布背景图的填充模式。
  • （默认）`FILL`：在保持长宽比的前提下，缩放画面，并居中剪裁。
    ![img](https://web-cdn.agora.io/docs-files/1628837665989)
  • `FIT`：在保持长宽比的前提下，缩放画面，使其完整显示。
    ![img](https://web-cdn.agora.io/docs-files/1628837708782) | + | waterMarks [] | JSON Array，可选 | Cloud transcoder 的水印输入配置。 | + | waterMarks [].imageUrl | String，必填 | 水印图片的 URL。必须为合法 URL，且包含 `jpg` 或 `png` 后缀。 | + | waterMarks [].fillMode | String，可选 | 水印的填充模式。
  • （默认）`FILL`：在保持长宽比的前提下，缩放画面，并居中剪裁。
    ![img](https://web-cdn.agora.io/docs-files/1628837665989)
  • `FIT`：在保持长宽比的前提下，缩放画面，使其完整显示。
    ![img](https://web-cdn.agora.io/docs-files/1628837708782) | + | waterMarks [].region | JSON Object，必填 | 水印在画布上的位置。 | + | waterMarks [].region.x | Number，必填 | 水印在画布上的 x 坐标 (px)。以画布左上角为原点，x 坐标为画面左上角相对于原点的横向位移。取值范围为 [0,3840]。 | + | waterMarks [].region.y | Number，必填 | 水印在画布上的 y 坐标 (px)。以画布左上角为原点，y 坐标为画面左上角相对于原点的纵向位移。取值范围为 [0,3840]。 | + | waterMarks [].region.width | Number，必填 | 水印的宽度 (px)。取值范围为 [120,3840]。 | + | waterMarks [].region.height | Number，必填 | 水印的高度 (px)。取值范围为 [120,3840]。 | + | waterMarks [].region.zOrder | Number，必填 | 水印的图层编号。取值范围为 [0,100]。0 代表最下层的图层。100 代表最上层的图层。 | + | outputs.rtc | JSON Object，必填 | cloud transcoder 的输出配置。 | + | outputs.rtc.rtcChannel | String，必填 | 转码输出的音视频流所属的 RTC 频道名。 | + | outputs.rtc.rtcToken | String，必填 | Cloud transcoder 在进入输出音视频流所属 RTC 频道时所需设置的 Token。该值可用于确保频道安全，避免异常用户扰乱频道内其他用户。详见[使用 Token 鉴权](https://docs.agora.io/cn/live-streaming-premium-4.x/token_server_android_ng?platform=Android)。Cloud transcoder 在转码输出音视频流所属 RTC 频道内的 UID 为你指定的 `outputs.rtc.rtcUid`，因此，生成 Token 时，你使用的 `uid` 必须和 `outputs.rtc.rtcUid` 一致。 | + | outputs.rtc.rtcUid | Number，必填 | Cloud transcoder 在转码输出音视频流所属 RTC 频道内的 UID。RTC 频道内不允许存在相同的 UID，因此，请确保该值与频道内其他用户 UID 不同。 | + | outputs.audioOption | JSON Object，可选 | 音频流的转码混音配置。如果你不传值，声网转码输出的音频属性为 `AUDIO_PROFILE_DEFAULT`，即 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。 | + | outputs.audioOption.profileType | String，可选 | 转码输出的音频属性。支持取值：
  • `AUDIO_PROFILE_DEFAULT`：默认值，48 kHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
  • `AUDIO_PROFILE_SPEECH_STANDARD`：32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps。
  • `AUDIO_PROFILE_MUSIC_STANDARD`: 48 KHz 采样率，音乐编码，单声道，编码码率最大值为 64 Kbps。
  • `AUDIO_PROFILE_MUSIC_STANDARD_STEREO`：48 KHz 采样率，音乐编码，双声道，编码码率最大值为 80 Kbps。
  • `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`：48 KHz 采样率，音 乐编码，单声道，编码码率最大值为 96 Kbps。
  • `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`：48 KHz 采样率，音乐编码，双声道，编码码率最大值为 128 Kbps。 | + | outputs.videoOption | JSON Object，必填 | 视频流的转码合图配置。 | + | outputs.videoOption.fps | Number，可选 | 转码输出视频的帧率 (fps)。取值范围为 [1,30]。默认值为 15。 | + | outputs.videoOption.codec | String，必填 | 转码输出视频的 codec。取值包括：
  • `H264`：标准 H.264 编码
  • `VP8`：标准 VP8 编码 | + | outputs.videoOption.bitrate | Number，可选 | 转码输出视频的码率。取值范围为 [1,10000]。如果你不传值，声网会根据网络情况和其他视频属性自动设置视频码率。 | + | outputs.videoOption.width | Number，必填 | 转码输出视频的宽度 (px)。取值范围为 [120,3840]。 | + | outputs.videoOption.height | Number，必填 | 转码输出视频的高度 (px)。取值范围为 [120,3840]。 | + +#### 请求包体示例 + +**场景一：音视频 + 水印 + 画布** + +将 UID 为 `123`、`456` 两个主播的音视频流转码合流并输入到 test 频道中。 + +```json +{ + "services":{ + "cloudTranscoder":{ + "serviceType":"cloudTranscoderV2", + "config":{ + "transcoder":{ + "idleTimeout":300, + "audioInputs":[ + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid": 123, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + } + }, + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid": 456, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + } + } + ], + "canvas":{ + "width":960, + "height":480, + "color":0, + "backgroundImage":"https://XXXX.jpg", + "fillMode": "FIT" + }, + "waterMarks":[ + { + "imageUrl":"https://XXXX.png", + "region":{ + "x":0, + "y":0, + "width":100, + "height":100, + "zOrder":50 + } + } + ], + "videoInputs":[ + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid": 123, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "placeholderImageUrl":"https://XXXX.jpg", + "region":{ + "x":0, + "y":0, + "width":320, + "height":360, + "zOrder":1 + } + }, + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid": 456, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "placeholderImageUrl":"https://XXXX.jpg", + "region":{ + "x":320, + "y":0, + "width":320, + "height":320, + "zOrder":1 + } + } + ], + "outputs":[ + { + "rtc":{ + "rtcChannel":"test", + "rtcUid":1000, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "audioOption":{ + "profileType":"AUDIO_PROFILE_MUSIC_STANDARD" + }, + "videoOption":{ + "fps":30, + "codec":"H264", + "bitrate":800, + "width":960, + "height":480, + "lowBitrateHighQuality":false + } + } + ] + } + } + } + } +} +``` + +**场景二：纯音频 + 画布** + +```json +{ + "services":{ + "cloudTranscoder":{ + "serviceType":"cloudTranscoderV2", + "config":{ + "transcoder":{ + "idleTimeout":180, + "audioInputs":[ + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid": 123, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + } + }, + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid": 456, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + } + } + ], + "canvas":{ + "width":960, + "height":480, + "color":0, + "backgroundImage":"https://XXXX.jpg" + }, + "outputs":[ + { + "rtc":{ + "rtcChannel":"test02", + "rtcUid":1000, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "audioOption":{ + "profileType":"AUDIO_PROFILE_MUSIC_STANDARD" + } + } + ] + } + } + } + } +} +``` + +**场景三：全频道混音 + 画布** + +```json +{ + "services":{ + "cloudTranscoder":{ + "serviceType":"cloudTranscoderV2", + "config":{ + "transcoder":{ + "idleTimeout":180, + "audioInputs":[ + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid": 0, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + } + } + ], + "canvas":{ + "width":960, + "height":480, + "color":0, + "backgroundImage":"https://XXXX.jpg" + }, + "outputs":[ + { + "rtc":{ + "rtcChannel":"test02", + "rtcUid":1000, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "audioOption":{ + "profileType":"AUDIO_PROFILE_MUSIC_STANDARD" + } + } + ] + } + } + } + } +} +``` + +### HTTP 响应 + +#### 响应头 + +`X-Request-ID`: UUID（通用唯一识别码），用于标识本次请求。 +
    • 如果请求出错，请在日志中打印出该值，排查问题。
    • 如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。
    + +#### 响应包体 + +如果状态码为 2XX，则请求成功。响应包体包含的字段结构如下图所示： + +![](https://web-cdn.agora.io/docs-files/1664351656358) + +字段含义详见下表： + +| 字段 | 类型 | 描述 | +| :------------------------------------------- | :----------- | :----------------------------------------------------------- | +| taskId | JSON Object | 任务 ID，为 UUID，用于标识本次请求创建的 cloud transcoder。 | +| createTs | Number | 创建云端转码任务时的 Unix 时间戳（秒）。 | +| status | String | 创建任务的运行状态：
  • `"IDLE"`: 任务未开始
  • `"PREPARED"`: 任务已收到开启请求
  • `"STARTING"`: 任务正在开启
  • `"CREATED"`: 任务初始化完成
  • `"STARTED"`: 任务已经启动
  • `"IN_PROGRESS"`: 任务正在进行
  • `"STOPPING"`: 任务正在停止
  • `"STOPPED"`: 任务已经停止
  • `"EXIT"`: 任务正常退出
  • `"FAILURE_STOP"`: 任务异常退出 | +| services | JSON Object | 任务中包含的服务信息。 | +| services.cloudTranscoder | JSON Object | 服务名称。 | +| services.cloudTranscoder.serviceType | String | 服务类型。云端转码：`"cloudTranscoderV2"`。 | +| services.cloudTranscoder.config | JSON Object | 服务参数。 | +| services.cloudTranscoder.config.transcoder | String，必填 | Cloud transcoder 对象。包含的字段及含义请参考请求包体字段及含义。 | +| services.cloudTranscoder.createTs | Number | 创建 cloud transcoder 时的 Unix 时间戳（秒）。 | +| services.cloudTranscoder.status | String | 服务的运行状态：
  • `"serviceIdle"`: 服务未开始
  • `"serviceReady"`: 服务已经就绪
  • `"serviceStarted"`: 服务已经开始
  • `"serviceInProgress"`: 服务正在进行
  • `"serviceCompleted"`: 服务已经停止，任务全部完成
  • `"servicePartialCompleted"`: 服务已经停止，任务部分完成
  • `"serviceValidationFailed"`: 服务参数验证失败
  • `"serviceAbnormal"`: 服务异常退出
  • `"serviceUnknown"`: 服务未知状态 | +| services.cloudTranscoder.message | String | 服务的执行信息，描述服务异常的具体原因。 | +| services.cloudTranscoder.details | JSON Object | 服务的执行细节。 | +| eventHandlers | String | 预留字段。 | +| execution | JSON Object | 预留字段。 | +| execution.workflows | String | 预留字段。 | +| properties | String | 预留字段。 | +| sequenceId | String | 预留字段。 | +| variables | JSON Object | 预留字段。 | +| workflows | JSON Object | 预留字段。 | + +响应包体示例： + +```json +{ + "createTs": 1661324613, + "eventHandlers": {}, + "execution": { + "workflows": {} + }, + "properties": {}, + "sequenceId": "0", + "services": { + "cloudTranscoder": { + "config": {}, + "createTs": 1661324614, + "details": {}, + "message": "", + "serviceType": "cloudTranscoderV2", + "status": "serviceReady" + } + }, + "status": "STARTED", + "taskId": "609f28f2644f1ae1ceb041b7047e3***", + "variables": {}, + "workflows": {} +} +``` + +## Delete：销毁 cloud transcoder + +### HTTP 请求 + +```http +DELETE https://api.agora.io/v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId}?builderToken={tokenName} +``` + +#### 路径参数 + +- `appId`: String 型必填字段。声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 +- `taskId`: cloud transcoder 的任务 ID，为 UUID，用于标识本次请求创建的 cloud transcoder。 + +#### 查询参数 + +`builderToken`: String 型必填字段。通过 `Acquire` 方法获取 builderToken 的参数值 `tokenName`。 + +#### 请求头 + +- `Content-Type`: `application/json` +- `Authorization`: 该字段的值需参考[认证说明](https://docs.agora.io/cn/faq/restful_authentication) + +### HTTP 响应 + +#### 响应头 + +`X-Request-ID`: UUID（通用唯一识别码），用于标识本次请求。 +
    • 如果请求出错，请在日志中打印出该值，排查问题。
    • 如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。
    + +#### 响应包体 + +如果状态码为 2XX，则请求成功。响应包体包含以下字段： + +![](https://web-cdn.agora.io/docs-files/1664351673569) + +字段含义详见下表： + +| 字段 | 类型 | 描述 | +| :------------------------------------------- | :----------- | :----------------------------------------------------------- | +| taskId | JSON Object | 任务 ID，为 UUID，用于标识本次请求创建的 cloud transcoder。 | +| createTs | Number | 创建任务时的 Unix 时间戳（秒）。 | +| status | String | 创建任务的运行状态：
  • `IDLE`: 任务未开始
  • `PREPARED`: 任务已收到开启请求
  • `STARTING`: 任务正在开启
  • `CREATED`: 任务初始化完成
  • `STARTED`: 任务已经启动
  • `IN_PROGRESS`: 任务正在进行
  • `STOPPING`: 任务正在停止
  • `STOPPED`: 任务已经停止
  • `EXIT`: 任务正常退出
  • `FAILURE_STOP`: 任务异常退出 | +| services | JSON Object | 任务中包含的服务信息。 | +| services.cloudTranscoder | JSON Object | 服务名称。 | +| services.cloudTranscoder.serviceType | String | 服务类型。云端转码：`cloudTranscoderV2`。 | +| services.cloudTranscoder.config | JSON Object | 服务参数。 | +| services.cloudTranscoder.config.transcoder | String，必填 | Cloud transcoder 对象。包含的字段及含义请参考请求包体字段及含义。 | +| services.cloudTranscoder.createTs | Number | 创建 cloud transcoder 时的 Unix 时间戳（秒）。 | +| services.cloudTranscoder.status | String | 服务的运行状态：
  • `serviceIdle`: 服务未开始
  • `serviceReady`: 服务已经就绪
  • `serviceStarted`: 服务已经开始
  • `serviceInProgress`: 服务正在进行
  • `serviceCompleted`: 服务已经停止，任务全部完成
  • `servicePartialCompleted`: 服务已经停止，任务部分完成
  • `serviceValidationFailed`: 服务参数验证失败
  • `serviceAbnormal`: 服务异常退出
  • `serviceUnknown`: 服务未知状态 | +| services.cloudTranscoder.message | String | 服务的执行信息，描述服务异常的具体原因。 | +| services.cloudTranscoder.details | JSON Object | 服务的执行细节。 | +| eventHandlers | String | 预留字段。 | +| execution | JSON Object | 预留字段。 | +| execution.workflows | String | 预留字段。 | +| properties | String | 预留字段。 | +| sequenceId | String | 预留字段。 | +| variables | JSON Object | 预留字段。 | +| workflows | JSON Object | 预留字段。 | + +响应包体示例： + +```json +{ + "createTs": 1661324613, + "eventHandlers": {}, + "execution": { + "workflows": {} + }, + "properties": {}, + "sequenceId": "0", + "services": { + "cloudTranscoder": { + "config": {}, + "createTs": 1661324614, + "details": {}, + "message": "OnSlaveServiceStopped", + "serviceType": "cloudTranscoderV2", + "status": "serviceCompleted" + } + }, + "status": "STOPPED", + "taskId": "609f28f2644f1ae1ceb041b7047e3***", + "variables": {}, + "workflows": {} +} +``` + +## Update：更新指定的 cloud transcoder + +### HTTP 请求 + +```http +PATCH https://api.agora.io/v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId}?builderToken={tokenName}&sequenceId={sequenceId}&updateMask=services.cloudTranscoder.config +``` + +#### 路径参数 + +- `appId`: String 型必填字段。声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 +- `taskId`: cloud transcoder 的任务 ID，为 UUID，用于标识本次请求创建的 cloud transcoder。 + +#### 查询参数 + +- `builderToken`: String 型必填字段。通过 `Acquire` 方法获取 `builderToken` 的参数值 `tokenName`。 +- `sequenceId`：Number 型必填字段。`Update` 请求的序列号。取值需要大于或等于 0。请确保后一次 `Update` 请求的序列号大于前一次 `Update` 请求的序列号。序列号可以确保声网服务器按照你指定的最新配置来更新 cloud transcoder。 + +>声网推荐你在第一次调用 `Update` 时，将 `sequence` 设置为 `0`。在第二次调用 `Update` 时，将 `sequence` 填 `1`。在第三次调用 `Update` 时，将 `sequence` 填 `2`。依次类推。声网服务器会按照最新 `Update` 请求（即最大的序列号）更新 cloud transcoder。 + +```http +PATCH https://api.agora.io/v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId}?builderToken={tokenName}&sequenceId={sequenceId}&updateMask=services.cloudTranscoder.config +``` + +#### 请求头 + +- `Content-Type`: `application/json` +- `Authorization`: 该字段的值需参考[认证说明](https://docs.agora.io/cn/faq/restful_authentication) + +#### 请求包体 + +请求包体包含字段及含义详见 [Create 请求包体](#create)。 + +### HTTP 响应 + +#### 响应头 + +`X-Request-ID`: UUID（通用唯一识别码），用于标识本次请求。 +
    • 如果请求出错，请在日志中打印出该值，排查问题。
    • 如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。
    + +#### 响应包体 + +- 如果状态码为 2XX，则请求成功。包体为空。 + +- 如果状态码不为 2XX，请求失败。包体中包含 String 类型的 `message` 字段，描述失败的具体原因。 + + +### 请求示例 + +`Update` 仅支持在以下场景中更新 cloud transcoder： + +- 订阅或取消订阅频道内的主播的音视频流 +新增或删除 `audioInputs[]`、`videoInputs[]` 中的 `rtc` 成员。 +- 更新合图布局中各主播的位置 +修改 `videoInputs[]` 中的 `region` 字段 +- 更新输出音视频的音频配置项、视频配置项 +更新 `outputs[]` 中的 `audioOption`、`videoOption` 字段 + +
  • 你需要全量设置包体中的字段，对于不想要更新的字段，请维持原设置。
  • 除以上列举字段，其余字段均不支持更新。
  • 请按照调用 Create 时设置的场景更新 cloud transcoder，否则会发生未知异常。 + +音视频场景下更新 cloud transcoder 示例代码如下： + + ```json +{ + "services":{ + "cloudTranscoder":{ + "serviceType":"cloudTranscoderV2", + "config":{ + "transcoder":{ + "idleTimeout":300, + "audioInputs":[ + { + "rtc":{ + "rtcChannel":"test", + "rtcUid": 123, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + } + }, + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid":456, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + } + } + ], + "canvas":{ + "width":960, + "height":480, + "color":0, + "backgroundImage":"https://XXXX.jpg", + "fillMode": "FIT" + }, + "waterMarks":[ + { + "imageUrl":"https://XXXX.png", + "region":{ + "x":0, + "y":0, + "width":100, + "height":100, + "zOrder":50 + } + } + ], + "videoInputs":[ + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid":123, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "placeholderImageUrl":"https://XXXX.jpg", + "region":{ + "x":0, + "y":0, + "width":320, + "height":360, + "zOrder":1 + } + }, + { + "rtc":{ + "rtcChannel":"test01", + "rtcUid":456, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "placeholderImageUrl":"https://XXXX.jpg", + "region":{ + "x":320, + "y":0, + "width":320, + "height":320, + "zOrder":1 + } + } + ], + "outputs":[ + { + "rtc":{ + "rtcChannel":"test02", + "rtcUid":1000, + "rtcToken":"aab8b8f5a8cd4469a63042fcfafe7***" + }, + "audioOption":{ + "profileType":"AUDIO_PROFILE_MUSIC_STANDARD" + }, + "videoOption":{ + "fps":30, + "codec":"H264", + "bitrate":800, + "width":960, + "height":480, + "lowBitrateHighQuality":false + } + } + ] + } + } + } + } +} +``` + + +## Query：查询 cloud transcoder 状态信息 + +### HTTP 请求 + +```http +GET https://api.agora.io/v1/projects/{appid}/rtsc/cloud-transcoder/tasks/{taskId}?builderToken={tokenName> +``` + +### 路径参数 + +- `appId`: String 型必填字段。声网为每个开发者提供的 App ID。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。 +- `taskId`: cloud transcoder 的任务 ID，为 UUID，用于标识本次请求创建的 cloud transcoder。 + +### 查询参数 + +`builderToken`: String 型必填字段。通过 `Acquire` 方法获取 `builderToken` 的参数值 `tokenName`。 + +#### 请求头 + +- `Content-Type`: `application/json` +- `Authorization`: 该字段的值需参考[认证说明](https://docs.agora.io/cn/faq/restful_authentication) + +### HTTP 响应 + +#### 响应头 + +`X-Request-ID`: UUID（通用唯一识别码），用于标识本次请求。 +
    • 如果请求出错，请在日志中打印出该值，排查问题。
    • 如果本次请求的响应状态码不是 2XX，那么响应 header 中可能无该字段。
    + +#### 响应包体 + +响应包体包含以下字段： + +![](https://web-cdn.agora.io/docs-files/1664351715856) + +字段含义详见下表： + +| 字段 | 类型 | 描述 | +| :------------------------------------------- | :----------- | :----------------------------------------------------------- | +| taskId | JSON Object | 任务 ID，为 UUID，用于标识本次请求创建的 cloud transcoder。 | +| createTs | Number | 创建任务时的 Unix 时间戳（秒）。 | +| status | String | 创建任务的运行状态：
  • `IDLE`: 任务未开始
  • `PREPARED`: 任务已收到开启请求
  • `STARTING`: 任务正在开启
  • `CREATED`: 任务初始化完成
  • `STARTED`: 任务已经启动
  • `IN_PROGRESS`: 任务正在进行
  • `STOPPING`: 任务正在停止
  • `STOPPED`: 任务已经停止
  • `EXIT`: 任务正常退出
  • `FAILURE_STOP`: 任务异常退出 | +| services | JSON Object | 任务中包含的服务信息。 | +| services.cloudTranscoder | JSON Object | 服务名称。 | +| services.cloudTranscoder.serviceType | String | 服务类型。云端转码：`cloudTranscoderV2`。 | +| services.cloudTranscoder.config | JSON Object | 服务参数。 | +| services.cloudTranscoder.config.transcoder | String，必填 | Cloud transcoder 对象。包含的字段及含义请参考请求包体字段及含义。 | +| services.cloudTranscoder.createTs | Number | 创建 cloud transcoder 时的 Unix 时间戳（秒）。 | +| services.cloudTranscoder.status | String | 服务的运行状态：
  • `serviceIdle`: 服务未开始
  • `serviceReady`: 服务已经就绪
  • `serviceStarted`: 服务已经开始
  • `serviceInProgress`: 服务正在进行
  • `serviceCompleted`: 服务已经停止，任务全部完成
  • `servicePartialCompleted`: 服务已经停止，任务部分完成
  • `serviceValidationFailed`: 服务参数验证失败
  • `serviceAbnormal`: 服务异常退出
  • `serviceUnknown`: 服务未知状态 | +| services.cloudTranscoder.message | String | 服务的执行信息，描述服务异常的具体原因。 | +| services.cloudTranscoder.details | JSON Object | 服务的执行细节。 | +| eventHandlers | String | 预留字段。 | +| execution | JSON Object | 预留字段。 | +| execution.workflows | String | 预留字段。 | +| properties | String | 预留字段。 | +| sequenceId | String | 预留字段。 | +| variables | JSON Object | 预留字段。 | +| workflows | JSON Object | 预留字段。 | + +响应包体示例： + +```json +{ + "createTs": 1661420011, + "eventHandlers": {}, + "execution": { + "workflows": {} + }, + "properties": {}, + "sequenceId": "0", + "services": { + "cloudTranscoder": { + "config": {}, + "createTs": 1661420011, + "message": "OnSlaveServiceQueryUpdated", + "serviceType": "cloudTranscoderV2", + "status": "serviceInProgress" + } + }, + "status": "IN_PROGRESS", + "taskId": "c0077139e34d0949c719189a393aa7c0", + "variables": {}, + "workflows": {} +} +``` + + +## 状态码汇总表 + +- 如果状态码为 `2XX`，则请求成功。 +- 如果状态码不为 `2XX`，则请求失败。请根据对应的响应包体中的 `message` 字段内容排查问题。 + +| 状态码 | 含义 | +| :---------------------- | :----------------------------------------------------------- | +| 200 OK | 请求成功。 | +| 201 Created | 任务已经在进行中 ，请勿用同一个 builderToken 重复开启任务。 | +| 202 Accepted | 服务端已经收到任务请求，但未执行完成。请通过 `Query` 方法查询执行状态。 | +| 400 Bad Request | 请求的语法错误（如参数错误）。如果你填入的 `appid` 没有开通云端录制权限，也会返回 `400`，请结合响应报文的 `message` 字段进行处理。 | +| 401 Unauthorized | Authorization 无效。 | +| 403 Forbidden | 你的 App ID 尚未开通 cloud transcoder，请联系我们。 | +| 404 Not Found | 找不到 cloud transcoder。 | +| 409 Conflict | 已经存在使用相同 `instanceId` 的 cloud transcoder 任务。如果你想创建新的 cloud transcoder，请先将旧的 cloud transcoder 删除。 | +| 429 Too Many Requests | 请求速率超过上限。 | +| 500 Unknown |声网服务器内部错误，请联系我们。 | +| 501 Not Implemented |该方法未实现。 | +| 503 Service Unavailable |声网服务器暂时超载或在临时维护中。请使用重试机制或联系我们。 | +| 504 Gateway Timeout |声网服务器内部错误，充当网关或代理的服务器未从上游服务器获取请求，上游服务器已关闭。请联系我们。 | + +## 注意事项 + +本节总结使用云端转码 RESTful API 的重要注意事项。 + +- 请不要对响应报文包体里的 `message` 字段的内容做任何逻辑，处理如果请求失败请结合状态码排查问题。 +- `202` 的状态码仅表示服务端已经收到任务请求，但不代表执行完成，需要继续通过 `Query` 方法查询执行状态来判断任务是否执行完成。 +- 收到 `404` 的状态码后，如果 `Create` 请求已返回成功且没有主动调用 `Delete` 方法，或者 cloud transcoder 的空闲状态超过请求参数中的 `idleTimeout` 字段，建议采取退避算法（例如间隔 5 秒、10 秒、15 秒）调用 `Query` 方法进行确认。 +- 收到 `5xx` 的响应状态码后，一般是服务端在响应的过程中出现了问题，建议采取退避算法（例如间隔 5 秒、10 秒、15 秒）调用 `Query` 请求进行确认。 \ No newline at end of file diff --git a/markdown/cloud-transcoder/overview.md b/markdown/cloud-transcoder/overview.md new file mode 100644 index 00000000000..f77d01e28da --- /dev/null +++ b/markdown/cloud-transcoder/overview.md @@ -0,0 +1,32 @@ +## 概述 + +声网针对**音视频直播**场景提供云端转码服务，支持在服务端拉取单个或多个主播的音视频源流，进行混音、合图、转码等处理后，发布到声网 RTC 频道中，以供观众端订阅。使用云端转码服务后，观众无需订阅多个主播的音视频流，可大幅节省下行带宽压力和客户端设备性能消耗。 + +## 技术原理 + +下图展示了使用声网服务来实现云端转码的工作流程。 + +![](https://web-cdn.agora.io/docs-files/1668165007849) + +你可以通过你的业务服务器发起云端转码请求，云端转码服务会从 RTC 频道中订阅主播的音视频流，并进行混音、合图或转码处理，再将处理后的音视频流发布到 RTC 频道中。观众端可根据实际场景选择订阅主播源流或转码处理后的音视频流： + +- 单个主播场景：可订阅主播源流或转码后的音视频流。 +- 多个主播连麦场景：订阅多个主播混音、合图、转码后的音视频流。 + +## 服务优势 + +### 能耗低 + +当观众端设备性能较差，无法在端上同时处理多路高清音视频流的编解码、渲染时，可通过该服务进行转码处理后再发布到 RTC 频道，以降低端上性能消耗。 + +### 低码率 + +观众端在下行网络较差时订阅多路主播视频流或单路主播高清视频流时，可通过该服务进行混音、合图、并转码处理成低码率流后再发布到 RTC 频道，从而提升视频流畅度。 + +### 兼容性 + +支持标准 H.264 和 VP8 编码。当主播使用设备平台为 Native，观众使用设备平台为 Web，可通过云端转码服务将主播源流转为 VP8 编码，提升 Web 端观众端用户体验。 + +## 计费说明 + +该服务目前处于公测阶段，可免费使用。 \ No newline at end of file diff --git a/markdown/cloud-transcoder/webhook.md b/markdown/cloud-transcoder/webhook.md new file mode 100644 index 00000000000..c5479bff9d0 --- /dev/null +++ b/markdown/cloud-transcoder/webhook.md @@ -0,0 +1,270 @@ +## 概述 + +声网消息通知服务可以将**云端转码**业务中的发生的一些事件以 HTTPS 请求的方式通知到你的服务器。 + +![](https://web-cdn.agora.io/docs-files/1675668130158) + +## 开通服务 + +使用声网消息通知服务前需要申请开通并进行配置，关于如何**开通服务**以及**消息通知回调的数据格式**详见[消息通知服务](https://docs.agora.io/cn/AgoraPlatform/ncs)。 + +## 事件 + +消息通知服务器可以通知云端转码业务下的四种事件： + +- 创建云端转码事件 +- 云端转码配置更新事件 +- 云端转码状态变化事件 +- 停止云端转码事件 + +### 事件公共字段 + +云端转码事件 `payload` 包含以下公共字段： + +- `taskId`：String 型字段。任务 ID。它是声网服务器生成的一个 UUID（通用唯一识别码），标识一个已创建的 cloud transcoder。 + +- `instanceId`：String 型可选字段。调用 `Acquire` 时为本次云端转码指定的实例 ID。 + +- `sequence`：Number 类型，消息序列号，从 0 开始计数。消息可能乱序到达或者丢失重发，可以通过该参数标识消息。 + +- `sendts`：Number 类型， 事件发生的时间 （UTC 时间）。Unix 时间戳，精确到毫秒。 + + - `serviceScene`：服务场景。云端转码的服务场景为 `rtsc/cloud-transcoder`。 + - `details`: JSON Object 型字段。消息内容，详见具体事件。 + + + +### 开始云端转码事件 + +当你调用 `Create` 成功创建一个 cloud transcoder 时，消息通知服务器会向你的服务器通知该事件。 + +`eventType` 为 110(`cloud_transcoder_started`)，`payload` 示例如下： + +```json +{ + "taskId":"1234", + "instanceId":"123", + "sequence":123, + "sendts":1656573243385, + "serviceScene":"rtsc/cloud-transcoder", + "details":{ + "event":"cloud_transcoder_started", + "state":"Transcoder success", + "createTs":1658112464000, + "transcoder":{ + "inputs":[ + { + "rtcChannel":"test01", + "rtcUid":123, + "audio":true, + "video":false + }, + { + "rtcChannel":"test01", + "rtcUid":456, + "audio":true, + "video":true + } + ], + "outputs":[ + { + "rtcChannel":"test01", + "rtcUid":1000, + "audio":true, + "video":true + } + ], + "userConfigDetail":"{XXXX}" + } + } +} +``` + +`details `包含如下字段： + +- `event`: String 型字段。回调事件类型。`cloud_transcoder_started` 表示成功创建一个 cloud transcoder。 + +- `state`: String 型字段，云端转码的状态。`Transcoder success 表示`成功创建一个 cloud transcoder，开始云端转码。 + + - `createTs`：Number 型字段。创建 cloud transcoder 时的 Unix 时间戳（秒）。 + + - `userConfigDetail`：String 类型。请求包体中的配置内容（`cloudTranscoder.config`）。 + + - `transcoder`：JSON Object 型字段。Cloud transcoder 的输入和输出配置。 + + - `inputs`[]：JSON Object 型字段。Cloud transcoder 的音视频输入源配置。 + + - `rtcChannel`：String 型字段。音视频输入源所属的 RTC 频道名。 + + - `rtcUid`：Number 型字段。音视频输入源所对应的 UID。 + - ` audio`：Bool 型字段。是否有音频输入源： + - `true`：有音频输入源。 + - `false`：无音频输入源。 + - `video`：Bool 型字段。是否有视频输入源： + - `true`：有视频输入源。 + - `false`：无视频输入源。 + - `outputs`[]：JSON Object 型字段。Cloud transcoder 的音视频输出配置。 + + - `rtcChannel`：String 型字段。输出音视频所属的 RTC 频道名。 + + - `rtcUid`：Number 型字段。输出音视频所对应的 UID。 + + - `audio`：Bool 型字段。是否有音频输出： + - `true`：有音频输出。 + - `false`：无音频输出。 + - `video`：Bool 型字段。是否有视频输出： + - `true`：有视频输出。 + - `false`：无视频输出。 + +### 云端转码配置更新事件 + +当你调用 `Update` 成功更新一个 cloud transcoder 配置时，消息通知服务器会向你的服务器通知该事件。 + +`eventType` 为 113(`cloud_transcoder_updated`)。 + +```json +{ + "taskId": "1234", + "instanceId": "123", + "sequence": 123, + "sendts": 1656573243385, + "serviceScene": "rtsc/cloud-transcoder", + "details": { + "event": "cloud_transcoder_updated", + "state": "running", + "createTs": 1658112464000, + "updateTs": 1658112464000, + "transcoder": { + "inputs": [ + { + "rtcChannel": "test01", + "rtcUid": 123, + "audio": true, + "video": false + }, + { + "rtcChannel": "test01", + "rtcUid": 456, + "audio": true, + "video": true + } + ], + "outputs": [ + { + "rtcChannel": "test01", + "rtcUid": 1000, + "audio": true, + "video": true + } + ], + "userConfigDetail": "json_string" + } + } +} +``` + +`details `包含如下字段： + +- `event`: String 型字段。回调事件类型。`cloud_transcoder_started` 表示成功创建一个 cloud transcoder。 + +- `state`: String 型字段，云端转码的状态。`running 表示 c`loud transcoder 正常运行中，正在进行云端转码。 + +- `createT`s：Number 型字段。创建 cloud transcoder 时的 Unix 时间戳（秒）。 + +- `updateTs`：Number 型字段。更新 cloud transcoder 配置时的 Unix 时间戳（秒）。 + +- `userConfigDetail`：String 类型。请求包体中的配置内容（`cloudTranscoder.config`）。 + +- `transcoder`：JSON Object 型字段。Cloud transcoder 的输入和输出配置。 + + - `inputs`[]：JSON Object 型字段。Cloud transcoder 的音视频输入源配置。 + + - `rtcChannel`：String 型字段。音视频输入源所属的 RTC 频道名。 + + - `rtcUid`：Number 型字段。音视频输入源所对应的 UID。 + + - `audio`：Bool 型字段。是否有音频输入源： + + - `true`：有音频输入源。 + - `false`：无音频输入源。 + + - `video`：Bool 型字段。是否有视频输入源： + + - `true`：有视频输入源。 + - `false`：无视频输入源。 + + - `outputs`[]：JSON Object 型字段。Cloud transcoder 的音视频输出配置。 + + - `rtcChannel`：String 型字段。输出音视频所属的 RTC 频道名。 + + - `rtcUid`：Number 型字段。输出音视频所对应的 UID。 + + - `audio`：Bool 型字段。是否有音频输出： + + - `true`：有音频输出。 + - `false`：无音频输出。 + + - `video`：Bool 型字段。是否有视频输出： + + - `true`：有视频输出。 + - `false`：无视频输出。 + +### 云端转码状态变化事件 + +成功创建一个 cloud transcoder 后，当 cloud transcoder 运行状态改变时，消息通知服务器会向你的服务器通知该事件。 + +`eventType` 为 112(`cloud_transcoder_status`)，`payload` 示例如下： + +```json +{ + "taskId": "1234", + "instanceId": "123", + "sequence": 123, + "sendts": 1656573243385, + "serviceScene": "rtsc/cloud-transcoder", + "details": { + "event": "cloud_transcoder_status", + "state": "running", + "createTs": 1658112464000, + "updateTs": 1658112464000 + } +} +``` + +`details `包含如下字段： + +- `event`: String 型字段。回调事件类型。`cloud_transcoder_started` 表示成功创建一个 cloud transcoder。 +- `state`: String 型字段，云端转码的状态。`running` 表示 cloud transcoder 正常运行中，正在进行云端转码。 +- `createTs`：Number 型字段。创建 cloud transcoder 时的 Unix 时间戳（秒）。 +- `updateTs`：Number 型字段。更新 cloud transcoder 配置时的 Unix 时间戳（秒）。 + + + +### 停止云端转码事件 + +当一个 cloud transcoder 被销毁而停止云端转码时，消息通知服务器会向你的服务器通知该事件。 + +`eventType` 为 111(`cloud_transcoder_stopped`)，`payload` 示例如下： + +``` +{ + "taskId": "1234", + "instanceId": "123", + "sequence": 123, + "sendts": 1656573243385, + "serviceScene": "rtsc/cloud-transcoder", + "details": { + "event": "cloud_transcoder_stopped", + "stopReason": "Stop request", + "createTs": 1658112464000, + "updateTs": 1658112464000 + } +} +``` + +`details `包含如下字段： + +- `event`: String 型字段。回调事件类型。`cloud_transcoder_started` 表示成功创建一个 cloud transcoder。 +- `stopReason`: String 型字段，云端转码停止的原因。你可以根据该字段排查云端转码异常停止的原因。 +- `createTs`：Number 型字段。创建 cloud transcoder 时的 Unix 时间戳（秒）。 +- `updateTs`：Number 型字段。更新 cloud transcoder 配置时的 Unix 时间戳（秒）。 \ No newline at end of file