NTV Media Server G3

NTV Media Server G3 API Specification

1.概述

1.1.用途及阅读方法

远程管理API提供一组接口，其他系统（如企业的业务管理系统、媒资管理系统、用户管理系统、OA系统等）可以通过调用接口来查询流媒体服务器的数据和更改流媒体服务器的配置，实现与流媒体服务器的集成。阅读本接口规范时，请首先认真阅读《概述》章节（即本章节），然后在阅读《登录认证》章节，这两个章节是必须阅读的部分。其他章节根据需要选择阅读，例如要做转码集成，阅读《文件管理》和《转码》章节即可。

1.2.适用版本

本文档定义的接口规范，对版本号大于等于3.6.500的流媒体服务器系统有效。较低版本服务器，继续使用对应版本的接口规范。

1.3.通信协议

本规范中，流媒体服务器是通信的服务器端（简称“服务器”），调用接口的其他系统是通信客户端（简称“客户端”）。客户端和服务器通过HTTP协议通信，客户端使用HTTP Get向服务器发送请求，服务器返回json格式的业务数据或操作结果给客户端。

1.4.接口请求

接口的请求地址是个URL地址，每个接口URL地址都包括分组位置和请求参数，例如： http://ip/mserver/interface/appMgr/?request=get&token=123456 其中： http://ip/mserver/interface/appMgr/ 是接口请求的URL位置，“ip”在实际请求中要替换成服务器的ip地址或域名。 http://ip/mserver/interface/ 代表流媒体服务器接口服务在Web上的部署的位置，要保持不变。 appMgr是接口的分组位置，流媒体服务器接口包括了多个分组位置，具体参见接口定义部分。符号?后面是参数列表，以name=value的形式体现。其中： request参数是在所有接口中都要有的，该参数表明了请求业务的类型。 token参数提供一个安全认证符号给服务器，服务器用token来验证客户端的合法性，除了登录验证接口之外，其他接口都需要token参数。有关URL地址的编码规范，请参考HTTP 1.1规范。

1.5.接口响应

服务器在收到接口请求后，首先判断token的正确性，如果token错误，则返回认证错误的消息给客户端。如果token正确，服务器返回json格式的文本内容给客户端。返回给客户端的json文本描述了服务器对请求的处理结果和响应数据。

1.6.接口安全

客户端必须首先通过身份认证才能继续调用接口，在一个“挑战—>应答”模式的身份认证过程中完成身份认证，认证通过后，服务器为客户端分配一个临时令×××token，在后续的请求中，token作为一项必选参数提供，服务器通过token识别用户身份和验证请求的合法性。在没有接口调用时，token的有效期为30分钟，之后客户端再调用接口时必须重新进行身份认证，获取新的token。为了确保一定的安全性，客户端应妥善保存token值。

1.7.URL编码

当URL请求参数值中包含URL地址保留字符时，应对参数值进行URL编码。具体参见“RFC2396: Uniform Resource Identifiers (URI): Generic Syntax”。当请求参数包含中文字符时，应对中文字符采用UTF-8编码。

1.8.描述约定

本文档在描述接口的URL地址时，如果没有特殊说明，会省略掉URL前面的相同部分，从接口的分组位置开始描述。例如，http://ip/mserver/interface/appMgr/?request=get 简化为 appMgr/?request=get。在描述参数时，省略token参数的描述，在示例中也会省略。在实际调用中必须把token参数加上。在对参数进行描述时，用【必选】表示该参数必须提供，用【可选】表示该参数可以省略，用【URL编码】表示该参数需要进行URL编码，【保留】表示该参数可以接受但尚未被使用。

1.9.返回消息结构

返回的json消息数据结构具有严格的一致性，客户端可以采用一致的接收和解析方式处理返回消息。 简单消息 简单的返回消息包含对请求的处理结果，结构如下：

代码语言：javascript复制

{
    "code":0,
    "err_desc":""
}

其中： code 为 0 表示处理成功，其它值表示处理失败。 err_desc是对错误的描述，在code为0时err_desc会被省略。特殊情况，在用户认证的login1和login2接口中，err_desc具有特殊用途用法，具体参见接口描述。除这两个接口之外，err_desc都表示错误描述。

带业务数据的消息 有的返回消息除了包含处理结果信息，还包含业务数据记录集，结构如下：

代码语言：javascript复制

 {
        "code":0,
        "data":{
            "count":1,
            "items":[{
            "server":"g3",
            "host":"127.0.0.1",
            "protocol":"rtmp",
            "app":"liveshow",
            "stream":"jgdy"
            }]
        }            
    }

其中： data 业务数据的根节点： count 业务数据的条数，可能的值为0 ~ n items 业务数据，是一个数组，数据条数由count属性定义。当count为0时，items属性可能为null或者不存在。本文档后续章节中，在描述items元素的属性时，会省略一些属性的描述，即实际调用接口返回的属性在本文档中可能会没有描述，这种情况下请直接忽略被忽略描述的属性值。本文档中描述的属性是实际返回内容的一个子集，没有描述到的内容对集成本系统没有影响。

带分页数据的消息 如果返回数据较多，服务器会对返回的数据进行分页，客户端可以按照页码请求指定范围的数据。带分页信息的返回数据结构如下：

代码语言：javascript复制

    {
    "code":0,
    "data":{
        "page":1,
        "page_size":"20",
        "pages":"1",
        "total":"2",
        "count":2,
        "items":[...]
                }
}

分页数据信息在data元素下，意义如下： page 当前页码 page_size 每页数据记录条数 pages 总共的页数 total 总数据条数 count 当前返回页的数据条数如果返回的数据带有分页信息，则可以在调用接口时使用page参数来请求指定页码的数据。

1.10.参考

[1] RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1[S]. [2] RFC 3986, Uniform Resource Identifier (URI): Generic Syntax[S]. [3] http://www.json.org/ Introducing JSON

2.登录认证

