点播文件转推
更新时间：2021-10-14 15:55:53
一． 功能简介
随着直播行业的不断发展，直播业务开始趋于同质化，直播平台在关注新功能的同时也越来越看重如何对直播内容进行二次利用，因此出现了重大赛事直播结束后循环播放的需求，出现了影院放映厅的需求，出现了以旧直播内容维持房间热度的需求，而网宿根据市场需求联合直播+云存储两大平台适时推出录制转直播功能，直播平台可根据自己的业务场景灵活使用网宿录制转直播接口满足业务需求。
二． 使用说明
网宿录制转直播功能通过API接口调用实现，可满足两种业务场景：
场景一：单文件按次数或时间循环播放，比如一场重要赛事直播结束后，可实时调用此接口将录制文件转成直播继续播放，可设置按次数或按时间段循环播放。
场景二：列表文件按次数或时间循环播放，比如影院放映厅模式下，可安排多个文件再调用此接口按次数或时间段循环播放，以此实现电视节目的播放效果。
具体调用参数说明如下：
API 具有权限控制，需有网宿已开通账号并以一定规则传入参数方可正确调用，权限控制由 n、r、k 三个参数决定，具体 n、r、k 说明如下：
1) n：默认设置为Protal平台帐号名；
2) r：唯一随机字符串，限制最大为10位，推荐使用时间戳；
3) k：md5验证值。
MD5 计算方式为: k = md5(r+key)，即 r 字符串加上key字符串，得到一个新的字符串，再对该字符串做MD5 计算出新值为k 的值。
注：key 可向对应客服获取。
例如：
1、 申请获取到key=012f37a3f2952 2、 随机生成字符串r=1409284800 3、 合并生成字符串new=1409284800012f37a3f2952 4、 使用MD5 计算new 得到 k值b9fed80be752551834eec3e52fa94115
API地址
http://livect.chinanetcenter.com/api/cdn/v2/forwardRequest.action
调用示例
采用Post方式请求，并且Content-Type 指定为“application/json”，其余方式不接受，具体示例如下：
URL：http://livect.chinanetcenter.com/api/cdn/v2/forwardRequest.action
{ "transcallbackurl": "http://ws.test.com/api/cdn/info.action",
"cmd": "1",
"type": "video",
"list": [
{
"id": "545414",
"src": [
{
"url":" http://www.video.com/live/test1.mp4",
"wmImage":" http://ws.test.com/live/picture1.jpg",
"wmGravity": "TOP_LEFT",
"absofftime":"20170510150000-20170510153000"
},
{
"url":"http://ws.test.com/live/test2.flv",
"wmImage":" http://ws.test.com/live/picture2.jpg",
"wmGravity": "TOP_LEFT",
"relofftime":"3600-7200"
}
],
"forward": [
{
"url": "rtmp://ws.test.com/live/test3 "
},
{
"url": " rtmp://ws.test.com/live/test4 "
}
],
"start": "1495177025000",
"end": "1495184225000",
"fops":{
"bps": "1200",
"res": "25",
"fps": "1280x640",
"vcodec": "libx265",
"acodec": "libmp3lame"
},
"extendParam": {
"loop": "2",
"index": "1",
"callBackFileInfo": "0",
"waitCrtUrlFinish": "1"
}
}
]
}
Body参数说明
| 字段名称 | 字段类型 | 字段含义 | 必填 | 举例说明 |
| transcallbackurl | string | 回调地址 | 否 | http://test/api/cdn/info.action |
| cmd | string | 转推指令 | 是 | cmd=1 转推开始指令；cmd=2 转推主动结束指令（亦表示暂停指令,转推保存48小时）；cmd= 3 转推列表转换指令；cmd=5 转推续播指令（基于2基础上） |
| type | string | 转推类型 | 是 | 默认video，此场景选择type=video保持默认即可 |
| list | list | 推流列表 | 是 | |
| id | string | 客户任务id | 是 | 56545647，如果传递重复的ID，会先停止原先任务再开启新的转推任务。（建议以时间戳传入） |
| src | list | 拉流信息 | 是 | 见下表拉流参数明细 |
| forward | list | 转推信息 | 是 | 见下表转推参数明细 |
| start | string | 开始时间 | 否 | 采用unix时间戳方式,位数为13位数字,单位ms. |
| end | string | 结束时间 | 否 | 采用unix时间戳方式,位数为13位数字,单位ms. |
| fops | array | 编码参数 | 否 | 见下表编码参数明细 |
| extendParam | array | 扩展参数 | 否 | 见下表编码参数明细 |
拉流参数说明
| 字段名称 | 字段类型 | 字段含义 | 必填 | 举例说明 |
| url | string | 点播文件地址 | 是 | http://ws3.test.com/api/cdn/test.flv，支持填写多个点播文件，支持flv、mp4、m3u8视频文件格式，但不支持m3u8文件再嵌套m3u8. |
| wmImage | string | 水印图片的URL地址 | 否 | http://ws3.test.com/app/picture.jpg（如果url中带&，需要进行url转义） |
| wmGravity | string | 水印位置 | 否 | 默认TOP_RIGHT。TOP_LEFT = 左上角；TOP_CENTER = 上部居中；TOP_RIGHT = 右上角；CENTER_LEFT = 中部靠左；CENTER = 居中；CENTER_RIGHT = 中部靠右；BOTTOM_LEFT = 左下角；BOTTOM_CENTER =下部居中；BOTTOM_RIGHT = 右下角； |
| absofftime | string | 输入片段的绝对时间设置，多个时间段用英文分号隔开 | 否 | 20170510150000-20170510153000;20170510160000-20170510163000 ，精确到秒(优先级 End > loop > relofftime >absofftime) |
| relofftime | string | 输入片段的相对时间设置，多个时间段用英文分号隔开 | 否 | 30-60;80-90 精确到秒 (优先级 End > loop > relofftime >absofftime) |
转推参数说明
| 字段名称 | 字段类型 | 字段含义 | 必填 | 举例说明 |
| url | string | 推流地址 | 是 | 推流地址支持填写多个转推地址，且只支持rtmp格式推流 |
| resetUrl | string | 更换转推地址 | 否 | cmd = 5 时候生效，表示续播更换转推地址 |
编码参数说明
| 字段名称 | 字段类型 | 字段含义 | 必填 | 举例说明 |
| bps | string | 码率 | 否 | 1200bps |
| res | string | 分辨率 | 否 | 420x720 (中间是小写字母的“x”) |
| fps | string | 帧率 | 否 | 25 |
| vcodec | string | 输出的视频转码方案 | 否 | 默认与输入一致。支持方案：libx264，libx265，libvpx等。 |
| acodec | string | 输出的音频转码方案 | 否 | 默认与输入一致。支持方案：libmp3lame，libfaac，libvorbis等。 |
扩展参数说明
| 字段名称 | 字段类型 | 字段含义 | 必填 | 举例说明 |
| loop | int | 文件循环次数 | 否 | 默认值为1；type=video时生效，转推次数设定 loop与end同时配置时以end为准 |
| index | int | 文件读取顺序 | 否 | type=video时生效，列表中的第几个文件开始转推。默认为1，即从点播列表第一个文件开始转推。 |
| offtime | string | 相对偏移时长 | 否 | 点播文件的开始转推的相对时长偏移，默认为0，单位为秒。例如为30时，表示从点播视频文件播放的第30秒处开始推流。 |
| callBackFileInfo | int | 是否回调每次转推文件信息 | 否 | 0 不需要回调每次转推文件信息；1 回调每次转推文件信息；默认为0 |
| waitCrtUrlFinish | string | 切换输入文件列表模式 | 否 | cmd = 3时使用，是否等待当前播放的url播完。默认为0，表示更新输入文件列表时，立即生效，播新的文件列表。为1时，表示播完当前url，再切换播新的文件列表。 |
接口响应信息
{
"http_code":"200",
"msg":"receive task success!",
"call_time":1479952114000
}
200：成功
400：请求参数错误（参数缺失、时间格式异常）
403：无权限
回调内容
默认不进行回调，若有设置回调地址，则以 jason 形式进行回调，具体回调参数说明如下：
| 字段名称 | 字段类型 | 字段含义 | 举例说明 |
| id | string | 客户任务标识ID | 若客户有带则回调 id |
| srcurl | string | 拉流信息列表 | 具体拉流列表信息 |
| forwardurl | string | 转推信息列表 | 具体转推列表信息 |
| cmd | string | 转推指令 | cmd=1 开始转推；cmd=2 结束转推 |
| code | string | 转推结果 | 0：开始推流； 1：推流正常结束； 2：推流外部异常结束； 3：推流内部异常结束 4：轮播转推失败告警，将执行下一个转推文件； 5：轮播转推时，回调文件信息 90：任务不存在，针对cmd2,cmd3,cmd5 91：重复任务，相同forward url的任务不能同时在执行 92：任务执行失败，请重试 |
| msg | string | 回调信息 | |
| event_time | Long | 事件发生时间 |
回调实例
{
"msg": "Start pushing!",
"code": "0",
"srcurl": "[{"url":"http://ws.test.com/live/test1.flv"},{"url":" http://ws.test.com/live/test2.flv"}]",
"cmd": "1",
"id": "8fb2eacc",
"forwardurl ": "rtmp://ws.test.com/live/test3"
"event_time":1600402486054
}
三． 应用场景
1、 影院放映厅模式，实现电视节目播放的效果。
2、 赛事结束后循环播放扩大赛事影响力。
3、 大主播不在线时，以往期直播内容循环播放维持房间热度。
四．注意事项
- start和end参数具体场景
| start | end | 场景 |
| 无配置 | 无配置 | 调用时开始转推，调用cmd=2或流结束时停止 |
| 无配置 | 有配置 | 调用时开始转推，调用cmd=2或end时间时停止 |
| 有配置 | 无配置 | start时间时开始转推，调用cmd=2或流结束时停止 |
| 有配置 | 有配置 | start时间开始转推，调用cmd=2或end时间停止 |
-
start 和 end 的间隔时间不得低于5分钟，end 时间不能晚于当前时间5分钟
-
loop 与 end 参数若同时配置，以 end 参数为准。
-
type=video 时，多个文件列表播放时有两种情况会播放下一个文件，第一：当前文件拉流失败，并且重试三次后依然失败，则拉取下一个文件；第二：当前文件播放结束，顺序播放下一个文件。
-
码率的单位为 bps，比如要设置400kbps，则参数 bps=400000。
-
转推时若涉及到转码，也即若有设置bps,res,fps等转码参数，则对应的vcodec参数必须配置。
-
cmd=3适用场景为任务已经开始后需切换播放地址时，因此若预设任务未开始则需先暂停后再更换，且更换转推列表只能更换源地址 src 部分，调用格式与例子相同，可携fops 和 extendParam 参数。
-
cmd=5适用场景为任务暂停时重新播放，任务暂停分为两种情况，一是转推文件全部播完自然结束暂停，二是调用cmd=2人工暂停，以上两种情况发生后的48小时以内可以调用cmd=5进行续播。第一种情况续播从第一个文件从头开始续播，第二种情况从人工暂停处开始续播，此场景不识别 fops 和 extendParam 参数，因此只要id，src 和 forward可以匹配即可。
-
callBackFileInfo 所回调的文件相关信息在回调信息中的msg中体现，比如"msg":“rtmp://ws.test.com/live/test beginTime:1518230486347 endTime:1518234086347”
-
当需要结束某个任务时，携带id和forward参数必须和任务下发时携带的参数保持一致，比如下发任务时，id为123，有多个转推地址比如A,B,C，在结束任务时，需携带同样id=123，对应转推地址进行停止。
-
接口调用入参的src和forward后面没有双引号，是数组列表方式的，回调内容中的srcurl和forwardurl有双引号的，是字符串类型。
-
接口调用频率限制5分钟100次。