CDN加速

点播文件转推

更新时间:2020-04-27 09:38:23

一. 功能简介

  直播发展至今,直播业务开始趋于同质化,直播平台在关注新功能的同时也越来越看重如何对直播内容进行二次利用,尤其是针对重大赛事,客户希望直播结束后继续循环播放录制的内容,以保持房间热度。对此网宿推出文件转推功能,可将客户的录制文件重新以直播流的形式转推到直播间供用户观看。

二. 使用说明

  文件转推功能是指由转推节点循环请求或顺序请求客户指定的点播文件,将文件内容以推流方式转推给客户指定的推流地址。为方便客户使用,网宿提供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接口时立即开始/结束点播文件转推。
  API接口:http://livect.chinanetcenter.com/api/cdn/v2/forwardRequest.action
  调用方式: POST
  HTTP头部: Content-Type:application/json
  Body内容:
  开始转推

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "1",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
				"url": "http://www.video.com/live/abc.mp4"
			},
			{
				"url": "http://www.video.com/live/1.flv",
				"absofftime": "20181022153000-20181022155000"
			},
			{
				"url": "http://www.video.com/live/2.mp4",
				"relofftime": "300-500"
			}
		],
		"forward": [{
				"url": "rtmp://www.push1.com/live/test"
			},
			{
				"url": "rtmp://www.push2.com/live/test2"
			}
		],
		"extendParam": {
			"loop": "1",
			"index": "1",
			"callBackFileInfo": "0"
		}
	}]
}

  说明:开始转推后,转推节点会循环读取点播文件进行转推处理,除非客户调用接口结束转推任务。
  结束转推

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "2",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": ""
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}]
	}]
}

  Body参数说明

字段名称 字段类型 字段含义 必填 举例说明
transcallbackurl string 回调地址
cmd string 转推指令 cmd=1 开始转推;cmd=2 结束转推;cmd=3 更新文件列表;cmd=5 文件续播
type string 转推类型 填写固定值,type = video
list list 推流列表

  list参数说明

字段名称 字段类型 字段含义 必填 举例说明
id string 客户任务标识ID 唯一任务标识ID,ID相同时会先停止原先任务,再进行拉流转推
src list 拉流信息 见下表src参数说明
forward list 转推信息 见下表forward参数说明
extendParam Array 扩展参数 见下表extendParam参数说明

  src参数说明

字段名称 字段类型 字段含义 必填 举例说明
url string 点播文件地址 支持填写多个点播文件,支持flv、mp4、m3u8视频文件格式,但不支持m3u8文件再嵌套m3u8.
absofftime string 点播文件的转推时间区间,多个时间用英文分号“;”分割 进行转推时读取文件内容的时间区间,比如:20181022153000-20181022155000,yyyymmddHHMMSS格式。时间优先级 relofftime> absofftime。
relofftime string 点播文件的转推时间区间,多个时间用英文分号“;”分割 单位是秒

  forward参数说明

字段名称 字段类型 字段含义 必填 举例说明
url string 推流地址 推流地址支持填写多个转推地址,且只支持rtmp格式推流

  extendParam参数说明

字段名称 字段类型 字段含义 必填 举例说明
loop int 文件循环次数 点播文件循环次数,src中有多个点播文件时,先顺序再循环。
index int 文件读取顺序 src中有多个文件时,从第几个文件开始转推,默认从第一个。
callBackFileInfo int 是否回调每次转推文件信息 0 不需要回调每次转推文件信息;1 回调每次转推文件信息;默认为0

  定时转推
  调用API接口定时开始/结束拉流转推的时间配置,到指定时间后才开始/结束拉流转推。
  API接口:http://livect.chinanetcenter.com/api/cdn/v2/forwardRequest.action
  调用方式: POST
  HTTP头部: Content-Type:application/json
  Body内容:
  定时结束

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "1",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/abc.mp4"
		}, {
			"url": "http://www.video.com/live/1.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/2.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}],
		"extendParam": {
			"loop": "1",
			"index": "1",
			"callBackFileInfo": "0"
		},
		"start": "1540216800000",
		"end": "1540220400000"
	}]
}

  说明:在指定时间点开始转推后,转推节点会循环读取点播文件进行转推处理,除非达到转推结束时间点,或者客户调用接口结束转推任务。

  Body参数说明

