跳到主要内容
版本:3.4.0

媒体服务直接对接集成指南

Streaming服务API为使用Streaming流媒体服务需要调用和提供的一组接口,供采用媒体服务直接对接方式的企业系统使用。 在这种对接集成方式下,媒体服务负责管理媒体流请求,负责将终端码流转换成客户端要求的媒体流格式, 而企业系统则需要实现与客户端进行API对接,需要自行实现终端网关,与终端进行JT/T 808JT/T 1078协议的通讯。

注意

  1. 本文档适用于Streaming服务3.4.0以上版本,不适用于3.3.x或以下版本。
  2. 本文档适合于直接对接接入方式使用,如果使用Micro-GNSSAPI服务,则可以略过或略读本接口文档。使用Micro-GNSSAPI服务时,必须使用不低于3.4.0的版本的Micro GNSS

媒体服务的功能

媒体服务主要提供以下功能:

  • 管理媒体流请求:
    • POST /strm/open接口接受建立媒体流请求,分配播放地址。
    • POST /strm/live_ctrlPOST /strm/replay_ctrl 接口接收控制包括关闭请求,判断请求是否可执行。如果控制请求是关闭请求,则释放请求。
    • POST /strm/release接口接收释放请求。
    • 当媒体流状态发生变更时,通过POST /strm_notif集成接口通知企业应用。
    • 记录媒体流请求的统计数据,并提供统计查询接口。
  • 管理终端媒体流:
    • 从网络接收终端推流数据,与已有媒体流请求建立对应关系。
    • 将终端媒体流数据转换成媒体流请求的格式,并推送到播放地址。
    • 所有媒体流请求释放时,关闭终端媒体流。
    • 记录终端媒体流的统计数据,并提供统计查询接口。

媒体功能支持情况

功能支持情况
音频格式支持
  • G711-A
  • G711-U
  • G726-16、G726-24、G726-32、G726-40
  • ADPCM
  • AAC
视频格式支持
  • H264
客户端协议
  • FLV-HTTP、FLV-WebSocket
  • HLS
多客户端共享实时播放支持
JT/T 1078对讲功能支持
JT/T 1078广播功能需根据应用需求开发
其它除了JT/T 1078协议终端媒体源外,媒体服务支持RTSP媒体源,可通过媒体服务将RTSP媒体源转换成支持的客户端协议

以下为媒体服务直接对接方式的布署图:

deploy-direct-detail

媒体服务接口概览

媒体服务接口包含APISPI两部分,其中:

  • API:是由媒体服务提供的,供企业系统调用的一组接口。
  • SPI:是由企业系统提供的,供媒体服务调用的一组接口。

APISPI接口的调用约定请参阅 调用约定 ,返回的错误码定义请参阅 错误码定义

媒体服务API

媒体服务API包括以下接口:

分类接口端点接口名称简述
媒体流管理POST /strm/open打开流媒体通道用于打开特定终端通道的流媒体,并返回服务端分配的媒体地址。
媒体流管理POST /strm/keep保持流向流媒体服务请求保持一个或多个流。
媒体流管理POST /strm/live_ctrl实时音视频控制对实时媒体流进行控制(预处理)。
媒体流管理POST /strm/replay_ctrl远程录像回放控制对录像媒体流进行控制(预处理)。
媒体流管理POST /strm/release释放流请求一次性关闭多个流。
媒体流管理POST /strm/publish_strm_notif发布媒体事件通知发布媒体事件通知。
媒体管理POST /strm/upload注册远程录像文件上传向媒体服务注册将要进行的远程录像上传。
媒体管理DELETE /strm/upload注销远程录像文件上传注销先前注册的远程录像文件上传活动。
媒体管理GET /strm/upload查询录像文件上传活动状态查询给定请求ID(reqId)指代的远程录像文件上传活动的状态。
媒体管理GET /strm/record查询服务端转储媒体文件查询播放时同时在服务端转储的音视频文件。
服务报告GET /strm/status查询媒体服务状态查询媒体服务的状态,包括当前有效的播放请求的状态,及服务器的系统资源状态(可选返回)。
服务报告GET /strm/recent_closed查询最近已关闭媒体流记录查询最近的已关闭的媒体流记录。
服务报告GET /strm/log查询媒体日志记录查询媒体活动的日志记录。
服务报告GET /strm/stat查询媒体播放统计查询一定期间内的媒体播放统计记录。