客户端调用流媒体服务器接口，首先要做的是身份认证，认证通过后才可以调用流媒体服务器的接口。服务器和客户端通过“挑战->应答”方式（challenge-response）进行身份认证交互，在这个过程中，客户端需要调用两次接口向服务器证明身份。认证过程中不需要传递密码，密码用于签名验证。身份认证的过如下： 1客户端使用“用户名”作为参数调用“login1”接口，向服务器发出身份认证请求 1.1）服务器确认用户是否是有效的用户： 1.2）若不是，则不做进一步处理，返回错误信息 1.3）若是，服务器产生一个“随机数（挑战字符串）”发送给客户端 2客户端使用“用户密码”和“随机数（挑战字符串）”作为输入，按约定的算法生成一个hash值，用该hash值作为调用“login2”接口的参数，请求login2接口。 2.1）服务器用收到的hash值与自己的计算结果比较，若二者相同，则通过认证；否则，认证失败 2.2）若认证通过，服务器返回“token”给客户端，否者返回错误信息。

2.1.login1接口

用途客户端向服务器申请进行身份认证，服务器返回“挑战字符串”给客户端。
请求 userAuth/?request=login1&username=admin username 登录服务器的用户名。
响应 { "code":0, "err_desc":"auha3gik9m48l1mh" } code 等于0，表示用户有效，此时 err_desc 的内容是返回的挑战字符串（challenge_code）。 code 不等于0，其他值表示错误，此时 err_desc 的内容是错误描述。返回的挑战字符（challenge_code）串用于下一步认证。

2.2.login2接口

用途对login1接口返回“挑战字符串”进行hash运算，将运算结果提交给服务器，进行身份合法性认证。
请求 userAuth/?request=login2&username=admin&hash=8c96202be3da1b23a96c4c838eb34d93 username 登录服务器的用户名。 hash是使用用户密码和挑战字符串作为输入计算出的md5摘要值(hash)，算法如下： hash=md5(md5(password) challenge_code) 算法描述：首先计算出密码的hash值，然后在生成的密码hash值尾部拼接上挑战字符串形成新的字符串，最后计算这个新字符串的hash值。 hash算法采用md5算法，生成的摘要采用16进制编码，编码生成的字符采用小写字母。例如，字符串111111的hash值是 96e79218965eb72c92a549dd5a330112
响应 { "code":0, "err_desc":"g2ow17rfyf4nxbkg" } code 0 表示登录成功，此时 err_desc 的内容是token值，用于后续接口的通信认证。 code >0 其他值表示错误，此时 err_desc 的内容是错误描述。

2.3.logout接口

用途退出登录，服务器销毁用户登录信息，作废“token”。建议客户端在退出系统时总是调用该接口。
请求 userAuth/?request=logout&token=vvkphp5ca79c538n
响应 { "code":0, }

3.application管理接口

3.1.查询应用接口

用途查询服务器上的应用（application）。
请求 appMgr/?request=get&token=abce token 是在登录认证接口中获得的token值。后续接口描述中将省略对token参数的描述，但是要记住token参数是必须的。
响应 { "code":0, "data":{ "count":2, "items":[{"app_name":"show3", "allow_live":"on", "allow_publish":"on", "allow_play":"on" }, {"app_name":"show4", "allow_live":"on", "allow_publish":"on", "allow_play":"on"} ]} } 返回一个或多个应用的信息。 app_name 应用名 allow_live 是否允许直播业务，on表示允许，off或省略不允许 allow_publish 是否允许推送直播流到该应用，on表示允许，off或省略不允许 allow_play 是否允许播出视频，on表示允许，off或省略不允许

3.2.查询DVR配置接口

用途查询应用的DVR配置参数。流媒体服务器的DVR功能可以将直播流在服务器上进行录制保存，DVR配置参数定义了保存的行为。系统有全局DVR配置参数，默认情况下会对每个应用生效。如果一个应用（application）没有DVR配置参数，则会使用全局配置参数。如果对一个应用配置了部分DVR参数，没有配置的参数依然会使用全局配置参数。
请求 appMgr/?request=get_dvr_paras&application= application 应用名，如果没有指定应用名，则会查询全局配置参数。
响应

代码语言：javascript复制

{
    "code":0,
    "data":{
        "count":1,
        "items":[
            {
                "is_dvr":"on",
                "dvr_method":"METHOD_A",
                "version_it":"on",
                "media_root":"/var/www/media",
                "keep_time":"0",
                "analyze_duration":"15",
                "segment_duration":"10",
                "chunk_type":"h",
                "chunk_size":"1",
                "chunk_ts":"off",
                "formats":"flv;hls",
                "probe_time":"20",
                "tv_streams":"tv",
                "application":"__Default"
            }
        ]
    }
}

返回应用的配置参数，items数组包含一个元素。配置参数： is_dvr on 表示DVR开启，off表示关闭。 media_root 归档数据保存的根路径 formats 归档的格式，多种格式用半角分号分开。flv 保存flv格式；hls保存hls切片格式；mp4保存mp4格式。 tv_streams 按照电视流格式归档的流名称，多个名称用半角分号分开。 application 应用名，"Default" 表示使用的是全局配置。

3.3.开启DVR功能

用途开启DVR功能。 系统暂不支持针对某个应用开启和关闭DVR功能，也不支持针对某个应用配置其他DVR参数。DVR的开启、关闭和修改配置参数会对所有应用生效。
请求 appMgr/?request=open_dvr
响应 { "code":0 }

3.4.关闭DVR功能

用途关闭DVR功能。
请求 appMgr/?request=close_dvr
响应 { "code":0 }

3.5.设置DVR保存格式

用途设置DVR保存格式，可以设置直播流在流媒体服务器上以一种或多种格式保存。
请求 appMgr/?request=set_dvr_format&formats=flv;hls;mp4 format 设置的归档格式，多种格式用半角分号分开。flv 保存flv格式；hls保存hls切片格式；mp4保存mp4格式。
响应 { "code":0 }

4.直播流相关接口

4.1.查询活动的视频流

用途查询活动的视频流，即正在直播中的视频流。
请求 streamMgr/?request=get_active_streams
响应 { "code":0, "data":{ "count":1, "items":[ { "server":"g3", "host":"192.168.1.230", "protocol":"rtmp", "app":"live", "stream":"live2", "uid":"23000043", "end":"end", "starttime":1516242339 } ] } } items数组可能包含0或多个元素。 server 服务器类型，默认是g3 host 服务器IP地址或域名 protocol 直播协议，rtmp或rtsp app 应用名 stream 流名称 starttime 开始直播的时间，是一个unix时间戳

