流媒体服务 API

流媒体服务 API

概述

系统集成了流媒体直播服务并提供 API 接口，为物联网场景提供专业的视频直播方案。

集成模式

物联网摄像机主要有三种集成模式：

  • 网络摄像机直连物联网云平台，可提供不同分辨率的多支码流
  • 网络摄像机通过流媒体网关连接物联网云平台，所有媒体流和控制命令都通过网关转发，网关可以通过 Onvif 协议等管理和访问普通摄像机，摄像机不需要重新开发。
  • 网络摄像机通过流媒体小平台连接物联网云大平台

设备 ID

在物联网平台中，每一个设备都必须使用一个唯一的 ID 标识这个设备，在下面的描述中都统一用 did 表示。

did 格式没有统一要求，默认情况下则使用摄像机的 MAC 地址 (16 进制无分隔符小写字符串) 做为 did.

设计原则

本文设计的 API 接口只涉及到最核心和最常用的功能，也只提供最常用的和最基本的可选参数，目的是用户用起来简单，开发者实现起来容易，同时保持较好的可扩展性，可以为专业客户定制所需的个性化功能。

  • 尽量使用最少和最简单的的 API
  • 尽量使用最少和最简洁的参数
  • 在简洁的基础保持较大的可扩展性
  • 尽量保持 API 接口的稳定性

流媒体服务 API

推流

流媒体服务支持标准的 RTMP 推流协议，支持 H.264 和 AAC 编码格式.

RTMP 推流地址为:

rtmp://{domain-name}/live/{did}

  • did 摄像机设备 ID
  • 如 DID 为 aa01234567890 的摄像机的推流地址为: rtmp://{domain-name}/live/aa01234567890

当摄像机支持多码流时，可以同时推送多支不同分辨率的码流, 比如:

rtmp://{domain-name}/live/aa01234567890@1080p

rtmp://{domain-name}/live/aa01234567890@720p

分别表示 1080p 和 720p 的码流

播放

播放流程

播放器->媒体服务器: 播放 /live/{did} (1)
媒体服务器->消息队列: 播放
消息队列->网关: 播放
网关->摄像机: RTSP 拉流 (2)
摄像机->网关: 视频流
网关->媒体服务器: 推送 RTMP 视频流 (3)
媒体服务器->播放器: 视频流
播放器->媒体服务器: 停止播放
媒体服务器->消息队列: 停止 (60 秒后)
消息队列->网关: 停止
网关->媒体服务器: 停止推送
  • 只要有任何应用程序请求播放，就会马上开始推流到服务器
  • 媒体服务器会发送心跳消息到推流网关
  • 当所有应用程序都关闭超过约 60 秒之后媒体服务器会通知网关停止推流
  • 网关在超时收不到心跳消息时需要自动关闭推流

注解：

RTMP 协议

RTMP 协议播放地址为:

rtmp://{domain-name}/live/{did}

  • did 摄像机设备 ID
  • 可以使用 Flash 应用程序播放

HTTP-FLV 协议

HTTP-FLV 协议播放地址为:

https://{domain-name}/v2/live/{did}.flv

  • did 摄像机设备 ID
  • 传输协议为 HTTP(s)
  • 音视频流为 FLV (Flash Video) 格式
  • 可以使用 flv.js 等 HTML5 应用程序播放，(浏览器必须支持 MSE)
  • 支持微信小程序播放, (需要开通直播权限)

摄像机控制 API

摄像机通过 MQTT 协议连接到云平台，可以实现按需推流和云台控制等功能

消息格式

摄像机和平台使用统一的物联网平台消息格式，具体请参考 设备连接协议

设备控制

具体消息格式请参考 网络摄像机控制协议

拉取流

流媒体服务器通过发送 play 和 stop 操作请求，控制摄像机按需推送音视频流，应用程序则只需直接连接和播放流媒体服务器的地址即可，不需要直接和摄像机通信。

流媒体服务器会定时发送通知，告知前端摄像机当前应用程序播放状态，前端摄像机可以根据请求自动开始或停止推送，以便节省带宽资源。

应用程序请求播放流媒体服务器提供的 URL 地址:

http://{domain-name}/v2/live/test.flv?token={token}

当所有应用程序都停止播放后，流媒体服务器会通知摄像机停止推流 (通常会延时 60 秒后发送，以免频繁关停推流)

云台控制

摄像机可以包含云台组件，通过云台组件可以实现镜头的转动和缩放等。

云台控制请求消息首先由应用程序发送给设备连接服务器:

POST https://{domain-name}/v2/device/actions

停止转动

通过这个命令可以控制摄像机镜头停止摆动或缩放，就算摄像机没有成功收到这个命令，也需要在超过一定时间后自动停止摆动或缩放 (巡航等模式除外)

预置位管理

摄像机可以包含预置位组件，通过云台组件可以实现预置位的管理等。

设置预置位

将当前云台位置设置为指定的预置位

查询预置位列表

查询摄像机已设置的预置位列表

调用预置位

转到指定的预置位

删除预置位

删除指定的预置位

错误应答消息

录像和回放

摄像机可以包含录像组件，通过录像组件可以实现录像以及回放等功能。

查询录像文件列表

拉取录像文件

应用程序下载录像文件

GET http://{domain-name}/v2/live/upload/:did/:filename?token={token}

服务器缓存时间

默认情况下服务器会缓存 7 天，缓存期间可随时访问，期满后会自动删除

图像抓拍

摄像机设置

应用程序可以设置部分最常用的摄像机设置，方便日常使用

安全

播放凭证

播放视频时需要提供播放凭证

管理员可以在系统后台为用户分配播放权限，只有相应权限的用户才可以取得播放凭证

有播放权限的用户获取摄像机设备详情时，会返回已包含播放凭证的 URL 地址:

{
    "video": {
        "flv": "http://{domain-name}/v2/live/test.flv?token={token}",
        "rtmp": "rtmp://{domain-name}/live/test?token={token}"
    }
}

云台控制凭证

控制云台时需要提供云台控制凭证

管理员可以在系统后台为用户分配云台控制权限，只有相应权限的用户才可以取得云台控制凭证

有控制权限的用户获取摄像机设备详情时，会返回云台控制凭证

{
    "video": {
        "flv": "http://{domain-name}/v2/live/test.flv?token={token}",
        "rtmp": "rtmp://{domain-name}/live/test?token={token}"
    }
}
image-modal