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

Streaming服务API为使用Streaming流媒体服务需要调用和提供的一组接口，供采用媒体服务直接对接方式的企业系统使用。 在这种对接集成方式下，媒体服务负责管理媒体流请求，负责将终端码流转换成客户端要求的媒体流格式， 而企业系统则需要实现与客户端进行API对接，需要自行实现终端网关，与终端进行JT/T 808和JT/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_ctrl、POST /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媒体源转换成支持的客户端协议

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

媒体服务接口概览

媒体服务接口包含API和SPI两部分，其中：

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

API、SPI接口的调用约定请参阅 调用约定 ，返回的错误码定义请参阅 错误码定义 。

媒体服务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均属于企业系统。

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 接口返回失败，则将错误返回给浏览器客户端。注意：如果是流控制命令是请求关闭流(ctrl为0)， 那么即使 POST /strm/live_ctrl 接口返回-25 无控制权，客户端也应关闭相应的播放器。

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

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

客户端打开流请求流程

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

对讲的业务处理

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

流程如下：

远程录像回放和控制

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

1. 打开流媒体通道接口( POST /strm/open )的参数不同(typ为replay)
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(ctrl 为0)或POST /strm/replay_ctrl(ctrl为2)关闭接口， 或调用POST /strm/release 释放接口后，流请求被释放。释放后，原来的reqId将不再有效。流请求生命周期结束。

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

实时流

实时流的模式相容

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

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

• exclusive独占模式： 独占模式相互之间不相容。相容表（✓表相容，❌表不相容，下同）如下：

\	已打开请求为独占模式	已打开请求为非独占模式
新请求为独占模式	❌	❌
新请求为非独占模式	❌	✓

• dataTyp交互模式:
  • 对讲交互(dataTyp为2)本质上是独占的，同一通道上的对讲请求互不相容。
  • 其它交互模式则依媒体类型判断。相容表如下：

\	已打开音视频	已打开仅视频	已打开仅音频	已打开对讲
新请求音视频	✓	❌	❌	❌
新请求仅视频	✓	✓	❌	❌
新请求仅音频	✓	❌	✓	❌
新请求对讲	❌	❌	❌	❌

• 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 没有控制权错误， 此时企业终端网关不应下发相应的终端指令；同时，如果ctrl为0(即请求关闭流)，流请求(reqId所指代的)将被释放。对于-25 没有控制权错误，可以理解为媒体流会话中还有其它流请求，企业应用可以灵活处理，不必狭义地理解为错误。
4. 随着共享流请求的先后释放，到了同一通道上只剩下一个流请求时，这个剩下的流请求重新获得对流的控制权，可对流进行暂停、恢复等控制操作。
5. 当所有流请求都已经释放后，媒体服务将关闭终端媒体流。

远程回放流

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

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

媒体流状态及其事件通知

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

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

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

下发指令阶段

• ✴ sent事件通知(可选)： 在 POST /strm/open 接口返回成功且ctrl属性为true后， 企业终端网关应向终端下发相应的推流指令（0x9101 或 0x9201, 依请求类型）。 指令下发后，可选地，可以通过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_ctrl 或 POST /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接口向各个相关的尚处于活动状态的流请求发布act为closed的事件通知。

媒体播放转储

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

远程录像上传

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

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 属性即可。业务流程如下：

安全性

API 访问要求

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

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

上面的privs属性以数组形式定义该用户的所有权限。目前定义了三种权限，分别是strm, ftp和config。每个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接口获得的媒体播放地址将无法播放。