集成SPI

集成SPI包括以下接口:

分类接口端点接口名称简述
媒体流管理POST /strm_notif媒体状态通知集成接口当媒体流状态生变更时(包括企业应用通过调用POST /strm/publish_strm_notif 发布媒体事件通知接口产生的通知),媒体服务调用本接口通知企业系统。
媒体管理POST /upload更新远程录像上传状态集成接口当注册的远程录像上传活动的状态发生变化时,媒体服务调用此接口通知企业应用。
媒体管理POST /upload/progress远程录像上传进度报告集成接口在终端不断上传的过程中,在每上传一定量的数据时,媒体服务调用此接口通知企业应用有关上传的当前已经上传字节数。
车辆信息查询GET /veh查询车辆终端号集成接口政府平台请求媒体播放时,流媒体服务通过此接口向企业系统查询车牌号对应的终端识别号。

业务处理

实时音视频播放和控制

要点

  1. 媒体服务负责媒体流的管理,不负责终端JT/T 808信令通道上(包括JT/T 1078的指令)的通讯。终端JT/T 808信令通道上(包括JT/T 1078的指令)的通讯由企业终端网关负责。
  2. 客户端请求后,企业应用应在打开媒体流、控制媒体流、关闭媒体流前,调用媒体服务相应接口,并根据返回结果确定是否需要向终端下发相应指令。
  3. 客户端应在媒体流请求存活期间,按约定经由企业应用转调用保持流接口。

流程

下图为实时音视频播放业务各系统组件的交互过程,其中,黄色的终端网关Web/API均属于企业系统。

open-strm-live.png

  1. 客户端向请求实时音视频播放。
  2. Web/API服务首先调用 POST /strm/open 接口,向媒体服务打开相应的终端通道。
  3. 如果 POST /strm/open 接口返回成功,且返回的OpenStrmResult对象的ctrl属性为true,则企业API系统向其终端网关下发实时音视频播放指令(0x9101) ,如果ctrl属性为false,则不必下发指令。如果 POST /strm/open 接口返回失败,则应终止后续处理,将错误返回给客户端。
  4. 如果 POST /strm/open接口返回的OpenStrmResult对象的ready属性为true,则客户端可以立即播放playUrl 属性给出的地址。否则,需要等待流媒体服务通知(参见 POST /strm_notif )。
  5. 当接收到终端的流数据时,媒体服务调用企业的Web/API服务的 POST /strm_notif 接口,通知流已经可以播放。Web/API服务通过WebSocket或其它途径将通知客户端。
  6. 客户端打开OpenStrmResult对象的playUrl属性给出的地址开始播放。
  7. 客户端在播放过程中,应按照要求的时间间隔向Web/API服务请求流请求保持,Web/API服务转而调用 POST /strm/keep 接口。 对于特定的一个播放请求,如果媒体服务超过指定的时间间隔未收到对应的流请求保持调用,媒体服务将主动关闭请求,并调用 POST /strm_notif 。 接口通知Web/API服务,请求已经关闭。请求关闭后,对应的reqId失效。
  8. 浏览器客户端在播放过程中,如果终端链接断开,或在一段时间内未收到终端流数据,媒体服务将主动关闭所有相关的流请求,并调用 POST /strm_notif 。 接口通知Web/API服务,流已经关闭。如果该流有多个请求,流媒体服务会以当前流的所有存活的请求ID(reqId)分别调用一次 POST /strm_notif , Web/API服务再转而通知相应的客户端。客户端收到通知后,应关闭对应的播放器。
  9. 浏览器客户端在播放过程中,可以向Web/API服务请求流控制,Web/API服务继而将该请求转化成 POST /strm/live_ctrl 调用。
    • 如果 POST /strm/live_ctrl 接口返回成功,则Web/API服务应向终端网关下发实时音视频控制指令(0x9102)
    • 如果 POST /strm/live_ctrl 接口返回失败,则将错误返回给浏览器客户端。注意:如果是流控制命令是请求关闭流(ctrl0), 那么即使 POST /strm/live_ctrl 接口返回-25 无控制权,客户端也应关闭相应的播放器。