4.2.关闭并禁用直播流

用途关闭一个直播流，并将该直播流设为禁用状态。调用该接口后，直播流会被立即关闭，直播客户端和播放客户端的连接都会中断。关闭后的直播流会被禁止再次推流，除非调用后续接口解除禁用。
请求 closedStream/?request=close&application=live&stream=live2 application 应用名 stream 直播流名称
响应 { "code":0 }

4.3.解除禁用的直播流

用途解除在上一接口中被关闭和禁用的直播流，解除后直播流可以允许推流直播。
请求 closedStream/?request=open&application=live&stream=live2 application 应用名 stream 直播流名称
响应 { "code":0 }

4.4.查询被禁用的直播流

用途查询被关闭并被禁用的直播流。
请求 closedStream/?request=list
响应

代码语言：javascript复制

{
    "code":0,
    "data":{
        "count":1,
        "items":[
            {
                "application":"liveshow",
                "stream":"live1",
                "time":1516274119
            }
        ]
    }
}

items元素下包含被禁用的直播流列表。 application 应用名 stream 直播流名称 time 禁用时间，unix时间戳

4.5.关闭直播流（不禁用）

用途关闭一个直播流，但是不禁用，推流客户端可以再次推流进来。调用该接口后，直播流会被立即关闭，直播客户端和播放客户端的连接都会中断。
请求 streamMgr/?request=close_active_stream&application=live&stream=live2 application 应用名 stream 直播流名称

响应

代码语言：javascript复制

{
    "code":0
}

5.点播流相关接口

5.1.查询点播流

用途查询某个应用下的点播视频流。如果查询的是点播应用（如"vod"），返回的是该点播应用下的点播流列表。如果查询的是直播应用（如“liveshow”），则会返回的是有录制数据的历史直播流的列表，列表中的时长、修改时间、生成时间属性都是针对该流最后一个录制版本的描述。可以通过下一个接口查询某个直播流下的详细录制数据。
请求 streamMgr/?request=get_streams&application=vod&pageno=1&page_size=20 application 应用名 pageno 页码 page_size 分页大小，【保留】，该参数暂不支持传入，分页大小由服务器根据数据量自动分页。在视频流较多的情况下，可以通过传入页码参数请求某一范围内的数据。返回的数据中含有详细的分页信息，可以通过请求第一页获取数据总量和分页的详情。本文档的后续章节将不再对分页属性做解释。
响应 { "code":0, "data":{ "page":1, "page_size":"20", "pages":"2", "total":"28", "modify_time":"1515731044", "count":20, "items":[ { "seq":1, "application":"vod", "stream":"fk7cpizvhwshjnyu", "type":"movie", "starttime":"1515155078", "modifytime":"1515155078", "active":"no", "duration":"10", "formats":"flv,hls,mp4" }, { "seq":2, "application":"vod", "stream":"VID20160916153947", "type":"movie", "starttime":"1515154953", "modifytime":"1515154953", "active":"no", "duration":"36", "formats":",,mp4" } ] } } 返回应用下的点播流。 data元素下包含数据量和分页信息： page 当前页码 pages 总页数 page_size 分页大小 total 总数据条数 count 当前分页中的数据条数 items元素下包含0或多条点播数据流，每条记录的属性如下： application 应用名 stream 流名称 type 点播流类型,movie表示是视频点播流，live表示是直播流（由直播流形成的归档数据）。 modifytime 最后修改的时间戳 "starttime 开始生成的时间戳，对于movie类型的流，表示转码生成的时间，对于live类型的流表示录制的时间。 duration 视频流的播出时长，单位秒 formats 视频流的格式，一个视频流可以有多种格式，多种格式之间使用逗号分开，可以是flv、hls、mp4格式中的一种或多种。

5.2.查询直播流录制数据

用途查询某个直播流的录制数据，录制数据也是一种点播流，是录制直播流形成的点播数据。一个直播流每次启停都会生一份录制数据，多次启停后会在一个直播流下生成多份录制数据。直播流的录制数据使用版本号区分，版本号从0开始，每生成一个新文件版本号会增1。
请求 streamMgr/?request=get_stream_files&application=liveshow&stream=jgdy&pageno=1&page_size=20 application 应用名 stream 直播流名称 pageno 页码 page_size 分页大小
响应 { "code":0, "data":{ "page":1, "page_size":"20", "pages":"1", "total":"2", "modify_time":"1515755949", "count":2, "items":[ { "version":"1", "size":"28759864", "duration":"353", "starttime":"1515655308", "modifytime":"1515655659", "formats":"hls" }, { "version":"0", "size":"121345164", "duration":"1209", "starttime":"1515218380", "modifytime":"1515219588", "formats":"hls" } ] } } 返回某个直播流的录制数据。 items元素下包含0或多条录制数据，每条数据的属性如下： version 版本号 size 录制数据大小，单位字节 duration 视频流的播出时长，单位秒 modifytime 最后修改的时间戳，可以理解成录制结束的时间戳 "starttime 开始录制的时间戳。 formats 视频流的格式，一个视频流可以有多种格式，多种格式之间使用逗号分开，可以是flv、hls、mp4格式中的一种或多种。

5.3.删除视频流

用途删除一个视频流。如果请求删除的是一个视频点播流名称（如"vod"应用下的某个流），会把这个点播流下的视频数据删除掉。如果请求的是一个直播流名称，则会把这个直播流下的所有版本的录制数据删除。要删除直播流的某个版本的录制数据，使用下一个接口（删除录制数据）。
请求 streamMgr/?request=remove_stream&application=vod&stream=fk7cpizvhwshjnyu application 应用名 stream 流名称
响应 { "code":0 }

5.4.删除录制数据

用途删除某个直播流的某个版本的录制数据。要删除所有版本的录制数据，请使用上一接口（删除视频流）；
请求 streamMgr/?request=remove_stream_version&application=liveshow&stream=yellow&version=31 application 应用名 stream 流名称 version 录制版本号
响应 { "code":0 }

6.查看在线用户

6.1.查询在线用户

用途查询当前时间在线的用户数量，返回每个视频流观看用户的总数。请求 statMgr/?request=connection_count
响应 { "code":0, "data":{ "count":1, "items":[ { "application":"live", "stream":"live2", "ver":"", "count":1 } ] } } 返回当前时间视频流的收看用户数。 application 应用名 stream 流名称 ver 版本号，如果是收看的直播回看数据，会返回版本号 count 用户数量