字段名称 字段类型 字段含义 必填 举例说明
transcallbackurl string 回调地址
cmd string 转推指令 cmd=1 开始转推;cmd=2 结束转推;cmd=3 更新文件列表;cmd=5 文件续播
type string 转推类型 填写固定值,type = video
list list 推流列表

  list参数说明

字段名称 字段类型 字段含义 必填 举例说明
id string 客户任务标识ID 唯一任务标识ID,ID相同时会先停止原先任务,再进行拉流转推
src list 拉流信息 见下表src参数说明
forward list 转推信息 见下表forward参数说明
start int 开始转推时间 13位unix时间戳,start小于当前时间时,则从当前时间立即开始转推。
end int 结束转推时间 13位unix时间戳,end必须晚于start时间5分钟以上,并且晚于当前时间5分钟以上
extendParam Array 扩展参数 见下表extendParam参数说明

  src参数说明

字段名称 字段类型 字段含义 必填 举例说明
url string 点播文件地址 支持填写多个点播文件,支持flv、mp4、m3u8视频文件格式,但不支持m3u8文件再嵌套m3u8.
absofftime string 点播文件的转推时间区间,多个时间用英文分号“;”分割 yyyymmddHHMMSS格式;时间优先级 end>relofftime> absofftime。
relofftime string 点播文件的转推时间区间,多个时间用英文分号“;”分割 单位是秒;时间优先级 end>relofftime

  forward参数说明

字段名称 字段类型 字段含义 必填 举例说明
url string 推流地址 支持填写多个转推地址,且只支持rtmp格式推流

  extendParam参数说明

字段名称 字段类型 字段含义 必填 举例说明
loop int 文件循环次数 点播文件循环次数,src中有多个点播文件时,先顺序再循环。优先级: end>loop
index int 文件读取顺序 src中有多个文件时,从第几个文件开始转推,默认从第一个。
callBackFileInfo int 是否回调每次转推文件信息 0 不需要回调每次转推文件信息;1 回调每次转推文件信息;默认为0

  定时结束
  配置定时转推任务之后,在转推任务结束时间前,仍可调用结束转推命令来终止该转推任务。结束转推命令,不带start和end参数。

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "2",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": ""
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}]
	}]
}

  更新文件
  文件转推过程中,也可以通过接口进行点播文件更新,并使用更新后的文件进行转推。Body内容:

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "3",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/d.mp4"
		}, {
			"url": "http://www.video.com/live/3.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/4.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}],
		"extendParam": {
			"loop": "1",
			"index": "1",
			"callBackFileInfo": "0",
			"waitCrtUrlFinish": "0"
		}
	}]
}

  Body参数说明

字段名称 字段类型 字段含义 必填 举例说明
cmd string 转推指令 cmd=3 更新文件列表;

  extendParam参数说明

字段名称 字段类型 字段含义 必填 举例说明
waitCrtUrlFinish int 文件更新是否立即生效 0 表示文件更新立即生效,即马上使用新文件进行转推;1 表示当前文件转推结束后生效,即当前文件转推结束后,再使用新文件进行转推。默认为0
  说明:1)更新文件命令中,其他携带的参数说明参考上文说明。      2)如果转推开始前更新文件列表,则会直接使用更新后文件进行转推。

  文件续播
  调用转推结束命令使转推结束时,系统会记录当前文件的播放时间点(有效期为48小时),之后可以调用接口对该文件进行续播,续播时转推节点会从上次结束时间点开始继续转推。
  Body内容:

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "5",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/d.mp4"
		}, {
			"url": "http://www.video.com/live/3.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/4.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2",
			"resetUrl": "rtmp://www.push3.com/live/test3"
		}]
	}]
}

  Body参数说明

字段名称 字段类型 字段含义 必填 举例说明
cmd string 转推指令 cmd=5 文件续播;

  extendParam参数说明

字段名称 字段类型 字段含义 必填 举例说明
resetUrl string 更换转推地址 续播时更换成哪个推流地址,默认不更换

  说明:
  1)文件续播命令中,其他携带的参数说明参考上文说明。
  2)如果转推自然结束后进行文件续播,并非调用cmd=2命令的结束,则等同于cmd=1的情况;
  3) 文件续播命令不支持 fops 和 extendParam参数,也就是文件续播无法进行转码处理。
  4)文件续播时间点记录有效期为48小时,超过48小时无法进行文件续播。

  转码或加水印
  接口除了实现转推功能外,通过携带相应的转码或加水印参数,还支持对转推流进行转码和添加水印处理。
  Body内容:

{
	"transcallbackurl": "http://www.callback.com/api",
	"cmd": "1",
	"type": "video",
	"list": [{
		"id": "123",
		"src": [{
			"url": "http://www.video.com/live/d.mp4",
			"wmimage": "http://ws.test.com/live/picture1.jpg",
			"wmgravity": "TOP_LEFT"
		}, {
			"url": "http://www.video.com/live/3.flv",
			"absofftime": "20181022153000-20181022155000"
		}, {
			"url": "http://www.video.com/live/4.mp4",
			"relofftime": "300-500"
		}],
		"forward": [{
			"url": "rtmp://www.push1.com/live/test"
		}, {
			"url": "rtmp://www.push2.com/live/test2"
		}],
		"fops": {
			"bps": "1200",
			"res": "25",
			"fps": "1280x640",
			"vcodec": "libx265",
			"acodec": "libmp3lame"
		}
	}]
}

  list参数说明

字段名称 字段类型 字段含义 必填 举例说明
fops Array 编码参数

  fops参数说明

字段名称 字段类型 字段含义 必填 举例说明
bps string 码率(bps) 1200
res string 分辨率 420x720 (中间是小写字母的“x”)
fps string 帧率(fps) 25
vcodec string 视频编码方案 libx264,支持方案:libx264,libx265,libvpx等。同时需添加水印时固定填写为 libx264。
acodec string 音频编码方案 Libfaac,支持方案:libmp3lame,libfaac,libvorbis等。

  src参数说明

字段名称 字段类型 字段含义 必填 举例说明
wmimage string 水印图片的URL地址 如果url中带&,则需要进行url转义
wmgravity string 水印位置 TOP_LEFT 左上角;TOP_CENTER 上部居中;TOP_RIGHT 右上角;CENTER_LEFT 中部靠左;CENTER 居中;CENTER_RIGHT 中部靠右;BOTTOM_LEFT 左下角;BOTTOM_CENTER 下部居中;BOTTOM_RIGHT 右下角。

  说明:转码或加水印命令中,其他携带的参数说明参考上文说明。

  接口响应信息

{
	"http_code": "200",
	"msg": "receive task success!",
	"call_time": 1479952114000
}

  返回状态码说明:
  200: 接口调用成功;
  400: 请求参数错误(参数缺失、时间格式异常等)
  403: 没有请求权限;

  转推回调信息

{
	"msg": "Start pushing!",
	"code": "0",
	"srcurl": "[{\"url\":\"http://www.video.com/live/abc.mp4\"}]",
	"cmd": "1",
	"id": "124",
	"forwardurl": "rtmp://www.push1.com/live/test"
}
字段名称 字段类型 字段含义 举例说明
id string 客户任务标识ID 若客户有带则回调 id
srcurl string 拉流信息列表
forwardurl string 转推信息列表
cmd string 转推指令 cmd=1 开始转推;cmd=2 结束转推
code string 转推结果 0:成功;1:失败 ;2:告警
msg string 回调信息
  说明:转推回调后,需要对端接口的服务器响应200状态码和body内容,body内容不做详细要求,但不能为空。

三. 应用场景

  1、 影院放映厅模式,实现电视节目播放的效果。
  2、 赛事结束后循环播放扩大赛事影响力。
  3、 大主播不在线时,以往期直播内容循环播放维持房间热度。
##四.注意事项
  1) 点播文件支持配置多个,转推地址也支持配置多路。
  2) 转推时若涉及到转码,也就是如果有设置bps,res,fps等转码参数,则对应的vcodec参数必须填写。
  3) 转推时获取点播文件或推流超时,服务器会进行重试,默认超时等待时间10S,重试3次。
  4) 当需要结束某个转推任务时,携带id和forward参数必须和开始转推任务携带的参数保持一致,比如开始转推时,id为123,转推地址为A,在结束任务时,需携带同样id=123和转推地址A;有多个转推地址的情况,可以停止其中一个或多个。
  5) 接口调用入参的src和forward后面没有双引号,是数组列表方式的,回调内容中的srcurl和forwardurl有双引号的,是string类型。
  6) 接口调用限制5分钟100次。