企业应用服务处理打开流请求

下图为企业应用服务处理客户端打开实时音视频请求的流程图,供参考:

is-open-strm-flow-chart

客户端打开流请求流程

下图为客户端从打开实时音视频到结束播放全过程的流程图,供参考:

clnt-open-strm-flow-chart

对讲的业务处理

对讲的业务处理流程基本遵循上述实时音视频播放流程。有一个需要补充的地方在于 POST /strm/open 接口返回的 OpenStrmResult 对象会有一个 taUrl 属性 和一个 wsUrl 属性。这两个属性指出用于提交客户端音频数据的websocket地址,前者接收二进制websocket数据包,后者使用stomp协议来提交数据。 企业应用选择其中一种协议,并将相应的音频数据提交地址返回给客户端,然后客户端在对讲期间通过这个地址向媒体服务不断提交音频数据,媒体服务转而将这些音频数据转发给终端,实现对讲。

流程如下:

talk-sequence-diagram

远程录像回放和控制

远程录像回放和控制与实时音视频的播放和控制基本一致,不同点在于:

  1. 打开流媒体通道接口( POST /strm/open )的参数不同(typreplay)
  2. POST /strm/open返回成功后,向终端网关下发的是远程录像回放指令(0x9201)
  3. 控制时调用的接口不同(POST /strm/replay_ctrl),POST /strm/replay_ctrl 接口返回成功后,Web/API向终端网关下发的是远程录像回放控制指令(0x9202)。

终端音视频流通道的共享、模式相容和控制问题

终端媒体流和流请求

  • 终端媒体流:是指终端到媒体服务的媒体流。终端停止推流或媒体流连接断开时,称为终端媒体流关闭。
  • 流请求:是指通过POST /strm/open接口向媒体服务申请的、代表客户端一次播放请求意向的逻辑实体。 当POST /strm/open 接口成功返回时,流请求被创建,并以一个reqId字符串指代,该reqId可用于后续媒体控制调用, 直到以该reqId调用POST /strm/live_ctrl(ctrl0)或POST /strm/replay_ctrl(ctrl2)关闭接口, 或调用POST /strm/release 释放接口后,流请求被释放。释放后,原来的reqId将不再有效。流请求生命周期结束。

终端媒体流因流请求而产生,可能先于流请求释放而关闭(如终端媒体流连接断开)。终端媒体流和流请求两者通过终端识别号、通道号、实时/回放属性来进行对应。如果是实时流,则一个终端媒体流可和一个或多个流请求对应,如果是回放流,则一个终端媒体流只能和一个流请求对应。 当终端媒体流的所有对应的媒体流释放后,媒体服务将关闭终端媒体流。

实时流

实时流的模式相容

多个实时音视频流请求在模式相容时,可共享(同时打开)同一个终端媒体流通道,不相容的后续请求将返回错误码-21

具体来说,在POST /strm/open接口被调用时,同一通道上如果已经有打开的流请求, 则媒体服务考察以下参数的模式相容问题,所有参数均相容后,才确定为模式相容:

  • exclusive独占模式: 独占模式相互之间不相容。相容表(表相容,表不相容,下同)如下:
\ 已打开请求为独占模式已打开请求为非独占模式
新请求为独占模式
新请求为非独占模式
  • dataTyp交互模式:
    • 对讲交互(dataTyp2)本质上是独占的,同一通道上的对讲请求互不相容。
    • 其它交互模式则依媒体类型判断。相容表如下:
\ 已打开音视频已打开仅视频已打开仅音频已打开对讲
新请求音视频
新请求仅视频
新请求仅音频
新请求对讲
  • keepIntv保持流调用间隔:后续新请求的间隔不能大于此前打开的请求的间隔。比较时,如此参数未指定,则代以服务配置的默认值。
  • audioCfg音频配置:如果已打开请求未指定音频配置,则后续请求也必须不指定音频配置;如果如果已打开请求指定了音频配置,则后续请求也必须指定相同的音频配置。相容表如下:
\ 已打开请求未指定音频配置已打开请求已指定音频配置
新请求未指定音频配置
新请求指定了音频配置音频配置相同时相容
  • rtspSrcRTSP媒体源:如果已打开请求未指定RTSP媒体源,则后续请求也必须不指定RTSP媒体源;如果如果已打开请求指定了RTSP媒体源,则后续请求也必须指定相同的RTSP媒体源。相容表如下:
\ 已打开请求未指定RTSP媒体源已打开请求已指定RTSP媒体源
新请求未指定RTSP媒体源
新请求指定了RTSP媒体源RTSP媒体源相同时相容
实时流的共享与控制
  1. 多个客户端可以同时播放同一通道的音视频,但仅当通道只有当前一个客户端请求在播放时,才允许对通道的流进行暂停、恢复控制操作。在多个请求同时播放同一通道的音视频时,尝试对流进行暂停、恢复控制操作将返回-25 没有控制权错误。
  2. POST /strm/open成功返回的OpenStrmResult数据中会包含一个ctrl属性,用于指明企业终端网关是否应实际对终端下发相应的实时音视频播放指令(0x9101)。
  3. 当多个流请求共享同一通道的音视频流时,所有的共享流均失去控制权,调用POST /strm/live_ctrl控制流接口将会返回-25 没有控制权错误, 此时企业终端网关不应下发相应的终端指令;同时,如果ctrl0(即请求关闭流),流请求(reqId所指代的)将被释放。对于-25 没有控制权错误,可以理解为媒体流会话中还有其它流请求,企业应用可以灵活处理,不必狭义地理解为错误。
  4. 随着共享流请求的先后释放,到了同一通道上只剩下一个流请求时,这个剩下的流请求重新获得对流的控制权,可对流进行暂停、恢复等控制操作。
  5. 当所有流请求都已经释放后,媒体服务将关闭终端媒体流。

远程回放流

每一个通道上的远程录像回放都是独占的,不支持共享,也不存在模式相容问题。但不同通道上的远程回放可同时打开。

尝试打开当前正在回放的通道时,接口将返回-21 资源已被占用错误。

媒体流状态及其事件通知

音视频请求内部有多种状态,以下为客户端主要关心的状态:

状态状态名称产生者说明
sent指令已下发企业系统终端网关已向终端下发了推流指令(0x91010x9201, 依请求类型)。
failed终端指令已失败企业系统下发推流指令后,终端应答了指令失败错误码或指令应答超时。
id终端开始推流媒体服务媒体服务已经检测并识别出终端的码流。
ready客户端媒体流已可用媒体服务POST /strm/open接口返回playUrl已经可以播放。
closed流请求已经关闭媒体服务当前流请求已经关闭(或因客户端请求,或因终端不在线、终端媒体流断开、客户端播放请求关闭等原因)。注意:流请求关闭并不意味着终端媒体流已经关闭

以下是这几个主要状态的状态机图:

strm-state-machine.png

下发指令阶段

  • sent事件通知(可选): 在 POST /strm/open 接口返回成功且ctrl属性为true后, 企业终端网关应向终端下发相应的推流指令(0x91010x9201, 依请求类型)。 指令下发后,可选地,可以通过API接口 POST /strm/publish_strm_notif 通知媒体服务,媒体服务将转而调用 POST /strm_notif SPI接口通知企业应用。本事件可供客户端作UI上的提示,但媒体服务未对此事件作其它业务逻辑处理, 如果企业端应用没对这两种事件处理的需求,或使用其它事件传递路径,则可以不使用本接口。

  • failed事件通知(可选):在向终端下发推流指令后,如终端应答了指令失败错误码,或者指令应答超时,则可选地,企业应用可以通过API接口 POST /strm/publish_strm_notif 通知媒体服务,媒体服务将转而调用 POST /strm_notif SPI接口通知企业应用。本事件可供客户端作UI上的提示,但媒体服务未对此事件作其它业务逻辑处理, 如果企业端应用没对这两种事件处理的需求,或使用其它事件传递路径,则可以不使用本接口。注意:即使企业向媒体服务发布了failed事件通知, 企业应用仍然应及时调用 POST /strm/release 接口,或 POST /strm/live_ctrlPOST /strm/replay_ctrl 接口以关闭流请求。