6.2.查询在线用户明细

用途查询当前时间正在播放某个视频流的用户明细，包括用户的终端IP和使用的播放协议。
请求 statMgr/?request=connection_detail&application=live&stream=live2&version= application 应用名 stream 流名称 version 版本号，如果要查看收看某个直播回看流的用户数，需要提供版本号参数
响应 { "code":0, "data":{ "count":1, "items":[ { "cip":"192.168.1.88", "sip":"192.168.1.230:1935", "uid":"D48423AB19931A0A", "sid":"D48423AB19931A0A", "ver":"-1", "format":"rtmp", "type":"live", "reg_time":"1516261938", "start":"-1", "offset":"-1" } ] } } 返回在线用户的明细数据。items元素下会包含0或多条记录。 cip 客户端ip sip 服务器ip uid 用户唯一识别id，可以有应用系统带入 sid 每次访问的唯一识别id ver 访问的哪个版本，对于视频点播流没有意义，对于回看流表示录制版本号 reg_time 开始收看的时间，unix时间戳 start 从视频的第几秒开始收看，-1表示从视频开头处收看。单位秒 offset 观看到了第几秒，该参数在用户收看hls和flv格式视频时有效。-1表示不支持或无法获取该参数。

7 按需录制直播流

7.1.定义按需录制的应用

用途将某个应用设置为按需录制应用。应用被设置为按需录制后，该应用下的直播流默认情况下不会被录制，只有在收到开始录制和停止录制的指令后才会针对某个直播流开始录制和停止录制。如果系统的全局配置参数中设置了不录制视频，直播流不会被录制。具体参见“application相关接口”章节中的DVR相关接口。按需录制的接口，对于live应用“live-”开头的应用无效。对于带有NR符号的应用和直播流也无效。
请求 demandDvr/?request=add_app&application=show application 应用名
响应 { "code":0 }

7.2.撤销按需录制的应用

用途撤销某个应用的按需录制配置。即如果通过上一接口将某个应用设置为按需录制应用，可以通过本接口撤销这种设置。
请求 demandDvr/?request=del_app&application=show application 应用名
响应

代码语言：javascript复制

{
    "code":0
}

7.3.查询按需录制的应用

用途查询所有被设置为按需录制的应用。
请求 demandDvr/?request=list_app
响应 { "code":0, "data":{ "count":2, "items":[ { "application":"show1", "time":1516264587 }, { "application":"liveshow", "time":1515742304 } ] } } 返回消息的items元素包含0或多条记录。 application 应用名 time 添加时间，unix时间戳

7.4.开始录制

用途对按需录制应用下的直播流，发送开始录制指令。服务器收到指令后会开始录制该直播流。如果该直播流当前时间正在直播，服务器收到指令后会立即开始录制，直到收到停止录制指令后才会停止录制。如果该直播流当前时间没有正在直播，服务器收到该指令后会保持录制状态，一旦该直播流开始直播就会开始录制。
请求 demandDvr/?request=start&application=liveshow&stream=live1 application 应用名 stream 直播流名称
响应 { "code":0 }

7.5.停止录制

用途对按需录制应用下的直播流，发送停止录制指令。服务器收到指令后会停止录制该直播流。
请求 demandDvr/?request=stop&application=liveshow&stream=live1 application 应用名 stream 直播流名称
响应 { "code":0 }

7.6.查看正在录制的流

用途对按需录制应用下的直播流，发送停止录制指令。服务器收到指令后会停止录制该直播流。
请求 demandDvr/?request=list&application=show application 应用名，如果省略，表示查询所有应用下正在录制的流。
响应

代码语言：javascript复制

        {
                "code":0,
                "data":{
                        "count":2,
                        "items":{
                                "show5-112233":{
                                        "application":"show5",
                                        "stream":"112233",
                                },
                                "liveshow-live1":{
                                        "application":"liveshow",
                                        "stream":"live1",
                                }
                        }
                }
        }

items包含多个正在录制流的列表。 application 应用 stream 流

8 播出认证相关接口

8.1.开启播出认证

用途针对某个应用，开启播出认证。开启播出认证后，所有播放该应用下的视频流的请求都需要做合法性认证，只有认证通过的请求才会允许播放。认证的方法包括token认证、referer认证和第三方认证。 token认证，就是为每个播出流配置一个认证码(token)，播放终端只有获得该认证码，并将该认证码作为播出请求的参数提交，才能够正常播放视频。 referer认证，就是要求播放终端必须从某个域名下的网站发起播放请求，也就是只有将播出视频嵌入到某个指定域名下的网站才允许播放。第三方认证，就是将认证请求转交给第三方系统的服务接口去认证，认证通过后才允许播放。开启第三方认证后，所有本地认证策略会被忽略。
请求 authMgr/?request=open_play_auth&application=liveshow application 应用名
响应 { "code":0 }

8.2.关闭播出认证

用途针对某个应用，关闭播出认证。关闭后播放该应用下的视频流不需要做认证。
请求 authMgr/?request=close_play_auth&application=liveshow application 应用名
响应 { "code":0 }

8.3.开启和关闭播出token认证

用途针对某个应用，开启和关闭播出token认证方式。设置该参数是为了迎合仅使用referer认证情况。
请求 authMgr/?request=open_play_token&application=liveshow&open=1 application 应用名 open 是否开启认证，open=1表示开启认证，open=0表示关闭认证
响应 { "code":0 }

8.4.查询播出token

用途查询某个应用下播出认证token的列表。每个token设置到一个视频流上，播放客户端访问该视频流需要给出正确的token值。
请求 authMgr/?request=list_play_token&application=liveshow application 应用名
响应 { "code":0, "data":{ "count":1, "items":[ { "application":"liveshow", "stream":"live1", "token":"8501E93883FC4D14", "use_once":0 } ] } } items元素包含当前应用下的token定义。 application 应用名 stream 流名称 token token值

8.5.添加播出token

