Make sure you have read Quickstart Guide before reading this section.
Item | Description |
---|---|
Request host | Domestic: api.jocloud.com; International: api-oversea.jocloud.com |
Request URL | /app/{appid}/v1/recordoss/{reqUri}?traceId={yourTraceId} reqUri: - startrtmp - stoprtmp |
Head | Content-Type: application/json;charset=UTF-8 token: Basic authorization. See its generation method in Basic HTTP Authentication |
startrtmp
The API for pushing streams to CDN carries video mixing parameters.
Content-type
is application/json;charset=utf-8
token
is Basic authorization. See its generation method in Basic HTTP Authentication.Parameters
Parameter | Required | Data Type | Description |
---|---|---|---|
appid | Yes | uint64 | Service application ID |
roomid | Yes | string | Room No. |
rtmpurl | Yes | string | Address(es) for Stream Pushing to CDN (required). Separate multiple addresses with , ; you may specify up to five addresses |
streamtype | Yes | uint32 | Stream type: 1=mixed stream pushing, 2=source stream pushing |
taskid | Required when pushing mixed streams | string | Stream mixing task ID, which is unique |
mixconfig | Required when pushing mixed streams | JSON | Video mixing configuration |
uid | Required when pushing source streams | string | User ID |
mixconfig
Parameter | Required | Data Type | Description |
---|---|---|---|
input | No | JSON | Input parameter; an array in JSON format; not required when using a template ID, see details in input |
output | Yes | JSON | Output parameter in JSON format, see details in output |
templateid | No | uint32 | Template ID: 1-horizontal layout 2-vertical layout 3-tiled layout 4-corner layout |
Note:
Input stream information is not required when using a layout template. Layout templates are only applicable to co-hosting within a room; for cross-roomco-hosting, custom-set layout information for each uid.
- Horizontal layout: the first user appears in the large upper window, while other users appear in small windows below. There may be two rows at most, each containing up to eight small windows, thus supporting the display of 17 users in total.
- Vertical layout: the first user appears in the large-window picture at the left side, with other users in the small-window pictures at the right side. Two rows of small windows can be provided at most, each of which can contain 8 pictures. In total, 17 user pictures can be supported in the small windows.
- Tiled layout: automatically adjust the size of each picture based on the number of users. The picture sizes of all users are the same, and 16 pictures (4 x 4) can be supported in total.
- Corner layout: the first user occupies the whole large window, and one small window hovers at each corner. This layout supports four small windows at most, and includes five pictures in total.
Parameter | Required | Data Type | Description |
---|---|---|---|
uid | Yes | string | Anchor user ID |
roomid | Yes | string | Input stream anchor’s publishing room. Current room ID is optional. |
streamtype | Yes | int | Stream type: 0: audio/video, 1: video, 2: audio |
layer | Yes | int | Layer (0 indicates the bottommost layer; 1 is the first layer up from the bottom, and so on) |
pos_x | Yes | int | Top left corner x-coordinate (coordinate system: x-axis increases from left to right; y-axis increases downward). Optional for audio-only stream mixing |
pos_y | Yes | int | Top left corner y-coordinate. Optional for audio-only stream mixing |
pos_h | Yes | int | Height in canvas. Optional during audio-only stream mixing |
pos_w | Yes | int | Width in canvas. Optional during audio-only stream mixing |
crop | No | int | Zoom options, 0: input stream display is centered and surrounded by a black border; 1: the screen is filled as much as possible by centering and clipping |
cutout_x | No | int | If input is a cutout from the original, the cutout area's x-coordinate in the original |
cutout_y | No | int | If input is a cutout from the original, the cutout area's y-coordinate in the original |
cutout_h | No | int | If input is a cutout from the original, the cutout area's height |
cutout_w | No | int | If input is a cutout from the original, the cutout area's width |
alpha | No | float | The transparency level of the video frame, value range: [0.0, 1.0] "0.0"- Completely transparent "1.0:"-Opaque |
Parameter | Required | Data Type | Description |
---|---|---|---|
streamtype | Yes | int | Stream type: 0: audio/video, 1: video, 2: audio |
videoheight | No | int | Video height (required for video streams), a multiple of 8 Value range: (0-10000), recommended value: 600 |
videowidth | No | int | Video width (required for video streams), a multiple of 8 Value range: (0-10000), recommended value: 800 |
videobitrate | No | int | Video bit rate (kbps) (required for video streams) Value range: (0-10000), recommended value: 800 |
videofps | No | int | Video frame rate (required for video streams), the server will set it to 60 if the current value is higher than 60 Value range: (0-60), deaflut value: 15, unit: fps |
videogop | No | int | Video GOP in frames (required for video streams), which is a multiple of videofps Value range: (0-1000), default value: 30, unit: fps |
videoencode | No | int | Video code (required for video streams) "100"-H264 (default), "101"-H265 |
audiobitrate | No | int | Audio bit rate (kbps) (required for audio streams), filled with a fixed value of 64 and adjust situationally according to the audioencode value. |
audiochannel | No | int | Number of audio tracks (required for audio streams), filled with a fixed value of 2 |
audiosample | No | int | Audio sampling rate (required for audio streams), filled with a fixed value of 44100 |
audioencode | No | int | Audio code (required for audio streams); 1=AAC+; 35=AAC (128kbps); recommended value: 1 |
patch | No | int | Video frame interpolation method: 0-no frame interpolation; 1-interpolation by black screen; 2-interpolation of the last frame; 3-interpolation by specified picture |
patchUrl | No | string | For frame interpolation method=3, specify the picture address not exceeding 256 bytes in length |
seilayout | No | int | SEI video mixing option. When seilayout=1, enter the video source stream layout information into the SEI field for mixed stream video |
watermark | No | JSON | Watermark types, see details in watermark |
background | No | JSON | Background, include color and picture |
base64seidata | No | string | SEI encoded in Base64, maximum size: 2048 bytes |
Parameter | Required | Data Type | Description |
---|---|---|---|
timestamp | No | JSON | Timestamp watermark, see details in timestamp |
textList | No | JSON Array | Text watermark , see details in textList |
imageList | No | JSON Array | Image watermark, see details in imageList |
Parameter | Required | Data Type | Description |
---|---|---|---|
x | Yes | int | The x coordinate of the watermark (taking the top left corner as the origin), range: (0,10000) it should be less than videowidth of output paramter |
y | Yes | int | The y coordinate of the watermark (taking the top left corner as the origin), range: (0,10000) it should be less than videoheight of output paramter |
format | Yes | string | Supported time formats: "%Y/%m/%d" "%Y-%m-%d" "%H:%M:%S" "%Y/%m/%d %H:%M:%S" "%Y-%m-%d %H:%M:%S" |
font | No | string | Font, default value: NotoSansCJK |
size | Yes | int | Font size, range: (0,100] |
color | No | string | Font color in RGB format, range: [000000, FFFFFF], default: FFFFFF (white) |
backgroundColor | No | string | Background color in RGB format, range: [000000, FFFFFF], default: 000000 (black) |
alpha | No | float | The transparency level of the video frame, value range: [0.0, 1.0] "0.0"- Completely transparent "1.0:"-Opaque |
Parameter | Required | Data Type | Description |
---|---|---|---|
x | Yes | int | The x coordinate of the watermark (taking the top left corner as the origin), range: (0,10000) it should be less than videowidth of output paramter |
y | Yes | int | The y coordinate of the watermark (taking the top left corner as the origin), range: (0,10000) it should be less than videoheight of output paramter |
content | Yes | string | Content |
font | No | string | Font, default value: NotoSansCJK |
size | Yes | int | Font size, range: (0,100] |
color | No | string | Font color in RGB format, range: [000000, FFFFFF], default: FFFFFF (white) |
backgroundColor | No | string | Background color in RGB format, range: [000000, FFFFFF], default: 000000 (black) |
alpha | No | float | The transparency level of the video frame, value range: [0.0, 1.0] "0.0"- Completely transparent "1.0:"-Opaque |
Parameter | Required | Data Type | Description |
---|---|---|---|
x | Yes | int | The x coordinate of the watermark (taking the top left corner as the origin), range: (0,10000) it should be less than videowidth of output paramter |
y | Yes | int | The y coordinate of the watermark (taking the top left corner as the origin), range: (0,10000) it should be less than videoheight of output paramter |
width | Yes | int | Image width, which should be less than videohwidth of output paramter, range: (0,10000) |
height | Yes | int | Image height, which should be less than videoheight of output paramter, range: (0,10000) |
url | Yes | string | Image URL, maximum length: 256 bytes |
scale | Yes | int | Zoom mode / cropped mode: 0-Uniformly scales the video until it fills the visible boundaries (cropped) 1-Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit) |
alpha | No | float | The transparency level of the video frame, value range: [0.0, 1.0] "0.0"- Completely transparent "1.0:"-Opaque |
Parameter | Required | Data Type | Description |
---|---|---|---|
color | No | string | Background color in RGB format, range: [000000, FFFFFF], default: 000000 (black) |
image | No | JSON | Background image, only image is valid when both image and color are set |
Parameter | Required | Data Type | Description |
---|---|---|---|
url | Yes | string | URL of the background image, maximum length: 256 bytes |
scale | Yes | int | Zoom mode / cropped mode: 0-Uniformly scales the video until it fills the visible boundaries (cropped) 1-Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit) |
Note:
The traceId tag is unique.
You do not need to set video mixing parameters for source stream pushing.
In mixed stream pushing scenarios, a streamtype output parameter of 2 enables audio-only stream pushing.
If a taskid already exists in a mixed stream pushing scenario, calling it will trigger a parameter update.
A default stream pushing task configuration is supported according to Appid levels. Contact customer support if you require this service.
startrtmp
Sample Requesthttps://api.jocloud.com/app/1470236061/v2/rtmpforward/startrtmp?traceId=biz201909121223210013
{
"appid":1470236061,
"roomid":"123",
"rtmpurl":"rtmp://aliyunbiz.upstream.biz.com/live/test",
"streamtype":1,
"taskid":"biz007",
"mixconfig":{
"input":[
{
"uid":"111",
"roomid":"123",
"streamtype":0,
"layer":0,
"pos_x":0,
"pos_y":0,
"pos_h":600,
"pos_w":400,
"crop":0
},
{
"uid":"222",
"roomid":"123",
"streamtype":0,
"layer":1,
"pos_x":400,
"pos_y":0,
"pos_h":600,
"pos_w":400,
"crop":0
}
],
"output":{
"streamtype":0,
"videoheight":600,
"videowidth":800,
"videobitrate":800,
"videofps":24,
"videogop":3,
"videoencode":100,
"audiobitrate":64,
"audiosample":44100,
"audiochannel":2,
"audioencode":1
}
}
}
startrtmp
Sample Response{
"code": 0,
"message": "success",
"traceId": "23116613407505472693518435"
}
code
: int, Response Code.message
: a string; any situation other than “success” will contain error details.traceId
: a string; traceId carried by a request; convenient for tracingstoprtmp
Stop the active pushing streams to CDN task
Content-type
is application/json;charset=utf-8
token
is Basic authorization. See its generation method in Basic HTTP Authentication.Parameters:
Parameter | Required | Data Type | Notes |
---|---|---|---|
appid | Yes | uint64 | Service application ID |
roomid | Yes | string | Room No. |
streamtype | Yes | uint32 | Stream type: 1=mixed stream pushing, 2=source stream pushing |
taskid | Mixed stream pushing (required) | string | Stream mixing task ID, is the corresponding active stream pushing task’s taskid |
uid | Source stream pushing (required) | string | User ID, is the corresponding active stream pushing task’s uid |
Note:
A default stream pushing task configuration is supported according to Appid levels. Contact customer support if you require this service.
stoprtmp
Sample Requesthttps://api.jocloud.com/app/1470236061/v2/rtmpforward/stoprtmp?traceId=biz201909121223210014
{
"appid":1470236061,
"roomid":"123",
"streamtype":1,
"taskid":"biz007"
}
stoprtmp
Sample Response{
"code": 0,
"message": "success",
"traceId": "82719231231166134075054726935"
}
code
: int, Response Code.message
: a string; any situation other than “success” will contain error details.traceId
: a string; traceId carried by a request; convenient for tracingEncode | Description | Note |
---|---|---|
0 | Succeeded | Request succeeded |
1000 | No token permission | No token in the service API header |
1001 | Invalid token | token format and/or content is incorrect |
1002 | No appid | No appid |
2101 | Invalid parameter | Invalid API parameter |
2102 | Abnormal stream status | Abnormal stream pushing status |
2103 | Timeout | Request timeout |
2104 | Internal error | Internal server error |
Before enabling stream pushing to CDN, make sure that the third-party service has enabled address authentication. Then, check to make sure the streams pushing address has a valid authentication code. After stream pushing failure, refresh the authentication code and push streams again.
Update the stream pushing address in full mode. Any preexisting stream pushing tasks not recorded in the new address list will be stopped, and any preexisting tasks given updated addresses in the new address list will be added to the stream pushing task
rtmp://upstream.jocloud.com/live/test?auth_key=1585626386-0-0-8032e26583c58344e43cce3e251173b7
The server returns push stream content and statuses by setting a callback address during stream pushing. The service has direct access to CDN callback; however, CDN callback generally only comes after the initial success. It is recommended that you connect your service to Jocloud's stream pushing callback. Contact Jocloud customer support to set up.
Parameter | Data type | Description |
---|---|---|
url | string | Stream pushing address |
appname | string | Application name |
streamname | string | Stream pushing name |
appid | uint64 | Service application ID |
roomid | string | Room No. |
taskid | string | Task ID, is the taskid of the corresponding active stream pushing task |
status | uint32 | Stream pushing status code. See the list of stream pushing callback status codes |
version | uint64 | Callback version |
errcode | uint32 | Error code, see details in [Error Codes](#Error Codes) |
description | string | Details |
Code | Description |
---|---|
3000 | Normal stream pushing. This code sends periodically. |
3001 | Audio/video streams cannot be pulled. Check uplink audio/video streams in the channel. This code sends periodically. |
3002 | Abnormal interruption of stream pushing. This code sends periodically. |
3003 | Stream pushing terminated |
Code | Description |
---|---|
0 | Normal |
1 | Incorrect URL format |
2 | The concurrency limit is reached |
3 | Timed out |
1001 | TCP connection break |
1002 | TCP connection failed |
1003 | RTMP push stream is rejected, please check whether the authentication parameter or the push stream name is repeated |
2001 | The stream pushing stopped |
2002 | The data to be pushed does not exist |
2003 | Internal error in the stream-pushing server |
Note: Access to the stream pushing callback service requires background configuration. Contact customer support if you require this service.
The following only introduces common status codes for stream pushing callback. Contact customer support if you encounter additional errors.
3001: audio/video streams cannot be pulled—typically due to an anchor uplink or publishing malfunction. The service side should check anchor status.
3002: stream pushing is interrupted—typically due stream pushing address authentication error or repeated pushing. The service side should check the stream pushing address.