播放阶段

  • id事件通知:当媒体服务已经检测并识别出终端的码流时,媒体服务通过SPI接口 POST /strm_notif 通知企业应用。 如果企业应用对此事件无特殊处理需求,可忽略此事件。
  • ready事件通知:当客户端媒体流已经可用时,媒体媒体服务通过SPI接口 POST /strm_notif 通知企业应用。 此时,企业应用可执行一些必要的业务处理,并应通过WebSocket或其它机制将此事件推送到客户端。
  • closed事件通知:当流请求已经关闭后,媒体媒体服务通过SPI接口 POST /strm_notif 通知企业应用。 此时,企业应用可执行一些必要的业务处理,如:下发关闭实时音视频或关闭远程录像回放指令,并应通过WebSocket或其它机制将此事件推送到客户端。

流请求的保持

为防止浏览器关闭而造成终端无终止的推流,流媒体服务为每个流请求设置心跳和超时机制: 在请求流成功后(即 POST /strm/open 接口返回后),客户端应设置约定周期的定时器,周期性地通过企业API网关经转调用 POST /strm/keep 接口,直到流请求关闭。

由于API调用有一定的延时,故而客户端的流请求保持调用定时器应少于媒体服务配置的默认流请求保持超时间隔数秒(建议少5秒),如媒体服务的流请求保持超时配置默认为25秒,则客户端流请求保持调用间隔应为20秒。 如果客户端要求更大的流请求保持超时间隔时,可在调用 POST /strm/open 打开流媒体接口时通过keepIntv属性指定要求的流请求保持超时间隔。

如果在约定的时间内没有收到这个保持调用,则流媒体服务将主动关闭流请求,并调用SPI接口 POST /strm_notif 通知企业应用。

终端媒体流的关闭

以下情况可引起终端媒体流的关闭:

  1. 该流的所有请求都已经释放(主动释放或因未按时调用流请求保持接口被媒体服务关闭),媒体服务断开终端媒体媒体流。
  2. 终端在一定时间内未推流,媒体服务断开终端媒体流。
  3. 终端的推送连接异常断开,或发生协议错误而被媒体服务关闭。

发生终端媒体流关闭后,流媒体服务将通过 POST /strm_notif SPI接口向各个相关的尚处于活动状态的流请求发布actclosed的事件通知。

媒体播放转储

打开流媒体通道接口 POST /strm/open 支持在播放的同时在服务端转储媒体文件(目前仅当fmt0时支持转储,转储文件格式为FLV)。 当结束播放(所有的共享请求都已关闭)后,可以通过 GET /strm/record 接口查询请求对应的转储文件, 返回的StoreAvurl指明此文件的下载地址。

远程录像上传

远程录像上传与媒体播放的业务过程完全不同,远程录像上传本质上是一个FTP上传处理,主要通过由媒体服务内置的一个FTP服务来实现。 下图为远程录像上传各系统组件的交互过程,其中,黄色的终端网关Web/API均属于企业系统。

av-upload-sequence

  1. 客户端向Web/API服务请求远程录像上传
  2. Web/API服务调用 POST /strm/upload 接口向媒体服务注册将要对指定终端的指定文件进行上传。
  3. 媒体服务将上传FTP的有关信息返回给Web/API服务。
  4. Web/API服务将上传FTP的有关信息转交给终端网关,终端网关下终端下发 0x9206 指令。
  5. 终端应答成功后,终端网关将成功应答返回给 Web/API 服务,而 Web/API 服务 返回第1步客户端发出的远程录像上传请求。
  6. 另一方面,终端在收到 0x9206 指令后,开始向指令中给定的地址发起 FTP 上传文件。
  7. 媒体服务在收到终端的FTP上传的相关命令后,首先通过 PUT /upload 集成接口通知 Web/API 服务 上传已经开始; 然后在终端每上传一定量的数据后、或每隔一小段时间后,通过 PUT /upload/progress 集成接口向 Web/API 服务报告上传的进度; 最后,当上传完成时,媒体服务再次调用 PUT /upload 集成接口通知 Web/API 服务 上传已经完成。这些通知, 企业应用可以通过某些机制如 WebSocket 通过客户端。