用途为视频流添加播出认证token。每个token设置到一个视频流上，播放客户端访问该视频流需要给出正确的token值。
请求 authMgr/?request=add_play_token&application=liveshow&stream=live1&token_val=8501E93883FC4D14 application 应用名 stream 流名称 token_val 添加的token值（注意这里使用token_val参数名，避免与接口认证的token参数冲突）
响应 { "code":0 }

8.6.删除播出token

用途删除某个视频流的token。
请求 authMgr/?request=delete_play_token&application=liveshow&stream=live1 application 应用名 stream 流名称
响应 { "code":0 }

8.7.设置播出认证的referer值

用途为某个应用设置播出认证referer值。
请求 authMgr/?request=set_referer&application=liveshow&url=play.ruiboyun.net;cloud.ruiboyun.net application 应用名 url 允许访问的域名列表，多个域名之间使用半角分号隔开。如果要撤销referer认证，将url设为空即可。
响应 { "code":0 }

8.8.设置第三方播出认证地址

用途将某个应用下的播出认证地址设置为一个第三方认证地址。设置第三方认证地址后，所有本地认证策略失效。如果要取消第三方认证，将url参数设置为空即可。
请求 authMgr/?request=set_play_auth_url&application=liveshow&url=http://i.ruiboyun.net/interface application 应用名 url 第三方认证接口的url地址，本参数需要进行【URL编码】。
响应 { "code":0 }

8.9.查询播出和推流认证配置

用途查询服务器上播出和推流认证的配置情况。本接口会返回所有应用的认证配置信息，包括推流认证和播放认证的配置信息。
请求 authMgr/?request=list
响应 { "code":0, "data":{ "count":1, "items":[ { "application":"liveshow", "is_play_auth":0, "is_pub_auth":1, "play_auth_url":null, "pub_auth_url":"", "referer":null, "is_play_token_auth":0 } ] } }

items应用下会返回多条记录，每条记录定义个应用的认证配置。 application 应用名 is_play_auth 是否开启播放认证，0关闭，1开启 is_pub_auth 是否开启推流认证，0关闭，1开启 pub_auth_url 推流第三方认证地址，null，"local"，""，或省略，都表示不使用第三方认证 play_auth_url 播出第三方认证地址，null，"local"，""，或省略，都表示不使用第三方认证 referfer 允许播出的域名列表，多个域名之间使用半角分号隔开，该项仅对播出认证有效 is_play_token_auth 是否开启播出的token认证，0关闭，1开启，使用该选项是为了配合只使用referer认证的情况，该项仅对播出认证有效

9 推流认证相关接口

9.1.开启推流认证

用途针对某个应用，开启推流认证。开启推流认证后，所有向该应用下的推送直播流的请求都需要做合法性认证，只有认证通过的请求才会允许推送。认证的方法包括token认证和第三方认证。 token认证，就是为每个直播流配置一个认证码(token)，推流终端只有获得该认证码，并将该认证码作为推流请求的参数提交，才能够正常推送直播流。第三方认证，就是将认证请求转交给第三方系统的服务接口去认证，认证通过后才允许推送直播流。开启第三方认证后，所有本地认证策略会被忽略。
请求 authMgr/?request=open_pub_auth&application=liveshow application 应用名
响应 { "code":0 }

9.2.关闭推流认证

用途针对某个应用，关闭推流认证。关闭后向该应用推送视频流不需要做认证。
请求 authMgr/?request=close_pub_auth&application=liveshow application 应用名
响应 { "code":0 }

9.3.查询推流token

用途查询某个应用下推流认证token的列表。
请求 authMgr/?request=list_pub_token&application=liveshow application 应用名
响应 { "code":0, "data":{ "count":1, "items":[ { "application":"liveshow", "stream":"live1", "token":"9501E93993FC4D14", "use_once":0 } ] } } items元素包含当前应用下的token定义。 application 应用名 stream 流名称 token token值

9.4.添加推流token

用途为视频流添加推流认证token。
请求 authMgr/?request=add_pub_token&application=liveshow&stream=live1&token_val=9501E93993FC4D14 application 应用名 stream 流名称 token_val 添加的token值（注意这里使用token_val参数名，避免与接口认证的token参数冲突）
响应 { "code":0 }

9.5.删除推流token

用途删除某个视频流的推流认证token。
请求 authMgr/?request=delete_pub_token&application=liveshow&stream=live1 application 应用名 stream 流名称
响应 { "code":0 }

9.6.设置第三方推流认证地址

用途将某个应用下的推流认证地址设置为一个第三方认证地址。设置第三方认证地址后，所有本地认证策略失效。如果要取消第三方认证，将url参数设置为空即可。
请求 authMgr/?request=set_pub_auth_url&application=liveshow&url=http://i.ruiboyun.net/interface application 应用名 url 第三方认证接口的url地址，本参数需要进行【URL编码】。
响应 { "code":0 }

10 并发限制相关接口

10.1.查询并发限制配置

用途查询某个应用的播出并发限制值。如果一个应用设置了并发限制值，当访问该应用下视频流的并发数超过该值时，终端的播出请求会被禁止。这个限制值是该应用下所有视频流的播出并发数总和限制值。
请求 limitMgr/?request=get&application=liveshow application 应用名，可以省略，省略时会返回所有应用的配置信息。
响应 { "code":0, "data":{ "count":1, "items":[ { "application":"liveshow", "limit":100 } ] } } application 应用名 limit 限制值

10.2.设置并发限制值

用途设置某个应用的播出并发限制值。如果要取消限制，将limit参数设为0。
请求 limitMgr/?request=set&application=liveshow&limit=100 application 应用名 limit 限制值，该值有一个允许范围，具体与服务器的发布版本有关
响应 { "code":0 } application 应用名 limit 限制值

11 串流相关接口

11.1.查询串流任务

用途查询服务器上的串流任务。
请求 streamingMgr/?request=get_streaming&id= id 串流任务在服务器上的唯一编号，省略时会返回所有任务的列表。
响应 { "code":0, "data":{ "count":2, "items":[ { "name":"监控视频", "id":"BAF9B8E5BA819259", "protocol":"rtsp", "source_url":"rtsp://192.168.2.246:8555/H264SubStream", "video_only":"on", "use_transcode":"on", "video_size":"1280x720", "width":"1280", "height":"720", "bitrate":"500", "use_audio_transcode":"on", "bitrate_audio":"56", "to_host":"localhost", "application":"show", "stream":"cameral1", "status":0 }, { "name":"本地文件串流", "id":"D16E78096B55C850", "protocol":"file", "source_url":"file:///var/media/jgdy.mp4", "to_host":"localhost", "application":"liveshow", "stream":"jgdy", "status":0 } ] } } items元素包含0个或多个串流任务。 name 串流的名称，在添加任务时输入 id 串流的唯一编号，在添加任务时系统自动分配，后续管理串流任务需要该id protocol 输入协议 source_url 视频源地址 video_only 输入源是否只有视频，on表示只有视频 audio_only 输入源是否只有音频，on表示只有音频 use_transcode 是否启动视频转码，on表示启动，off或者省略表示没有转码 width 转码的输出视频画面宽度，0表示保持输入源画幅大小 height 转码的输出视频画面高度，0表示保持输入源画幅大小 bitrate 视频转码的比特率，单位 kbps use_audio_transcode 是否启动音频转码，on表示启动，off或者省略表示没有转码 bitrate_audio 音频转码比特率单位 kbps to_host 串流的目标服务器，省略或localhost都表示要串流到本服务器。如果要串流的其他服务器，该值为“other”，并使用参数to_server指示要串流的目标服务器IP或域名。 to_server要串流其他服务器的IP或域名。 application 串流的目标应用名 stream 串流的目标直播流名称 status 串流任务状态 0没有运行 1正在运行其他表示异常

11.2.添加串流任务

用途添加一个串流任务。添加串流任务时，要调用接口的客户端提供一个唯一的任务id，该id可由字母和数字组成，用于在调用后续接口时识别该任务。如果提供的id和已经存在任务的id相同，则服务器会将该请求当作修改串流任务处理。
请求 streamingMgr/?request=add_streaming&name=监控视频&id=BAF9B8E5BA819259&protocol=rtsp&source_url=rtsp://192.168.2.246:8555/H264SubStream&video_only=on&use_transcode=on&video_size=1280x720&width=1280&height=720&bitrate=500&use_audio_transcode=on&bitrate_audio=56&to_host=localhost&application=show&stream=cameral1 参数： id 任务唯一编号，应由字母或数字组成，长度建议在6个字符以上，要避免重复 protocol 串流输入源的协议，支持rtsp、rtmp、udp、http、mms等协议 source_url 串流输入的源地址，该参数需要进行【url编码】 video_only 是否只有视频，on 表示只有视频，在只有视频时，所有音频相关参数会被忽略 use_transcode 是否进行视频转码，on表示进行转码，off或者省略表示不转码。如果不进行视频转码，所有视频转码参数会被忽略 width 视频转码输出的画面宽度，单位像素 height 视频转码输出的画面高度，单位像素 bitrate 视频转码输出的比特率，单位kpbs use_audio_transcode 是否进行音频转码，on表示进行转码，off或者省略表示不转码。如果不进行音频转码，所有音频转码参数会被忽略。 bitrate_audio 音频转码比特率，单位kbps to_host 串流的目标服务器，省略或localhost都表示要串流到本服务器。如果要串流的其他服务器，该值为“other”，并使用参数to_server指示要串流的目标服务器IP或域名。 to_server要串流其他服务器的IP或域名，要是本参数生效，必须将to_host值设为other。 application 串流输出的应用名，定义向服务器的哪个应用输出直播流 stream 串流输出的直播流名称
响应 { "code":0 }

11.3.启动串流任务

用途启动一个串流任务。添加完串流任务后，可以调用该接口运行任务。
请求 streamingMgr/?request=start_streaming&id=BAF9B8E5BA819259 id 串流任务的唯一编号，可以通过查询串流任务接口获得。
响应 { "code":0 }

11.4.停止串流任务

用途停止一个串流任务。
请求 streamingMgr/?request=stop_streaming&id=8A9B587159245ED5 id 串流任务的唯一编号，可以通过查询串流任务接口获得。
响应 { "code":0 }

11.5.删除串流任务

用途删除一个串流任务。
请求 streamingMgr/?request=remove_streaming&id=8A9B587159245ED5 id 串流任务的唯一编号，可以通过查询串流任务接口获得。
响应 { "code":0 }

12 自动删除相关接口

12.1.查询自动删除任务

用途查询服务器上的自动删除任务。自动删除任务是一种运行在服务器上的服务，按照定义的规则自动删除过期的视频内容。例如，对于监控和视频直播类业务，可以定义一个任务，定期删除某个直播流30天前的录制内容。
请求 autodelMgr/?request=get&application=&stream= application 应用名，可以省略，省略时表示查询所有应用下的自动删除任务。 stream 直播流名，可以省略，省略时表示查询某个应用下的所有自动删除任务。
响应 { "code":0, "data":{ "count":1, "items":[ { "application":"liveshow", "stream":"hks", "timeline":"3600" } ] } } application 应用名 stream 直播流名 timeline 视频保留的时间长度，单位秒，例如，3600表示保存1小时内的节目

12.2.新建自动删除任务

用途新建一个自动删除任务。
请求 autodelMgr/?request=set&application=liveshow&stream=live1&timeline=86400 application 应用名，【必选】 stream 直播流名，【必选】 timeline 视频保留的时间长度，单位秒，【必选】，例如，86400表示保存1天内的节目如果应用名和直播流名和已有任务的都一样，则会覆盖已有的任务。
响应

代码语言：javascript复制

{
    "code":0
}

12.3.删除自动删除任务

用途删除一个自动删除任务。
请求 autodelMgr/?request=remove&application=liveshow&stream=live1 application 应用名，【必选】 stream 直播流名，【必选】
响应

代码语言：javascript复制

{
    "code":0
}

13 文件上传及管理相关接口

这组接口实现视频资源的上传及管理，为视频转码和发布提供支持。上传的服务器上的视频文件，经过转码发布后形成可以对外播出的在线视频资源。本小节描述文件上传和管理的接口，转码接口在下一章节说明。

13.1.文件上传接口