超时

如果因为某些原因,如网络原因且文件过大,在一定时间内(2小时内)终端多次重连仍无法完成上传,则媒体服务将会将该上传活动标记为已超时,并调用 PUT /upload 集成接口通知 Web/API 服务上传已经超时。

媒体服务重启的影响

目前媒体服务没有对注册的远程录像上传活动进行持久化,故媒体服务重启后,注册的远程录像上传活动登记将会丢失。 如企业应用在媒体服务重启后仍需要上传终端的远程录像,应重新启动一个新的远程录像上传流程。 可通过 GET /strm/upload 接口确定远程录像上传是否仍然处于活动状态。

取消

用户取消,或企业应用决定中止先前注册的远程录像上传活动,可调用 DELETE /strm/upload 接口注销此活动的登记。 注意,调用注销接口后,企业应用仍需要向终端下发相应的 0x9207 指令(上传控制参数为2)。

RTSP媒体源的播放

媒体服务在支持JT/T 1078协议终端媒体之外,目前还支持对部分规格的RTSP源媒体的实时播放。与JT/T 1078终端音视频实时播放不同的地方是, RTSP媒体源的播放不涉及到终端和终端网关,无需向终端下发指令,只需直接和媒体服务交互即可。

要进行RTSP源媒体的实时播放, 对调用 POST /strm/open 接口时指定 rtspSrc 属性即可。业务流程如下:

rtsp-live-sequence

安全性

API 访问要求

媒体服务的API要求HTTPS协议访问,并要求基本访问身份认证要求 (Basic Access Authentication)。 要访问媒体服务API,要配置媒体服务的config/trusted-clients.json文件,在此文件中定义可访问的用户、密码及权限。如:

{
"clients": [
{
"username": "user-1",
"password": "bPwsAc7FoF1SghovPuusFw",
"privs": [
"config", "strm", "ftp"
]
}
]
}

上面的privs属性以数组形式定义该用户的所有权限。目前定义了三种权限,分别是strm, ftpconfig。每个API都有相应的权限要求,见下表。

API权限要求一览表

分类接口端点接口/功能名称权限要求
媒体流管理POST /strm/open打开流媒体通道strm
媒体流管理POST /strm/keep保持流strm
媒体流管理POST /strm/live_ctrl实时音视频控制strm
媒体流管理POST /strm/replay_ctrl远程录像回放控制strm
媒体流管理POST /strm/release释放流请求strm
媒体流管理POST /strm/publish_strm_notif发布媒体事件通知strm
媒体管理GET /strm/record查询服务端转储媒体文件strm
媒体管理GET /strm/fs/*下载服务端转储媒体文件strm
服务报告GET /strm/status查询媒体服务状态strm
服务报告GET /strm/recent_closed查询最近已关闭媒体流记录strm
媒体管理POST /strm/upload注册远程录像文件上传ftp
媒体管理DELETE /strm/upload注销远程录像文件上传ftp
媒体管理GET /strm/upload查询录像文件上传活动状态ftp
媒体管理GET /strm/ftp/*下载已上传远程录像文件文件ftp
服务报告GET /strm/log查询媒体日志记录config
服务报告GET /strm/stat查询媒体播放统计config

API端口 和 媒体发布端口分开

  • API端口:可单独将API端口布署在只允许内网访问的端口,而媒体发布端口布署在允许内外网访问的端口,从而确保API的安全性。
  • 媒体发布端口:打开媒体流时返回的媒体播放地址带有随机和验证信息,不是从API接口获得的媒体播放地址将无法播放。