用途通过HTTP POST协议上传视频文件。文件上传接口是一个特殊的接口，接口位置与其他接口有差异。上传协议采用HTTP POST协议，提交form的数据采用multipart/form-data编码（enctype="multipart/form-data"）。这里有详细的规范（对于Web开发，通常您无需阅读这个文档）： rfc1867 http://www.ietf.org/rfc/rfc1867.txt 对于采用Web页面上传的应用，采用典型的form提交上传文件即可，数据提交地址设为本接口地址。
请求 http://host/upload?app=g3_video&sub_path=&file_name=&token=abcd&field_name=field_abcd 其中: http://host/upload 是上传位置，保持不变。host替换成实际的流媒体服务器IP地址或域名。参数： app=g3_video,表示上传的是视频文件，要保持不变。 sub_path表示上传到哪个子目录下，如果省略表示上传到用户根目录下。 file_name上传文件要在服务器上保存的文件名，如果跟上传文件名一样，则省略。该参数提供了一个上传文件在服务器上重新命名的机会。中文件名要采用UTF-8编码。 token意义跟其他接口一样。
响应 { "code":0 }

13.2.查询文件列表接口

用途查询服务器上的某个目录下的视频文件列表。
请求 fileMgr/?request=list_files&subpath=&page=1 sub_path 文件存放的子目录，对应上传文件时的sub_path参数。如果省略，则查询用户根目录下的文件。 page页码，该接口支持分页查询，分页信息在返回数据中。
响应 { "code":0, "data":{ "page":"1", "page_size":"50", "pages":"1", "total":"1", "count":1, "items":[{ "filename":"案例视频8.mp4", "mtime":"2018-01-12 12:43", "size":"3153954", "charset":"UTF-8", "timestamp":1515732410, "is_media":1, "duration":98, "bitrate":255309, "stream_number":2, "timestamp_m":1515397208, "streams":[ { "index":"0", "type":"video", "codec":"h264", "pic_width":640, "pic_height":352, "bitrate":208980, "duration":98, "pix_fmt":"yuv420p", "frame_rate":"28/1" }, { "index":"1", "type":"audio", "codec":"aac", "lan":"und", "channels":1, "bitrate":43970, "duration":98, "sample_rate":44100 } ] }] } } 返回数据包含分页信息，在文件量较大时要按页查询。 items元素包含0或多个文件信息。streams元素是该文件包含的音视频流信息，一个多媒体文件会包含1到多个音视频流 filename 文件名，返回的文件名总是采用UTF-8编码 charset 文件名在服务器上的字符集编码，省略表示是UTF-8编码。如果为非UTF-8编码，在后续的接口中请将该属性带入 mtime 文件最后的修改时间 size 文件大小，单位字节 duration 文件播出时长，单位秒 bitrate 综合码率，单位bps stream_number 文件包含的音视频流总数 streams元素： streams包含0或多个音视频流，属性： index 流的索引编号，在转码接口中，在多语言音频流的情况下，可以通过传入音频流索引号选择指定的音频流。 type 视频或音频，对应 video 或 audio codec 流编码格式，例如视频h264编码，音频aac编码等 bitrate 流的比特率，单位bps pix_fmt 视频帧格式 frame_rate 帧率 pic_width 视频画幅宽度 pic_height 视频画幅高度 lan 音频语言信息，语言编码缩写 channels 音频声道数 sample_rate音频采样率

13.3.查询文件目录接口

用途查询服务器上的文件目录。
请求 fileMgr/?request=list_dirs&subpath= sub_path 文件存放的子目录，如果省略，则查询用户根目录下的文件目录。
响应 { "code":0, "data":{ "count":2, "items":[ { "filename":"auto", "mtime":"2018-01-06 16:36", "size":"4096", "timestamp":0, "auto_transcode":1 }, { "filename":"audio", "mtime":"2017-12-27 18:09", "size":"4096", "timestamp":0, "auto_transcode":0 }] } } items元素包含0或多个目录信息。 filename 目录名 mtime 最后修改时间 auto_transcode 是否针对该目录设置了自动转码任务，1表示有自动转码任务

13.4.查询文件信息接口

用途查询服务器上的某个视频文件的信息。
请求 fileMgr/?request=get_file&filename=案例视频8.mp4&charset=UTF-8 filename 文件名，如果在子目录中，应当包含完整的相对目录，如 mypath/myfile.mp4，文件名采用UTF-8编码 charset 文件名在服务器上的实际字符集编码，在查询文件列表接口中有返回。
响应 { "code":0, "data":{ "count":1, "items":[ { "filename":"/案例视频8.mp4", "charset":"UTF-8", "mtime":1515732213, "size":3153954, "timestamp":1516941450, "is_media":1, "duration":98, "bitrate":255309, "stream_number":2, "timestamp_m":1515397208, "streams":[ { "index":"0", "type":"video", "codec":"h264", "pic_width":640, "pic_height":352, "bitrate":208980, "duration":98, "pix_fmt":"yuv420p", "frame_rate":"28/1" }, { "index":"1", "type":"audio", "codec":"aac", "lan":"und", "channels":1, "bitrate":43970, "duration":98, "sample_rate":44100 } ] } ] } } 返回一个文件的信息，包含多媒体信息。返回数据的文件信息的描述与查询文件列表接口中对文件信息的描述相同。

13.5.删除文件接口

用途删除服务器上的文件。
请求 fileMgr/?request=remove&filename=myvideo.mp4&charset=ASCII filename 文件名，如果在子目录中，应当包含完整的相对目录，如 mypath/myfile.mp4，文件名采用UTF-8编码 charset 文件名在服务器上的实际字符集编码，在查询文件列表接口中有返回。
响应 { "code":0 }

14 转码相关接口

14.1.转码接口

用途对上传到服务器上的视频进行转码，转码后可以面向互联网或局域网发布播出。
请求 transcodeMgr/?request=transcode&application=vod&src=案例视频8.mp4&src_id=video89&video_bitrate=800&audio_bitrate=60&width=0&height=0&deinterlace=OFF&encoding=UTF-8&audio_stream=&output_formats=hls;flv;mp4&publish=&title=

参数说明： src 输入文件名，如果文件在转码目录的下级子目录内，则需要包含该子目录，如： subdir/myvideo.mp4。中文文件名参数使用UTF-8字符集编码。 encoding 输入文件名在服务器上的实际字符集编码。如果是UTF-8可以省略。 src_id 转码后输出资源的资源编号，由转码方提供（可以和集成的业务系统关联对应）,只能包含英文字符和数字，要确保其唯一性。这个编号就是资源在流媒体服务器上的播出流名称，可以使用该编号获取播出视频流。 application 应用名，定义转码结束后资源发布到流媒体服务器上的哪个应用下。该应用名和流名称（对应src_id）可以确定一个资源的播出地址。 video_bitrate 视频转码的比特率，单位Kbps，如果省略表示不对视频进行转码。只有视频格式是H264，并且码率大小适合播出（如在2Mbps以下），才可以省略该参数。 audio_bitrate 音频转码的比特率，单位Kbps，如果省略表示不对音频进行转码。只有音频格式是AAC，并且码率大小适合播出（如在100Kbps以下），才可以省略该参数。 width 视频转码输出的画面宽度，省略或者设为0表示不改变画幅，使用原始视频的画幅大小。 height 视频转码输出的画面高度，省略或者设为0表示不改变画幅，使用原始视频的画幅大小。 deinterlace 对于隔行扫描的视频画面，该参数定义是否进行画面的反交错处理，ON表示要进行反交错，OFF或者省略表示不进行反交错处理。 audio_stream 音频流索引号，对于多语言的多媒体提文件，会包含多个语言的音频流，使用该参数可以选择一种语言输出。不清楚怎么使用时，请省略该参数，大部分情况下不需要提供。 output_formats 转码输出格式，可以是flv,hls,mp4格式的一种或几种，多种格式使用分号隔开。省略该参数时将会使用系统配置的归档格式参数。 callback 可选参数。转码结果回调接口位置，该参数是一个HTTP地址，转码结束后系统使用HTTP Get向该地址汇报转码结果。调用回调接口时，系统会在回调接口URL上附加上资源编号参数src_id和转码结果参数result,result=ok表示转码成功，result=error表示转码失败。 publish 可选参数。如果需要将转码输出的视频信息发布到第三方系统，可以提供发布地址，转码结束后会将视频信息提交给该地址。如果没有该需求，请省略该参数和title参数。 title 如果要进行转码信息发布，可以提供一个发布的标题。

响应 { "code":0 }

14.2.转码进度查询接口

用途查询服务器上正在转码的转码任务的进度，该接口返回所有正在转码任务的列表。
请求 transcodeMgr/?request=list_working
响应 { "code":0, "data":{ "count":1, "items":[ { "status":"working", "src_file":"案例视频8.mp4", "application":"vod", "bitrate":"800", "width":"640", "height":"352", "bitrate_audio":"56", "src_id":"8ass3", "add_time":"1516947498", "from":null, "start_time":"1516947498", "encode_progress":"1.0%", "work_duration":1 } ] } } 返回0或多个转码任务的进度信息。 src_file 转码文件名 application 输出应用名 src_id 资源编号 start_time 开始转码时间，Unix时间戳 encode_progress 转码进度，百分比格式 work_duration 转码持续时间，单位秒 bitrate 视频转码码率，Kbps bitrate_audio 音频转码码率,Kpbs width 转码输出画幅宽度 height 转码输出画幅高度

14.3.停止转码接口

用途停止一个正在转码的任务。
请求 transcodeMgr/?request=stop_transcode&src_id=8ass3 src_id 转码任务的资源编号，由转码接口传入。
响应 { "code":0 }

15 用户管理

管理系统中的管理员帐号。

15.1.添加管理员

请求 userAuth/?request=create_user&name=myname&pwd=123&auth_func=fileMgr,transcodeMgr&auth_app=vod name 登录用户名 pwd 登录用户名 auth_func 允许使用的功能，多个功能使用半角逗号隔开。功能定义见 15.3 auth_app 允许使用的应用，多个应用使用半角逗号隔开。应用定义见 3.1 小节

备注： 如果传入的name在系统中存在同名用户，则会用新的信息替换原有信息，相当于“修改”用户。

响应 { "code":0 }

15.2.删除管理员

暂不支持

15.3.列出系统可用功能

请求 userAuth/?request=functions
响应 { "code": 0, "data": { "count": 17, "items": [ { "controller": "loginWeb", "name": "登录管理平台" }, { "controller": "appMgr", "name": "管理应用" }, { "controller": "streamMgr", "name": "管理播出流" }, { "controller": "authMgr", "name": "管理播出/推流认证" }, { "controller": "streamingMgr", "name": "管理串流" }, { "controller": "streamingMgr2", "name": "管理监控接入" }, { "controller": "closedStream", "name": "关闭/开启直播流" }, { "controller": "demandDvr", "name": "执行按需录制" }, { "controller": "limitMgr", "name": "设置并发限制" }, { "controller": "autodelMgr", "name": "设置自动删除" }, { "controller": "set_domain", "name": "设置本机域名" }, { "controller": "cdnMgr", "name": "配置CDN" }, { "controller": "statMgr", "name": "播出统计和明细" }, { "controller": "transcodeMgr", "name": "管理转码" }, { "controller": "fileMgr", "name": "管理转码文件（上传和管理资源文件）" }, { "controller": "systemMgr", "name": "重启服务" }, { "controller": "cms_module", "name": "使用内容管理模块（如果安装）" } ] } }

16 外源录制接口

本接口实现录制rtmp协议的直播流。

16.1.添加录制任务

用途添加一个录制任务。
请求 recorderMgr/?request=add&id=8ass3&duration=120&input=rtmp://ip/app/stream id 任务的唯一编号，由调用接口方传入，用于识别一个任务。 input 要录制的直播地址 duration 录制时长，秒 img_int 截图间隔，秒 callback 回调地址，如果有回调地址，录制结束后将回调该URL地址。
响应 { "code":0 }
回调说明 如果提供了callback参数，录制结束后将会请求该地址。系统将使用POST协议向该地址发送任务执行的情况。POST数据是一个json串，json结构如下： { "id":"abcd", "result":"OK", "start":"1516947498", "review_url":0, "images":[ { "offset":0, "url":"imageurl" }, ] } id 任务编号，有添加任务时传入 result 录制结果，OK 或 ERROR start 开始录制时间，UNIX时间戳 review_url 回看地址 images 截图数组 offset 截图时间，相对于开始录制时间的秒数。 url 截图地址

http 云点播编程算法云直播移动直播

0 人点赞