ZLMediaKit使用说明文档(V1.0)

文章目录

一、目录说明

1.ZLMediaKit在129.1.7.32的/usr/local/ZLMediaKit 目录下
2.需要注意，本目录包含ZLMediaKit 相关所有的内容（包括编译前的代码）
3.build/目录为编译过程的编译文件目录，每次编译前尽量清空文件夹内容。

4.release/linux/Debug/ 目录为编译后的文件运行目录，实际上运行后所有的动作都发生在这里。

5…release/linux/Debug/www/ 目录为web页面目录 其中包括播放页demo(webrtc/)及录播回放目录（record/）

6.release/linux/Debug/config.ini 为配置文件

7.default.pem 为ssl证书

8.日志目录 log/

二、命令说明

1.启动命令：./MediaServer

2.后台运行启动命令：nohup ./MediaServer -d &

3.带证书后台启动命令(WEBRTC必须带证书启动)：nohup ./MediaServer -s default.pem -d &

4.热加载配置文件启动命令：killall -1 MediaServer

5.关闭程序命令：killall -2 MediaServer

6.启动参数参考如下

缩写 命令 是否带参 默认 是否必填 描述
-h –help 无参数 默认：null 选填 打印此信息
-d –daemon 无参数 默认:null 选填 是否以Daemon方式启动
-l –level 有参数 默认:0 选填 日志等级,LTraceLError(04)
-m –max_day 有参数 默认:7 选填 日志最多保存天数
-c –config 有参数 默认:config.ini 选填 配置文件路径
-s –ssl 有参数 默认:default.pem 选填 ssl证书文件或文件夹,支持p12/pem类型
-t –threads 有参数 默认:8 选填 启动事件触发线程数

-d(–daemon): 是否以守护进程的方式启动，守护进程只做一件事，就是判断子进程(这个才是干活的进程)是否已经退出，退出后会不断尝试重启子进程。

-l(–level): 指定日志打印等级，赋值范围为0~4，等级越高，日志越少。

-m(–max_day): 日志文件保存天数，程序本次运行期间的日志如果超过这个天数，就会被删除。

-c(–config): 指定配置文件路径，配置文件为ini格式，请参考ZLMediaKit的默认配置文件。

-s(–ssl): 指定ssl证书路径，证书格式支持p12和pem类型，里面必须包含公钥和私钥，私钥不能有加密密码。如果指定文件夹，会加载文件夹下所有证书。

-t(–threads): 指定事件驱动线程(干重活)和后台工作线程(干阻塞的活)个数。

三、API 说明

API 使用GET/POST方式，参数既可以使用urlencoded方式也可以使用json方式。 操作这些api一般需要提供secret参数以便鉴权，如果操作ip是127.0.0.1，那么可以无需鉴权。

API功能目录：

“/index/api/getApiList”, ----------- 获取API列表
“/index/api/addFFmpegSource”, ----------- 通过fork FFmpeg进程的方式拉流代理，支持任意协议
“/index/api/addStreamProxy”, ----------- 动态添加rtsp/rtmp/hls/http-ts/http-flv拉流代理
“/index/api/close_stream”, ----------- (已过期，请使用close_streams接口替换)关闭流
“/index/api/close_streams”, ----------- 关闭流(目前所有类型的流都支持关闭)
“/index/api/delFFmpegSource”, ----------- 关闭ffmpeg拉流代理
“/index/api/delStreamProxy”, ----------- 关闭拉流代理(流注册成功后，也可以使用close_streams接口替代)
“/index/api/getAllSession”, ----------- 获取所有TcpSession列表(获取所有tcp客户端相关信息)
“/index/api/getApiList”, -----------
“/index/api/getMediaList”, ----------- 获取流列表，可选筛选参数
“/index/api/getServerConfig”, ----------- 获取服务器配置
“/index/api/getThreadsLoad”, ----------- 获取各epoll(或select)线程负载以及延时
“/index/api/getWorkThreadsLoad”, ----------- 获取各后台epoll(或select)线程负载以及延时
“/index/api/kick_session”, ----------- 断开tcp连接，比如说可以断开rtsp、rtmp播放器等
“/index/api/kick_sessions”, ----------- 断开tcp连接，比如说可以断开rtsp、rtmp播放器等
“/index/api/restartServer”, ----------- 重启服务器,只有Daemon方式才能重启，否则是直接关闭！
“/index/api/setServerConfig”, ----------- 设置服务器配置
“/index/api/isMediaOnline”, ----------- 判断直播流是否在线(已过期，请使用getMediaList接口替代)
“/index/api/getMediaInfo”, ----------- 获取流相关信息(已过期，请使用getMediaList接口替代)
“/index/api/getRtpInfo”, ----------- 获取rtp代理时的某路ssrc rtp信息
“/index/api/getMp4RecordFile”, ----------- 搜索文件系统
“/index/api/startRecord”, ----------- 开始录制hls或MP4
“/index/api/stopRecord”, ----------- 停止录制流
“/index/api/getRecordStatus”, ----------- 获取流录制状态
“/index/api/getSnap”, ----------- 获取截图或生成实时截图并返回
“/index/api/openRtpServer”, ----------- 创建GB28181 RTP接收端口
“/index/api/closeRtpServer”, ----------- 关闭GB28181 RTP接收端口
“/index/api/listRtpServer”, ----------- 获取openRtpServer接口创建的所有RTP服务器
“/index/api/startSendRtp”, ----------- 启动ps-rtp推流

“/index/api/startSendRtpPassive” ----------- 支持rtsp/rtmp等协议转ps-rtp被动推流
“/index/api/stopSendRtp”, ----------- 停止GB28181 ps-rtp推流
“/index/api/getStatistic”, ----------- 获取主要对象个数统计，主要用于分析内存性能
“/index/api/addStreamPusherProxy”, ----------- 添加rtsp/rtmp主动推流
“/index/api/delStreamPusherProxy”, ----------- 关闭推流
“/index/api/version” ----------- 获取版本信息
“/index/api/isRecording” ----------- 获取流录制状态

API返回结果约定

  • HTTP层面统一返回200状态码，body统一为json。
  • body一般为以下样式：
{
    "code" : -1,
    "msg" : "失败提示"
}
  • code值代表执行结果，目前包含以下类型：
typedef enum {
    Exception = -400,//代码抛异常
    InvalidArgs = -300,//参数不合法
    SqlFailed = -200,//sql执行失败
    AuthFailed = -100,//鉴权失败
    OtherFailed = -1,//业务代码执行失败，
    Success = 0//执行成功
} ApiErr;
  • 如果执行成功，那么code == 0,并且一般无msg字段。
  • code == -1时代表业务代码执行不成功，更细的原因一般提供result字段，例如以下：
{
    "code" : -1, # 代表业务代码执行失败
    "msg" : "can not find the stream", # 失败提示
    "result" : -2 # 业务代码执行失败具体原因
}
  • 开发者一般只要关注code字段和msg字段，如果code != 0时，打印显示msg字段即可。
  • code == 0时代表完全成功，如果有数据返回，一般提供data字段返回数据。

API详解

0、`/index/api/getApiList`

  • 功能：获取API列表

  • 范例：http://127.0.0.1/index/api/getApiList

  • 参数：无

  • 响应：

    {
    "code": 0,
    "data": [
        "/index/",
        "/index/api/addFFmpegSource",
        "/index/api/addStreamProxy",
        "/index/api/addStreamPusherProxy",
        "/index/api/closeRtpServer",
        "/index/api/close_stream",
        "/index/api/delFFmpegSource",
        "/index/api/delStreamProxy",
        "/index/api/delStreamPusherProxy",
        "/index/api/downloadBin",
        "/index/api/getAllSession",
        "/index/api/getApiList",
        "/index/api/getMediaInfo",
        "/index/api/getMediaList",
        "/index/api/getMp4RecordFile",
        "/index/api/getRtpInfo",
        "/index/api/getServerConfig",
        "/index/api/getSnap",
        "/index/api/getStatistic",
        "/index/api/getThreadsLoad",
        "/index/api/getWorkThreadsLoad",
        "/index/api/isMediaOnline",
        "/index/api/isRecording",
        "/index/api/kick_session",
        "/index/api/kick_sessions",
        "/index/api/listRtpServer",
        "/index/api/openRtpServer",
        "/index/api/pauseRtpCheck",
        "/index/api/restartServer",
        "/index/api/resumeRtpCheck",
        "/index/api/setServerConfig",
        "/index/api/startRecord",
        "/index/api/startSendRtp",
        "/index/api/stopRecord",
        "/index/api/stopSendRtp",
        "/index/api/version",
        "/index/api/webrtc",
        "/index/hook/on_flow_report",
        "/index/hook/on_http_access",
        "/index/hook/on_play",
        "/index/hook/on_publish",
        "/index/hook/on_record_hls",
        "/index/hook/on_record_mp4",
        "/index/hook/on_rtsp_auth",
        "/index/hook/on_rtsp_realm",
        "/index/hook/on_server_started",
        "/index/hook/on_shell_login",
        "/index/hook/on_stream_changed",
        "/index/hook/on_stream_none_reader",
        "/index/hook/on_stream_not_found",
        "/index/hook/on_stream_not_found_ffmpeg"
    ]
}

1、`/index/api/getThreadsLoad`

  • 功能：获取各epoll(或select)线程负载以及延时

  • 范例：http://127.0.0.1/index/api/getThreadsLoad

  • 参数：无

  • 响应:

    {
   "code" : 0,
   "data" : [
      {
         "delay" : 0, # 该线程延时
         "load" : 0 # 该线程负载，0 ~ 100
      },
      {
         "delay" : 0,
         "load" : 0
      }
   ]
}

2、`/index/api/getWorkThreadsLoad`

  • 功能：获取各后台epoll(或select)线程负载以及延时

  • 范例：http://127.0.0.1/index/api/getWorkThreadsLoad

  • 参数：无

  • 响应:

    {
   "code" : 0,
   "data" : [
      {
         "delay" : 0, # 该线程延时
         "load" : 0 # 该线程负载，0 ~ 100
      },
      {
         "delay" : 0,
         "load" : 0
      }
   ]
}

3、`/index/api/getServerConfig`

  • 功能：获取服务器配置

  • 范例：http://127.0.0.1/index/api/getServerConfig

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数

  • 响应：

    {
   "code" : 0,
   "data" : [
      {
         "api.apiDebug" : "1",
         "api.secret" : "035c73f7-bb6b-4889-a715-d9eb2d1925cc",
         "ffmpeg.bin" : "/usr/local/bin/ffmpeg",
         "ffmpeg.cmd" : "%s -i %s -c:a aac -strict -2 -ar 44100 -ab 48k -c:v libx264 -f flv %s",
         "ffmpeg.log" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/ffmpeg/ffmpeg.log",
         "general.enableVhost" : "1",
         "general.flowThreshold" : "1024",
         "general.maxStreamWaitMS" : "5000",
         "general.streamNoneReaderDelayMS" : "5000",
         "hls.fileBufSize" : "65536",
         "hls.filePath" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/httpRoot",
         "hls.segDur" : "3",
         "hls.segNum" : "3",
         "hook.access_file_except_hls" : "1",
         "hook.admin_params" : "secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc",
         "hook.enable" : "1",
         "hook.on_flow_report" : "https://127.0.0.1/index/hook/on_flow_report",
         "hook.on_http_access" : "https://127.0.0.1/index/hook/on_http_access",
         "hook.on_play" : "https://127.0.0.1/index/hook/on_play",
         "hook.on_publish" : "https://127.0.0.1/index/hook/on_publish",
         "hook.on_record_mp4" : "https://127.0.0.1/index/hook/on_record_mp4",
         "hook.on_rtsp_auth" : "https://127.0.0.1/index/hook/on_rtsp_auth",
         "hook.on_rtsp_realm" : "https://127.0.0.1/index/hook/on_rtsp_realm",
         "hook.on_shell_login" : "https://127.0.0.1/index/hook/on_shell_login",
         "hook.on_stream_changed" : "https://127.0.0.1/index/hook/on_stream_changed",
         "hook.on_stream_none_reader" : "https://127.0.0.1/index/hook/on_stream_none_reader",
         "hook.on_stream_not_found" : "https://127.0.0.1/index/hook/on_stream_not_found",
         "hook.timeoutSec" : "10",
         "http.charSet" : "utf-8",
         "http.keepAliveSecond" : "100",
         "http.maxReqCount" : "100",
         "http.maxReqSize" : "4096",
         "http.notFound" : "<html><head><title>404 Not Found</title></head><body bgcolor=\"white\"><center><h1>您访问的资源不存在！</h1></center><hr><center>ZLMediaKit-4.0</center></body></html>",
         "http.port" : "80",
         "http.rootPath" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/httpRoot",
         "http.sendBufSize" : "65536",
         "http.sslport" : "443",
         "multicast.addrMax" : "239.255.255.255",
         "multicast.addrMin" : "239.0.0.0",
         "multicast.udpTTL" : "64",
         "record.appName" : "record",
         "record.filePath" : "/Users/xzl/git/ZLMediaKit/cmake-build-debug/bin/httpRoot",
         "record.fileSecond" : "3600",
         "record.sampleMS" : "100",
         "rtmp.handshakeSecond" : "15",
         "rtmp.keepAliveSecond" : "15",
         "rtmp.modifyStamp" : "1",
         "rtmp.port" : "1935",
         "rtp.audioMtuSize" : "600",
         "rtp.clearCount" : "10",
         "rtp.cycleMS" : "46800000",
         "rtp.maxRtpCount" : "50",
         "rtp.videoMtuSize" : "1400",
         "rtsp.authBasic" : "0",
         "rtsp.handshakeSecond" : "15",
         "rtsp.keepAliveSecond" : "15",
         "rtsp.port" : "554",
         "rtsp.sslport" : "322",
         "shell.maxReqSize" : "1024",
         "shell.port" : "9000"
      }
   ]
}

4、`/index/api/setServerConfig`

5、`/index/api/restartServer`

  • 功能：重启服务器,只有Daemon方式才能重启，否则是直接关闭！

  • 范例：http://127.0.0.1/index/api/restartServer

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数

  • 响应：

    {
   "code" : 0,
   "msg" : "服务器将在一秒后自动重启"
}

6、`/index/api/getMediaList`

  • 功能：获取流列表，可选筛选参数

  • 范例：http://127.0.0.1/index/api/getMediaList

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    schema N 筛选协议，例如 rtsp或rtmp
    vhost N 筛选虚拟主机，例如__defaultVhost__
    app N 筛选应用名，例如 live
    stream N 筛选流id，例如 test

  • 响应：

    {
  "code" : 0,
  "data" : [
  {
     "app" : "live",  # 应用名
     "readerCount" : 0, # 本协议观看人数
     "totalReaderCount" : 0, # 观看总人数，包括hls/rtsp/rtmp/http-flv/ws-flv
     "schema" : "rtsp", # 协议
     "stream" : "obs", # 流id
     "originSock": {  # 客户端和服务器网络信息，可能为null类型
            "identifier": "140241931428384",
            "local_ip": "127.0.0.1",
            "local_port": 1935,
            "peer_ip": "127.0.0.1",
            "peer_port": 50097
        },
     "originType": 1, # 产生源类型，包括 unknown = 0,rtmp_push=1,rtsp_push=2,rtp_push=3,pull=4,ffmpeg_pull=5,mp4_vod=6,device_chn=7
     "originTypeStr": "MediaOriginType::rtmp_push",
     "originUrl": "rtmp://127.0.0.1:1935/live/hks2", #产生源的url
     "createStamp": 1602205811, #GMT unix系统时间戳，单位秒
     "aliveSecond": 100, #存活时间，单位秒
     "bytesSpeed": 12345, #数据产生速度，单位byte/s
     "tracks" : [    # 音视频轨道
        {
           "channels" : 1, # 音频通道数
           "codec_id" : 2, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecAAC", # 编码类型名称 
           "codec_type" : 1, # Video = 0, Audio = 1
           "ready" : true, # 轨道是否准备就绪
           "frames" : 1119, #累计接收帧数
           "sample_bit" : 16, # 音频采样位数
           "sample_rate" : 8000 # 音频采样率
        },
        {
           "codec_id" : 0, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecH264", # 编码类型名称  
           "codec_type" : 0, # Video = 0, Audio = 1
           "fps" : 59,  # 视频fps
           "frames" : 1119, #累计接收帧数，不包含sei/aud/sps/pps等不能解码的帧
           "gop_interval_ms" : 1993, #gop间隔时间，单位毫秒
           "gop_size" : 60, #gop大小，单位帧数
           "key_frames" : 21, #累计接收关键帧数
           "height" : 720, # 视频高
           "ready" : true,  # 轨道是否准备就绪
           "width" : 1280 # 视频宽
        }
     ],
     "vhost" : "__defaultVhost__" # 虚拟主机名
   }
  ]
}

7、`/index/api/close_stream`(已过期，请使用close_streams接口替换)

  • 功能：关闭流(目前所有类型的流都支持关闭)

  • 范例：http://127.0.0.1/index/api/close_stream?schema=rtmp&vhost=__defaultVhost__&app=live&stream=0&force=1

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    schema Y 协议，例如 rtsp或rtmp
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    force N 是否强制关闭(有人在观看是否还关闭)

  • 响应：

    {
   "code" : 0,
   "result" : 0,# 0:成功，-1:关闭失败，-2:该流不存在
   "msg" : "success"
}

8、`/index/api/close_streams`

  • 功能：关闭流(目前所有类型的流都支持关闭)

  • 范例：http://127.0.0.1/index/api/close_streams?schema=rtmp&vhost=__defaultVhost__&app=live&stream=0&force=1

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    schema N 协议，例如 rtsp或rtmp
    vhost N 虚拟主机，例如__defaultVhost__
    app N 应用名，例如 live
    stream N 流id，例如 test
    force N 是否强制关闭(有人在观看是否还关闭)

  • 响应：

    {
   "code" : 0,
   "count_hit" : 1,  # 筛选命中的流个数
   "count_closed" : 1 # 被关闭的流个数，可能小于count_hit
}

9、`/index/api/getAllSession`

  • 功能：获取所有TcpSession列表(获取所有tcp客户端相关信息)

  • 范例：http://127.0.0.1/index/api/getAllSession

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    local_port N 筛选本机端口，例如筛选rtsp链接：554
    peer_ip N 筛选客户端ip

  • 响应：

    {
   "code" : 0,
   "data" : [
      {
         "id" : "140614477848784",
         "local_ip" : "127.0.0.1",
         "local_port" : 80,
         "peer_ip" : "127.0.0.1",
         "peer_port" : 51136,
         "typeid" : "16WebSocketSessionI11EchoSessionN8mediakit11HttpSessionEE"
      },
      {
         "id" : "140614443300192",
         "local_ip" : "127.0.0.1",
         "local_port" : 80,
         "peer_ip" : "127.0.0.1",
         "peer_port" : 51135,
         "typeid" : "16WebSocketSessionI11EchoSessionN8mediakit11HttpSessionEE"
      },
      {
         "id" : "140614440178720",  # 该tcp链接唯一id
         "local_ip" : "127.0.0.1",  # 本机网卡ip
         "local_port" : 1935, 			# 本机端口号	(这是个rtmp播放器或推流器)
         "peer_ip" : "127.0.0.1",   # 客户端ip 
         "peer_port" : 51130,				# 客户端端口号
         "typeid" : "N8mediakit11RtmpSessionE"  # 客户端TCPSession typeid
      }
   ]
}

10、`/index/api/kick_session`

  • 功能：断开tcp连接，比如说可以断开rtsp、rtmp播放器等

  • 范例：http://127.0.0.1/index/api/kick_session?id=140614440178720

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    Id Y 客户端唯一id，可以通过getAllSession接口获取

  • 响应：

    {
   "code" : 0,
   "msg" : "success"
}

11、`/index/api/kick_sessions`

  • 功能：断开tcp连接，比如说可以断开rtsp、rtmp播放器等

  • 范例：http://127.0.0.1/index/api/kick_sessions?local_port=554

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    local_port N 筛选本机端口，例如筛选rtsp链接：554
    peer_ip N 筛选客户端ip

  • 响应：

    {
   "code" : 0,
   "count_hit" : 1,# 筛选命中客户端个数
   "msg" : "success"
}

12、`/index/api/addStreamProxy`

参数 参数类型 释意 是否必选
secret string api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数 Y
vhost string 添加的流的虚拟主机，例如__defaultVhost__ Y
app string 添加的流的应用名，例如live Y
stream string 添加的流的id名，例如test Y
url string 拉流地址，例如rtmp://live.hkstv.hk.lxdns.com/live/hks2 Y
retry_count int 拉流重试次数，默认为-1无限重试 N
rtp_type int rtsp拉流时，拉流方式，0：tcp，1：udp，2：组播 N
timeout_sec int 拉流超时时间，单位秒，float类型 N
enable_hls 0/1 是否转换成hls协议 N
enable_mp4 0/1 是否允许mp4录制 N
enable_rtsp 0/1 是否转rtsp协议 N
enable_rtmp 0/1 是否转rtmp/flv协议 N
enable_ts 0/1 是否转http-ts/ws-ts协议 N
enable_fmp4 0/1 是否转http-fmp4/ws-fmp4协议 N
enable_audio 0/1 转协议时是否开启音频 N
add_mute_audio 0/1 转协议时，无音频是否添加静音aac音频 N
mp4_save_path string mp4录制文件保存根目录，置空使用默认 N
mp4_max_second int mp4录制切片大小，单位秒 N
hls_save_path string hls文件保存保存根目录，置空使用默认 N

  • 响应：

    {
   "code" : 0,
   "data" : {
      "key" : "__defaultVhost__/proxy/0"  # 流的唯一标识
   }
}

13、`/index/api/delStreamProxy(流注册成功后，也可以使用close_streams接口替代)`

  • 功能：关闭拉流代理

  • 范例：http://127.0.0.1/index/api/delStreamProxy?key=__defaultVhost__/proxy/0

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    key Y addStreamProxy接口返回的key

  • 响应：

    {
   "code" : 0,
   "data" : {
      "flag" : true # 成功与否
   }
}

14、`/index/api/addFFmpegSource`

  • 功能：通过fork FFmpeg进程的方式拉流代理，支持任意协议

  • 范例：http://127.0.0.1/index/api/addFFmpegSource?src_url=http://live.hkstv.hk.lxdns.com/live/hks2/playlist.m3u8&dst_url=rtmp://127.0.0.1/live/hks2&timeout_ms=10000&ffmpeg_cmd_key=ffmpeg.cmd

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    src_url Y FFmpeg拉流地址,支持任意协议或格式(只要FFmpeg支持即可)
    dst_url Y FFmpeg rtmp推流地址，一般都是推给自己，例如rtmp://127.0.0.1/live/stream_form_ffmpeg
    timeout_ms Y FFmpeg推流成功超时时间
    enable_hls Y 是否开启hls录制
    enable_mp4 Y 是否开启mp4录制
    ffmpeg_cmd_key N 配置文件中FFmpeg命令参数模板key(非内容)，置空则采用默认模板:ffmpeg.cmd

  • 响应：

    {
   "code" : 0,
   "data" : {
      "key" : "5f748d2ef9712e4b2f6f970c1d44d93a"  # 唯一key
   }
}

15、`/index/api/delFFmpegSource(流注册成功后，也可以使用close_streams接口替代)`

  • 功能：关闭ffmpeg拉流代理

  • 范例：http://127.0.0.1/index/api/delFFmpegSource?key=5f748d2ef9712e4b2f6f970c1d44d93a

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    key Y addFFmpegSource接口返回的key

  • 响应：

    {
   "code" : 0,
   "data" : {
      "flag" : true # 成功与否
   }
}

16、`/index/api/isMediaOnline(已过期，请使用getMediaList接口替代)`

  • 功能：判断直播流是否在线

  • 范例：http://127.0.0.1/index/api/isMediaOnline?schema=rtsp&vhost=__defaultVhost__&app=live&stream=obs

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    schema Y 协议，例如 rtsp或rtmp
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 obs

  • 响应：

    {
   "code" : 0,
   "online" : true # 是否在线
}

17、`/index/api/getMediaInfo(已过期，请使用getMediaList接口替代)`

  • 功能：获取流相关信息

  • 范例：http://127.0.0.1/index/api/getMediaInfo?schema=rtsp&vhost=__defaultVhost__&app=live&stream=obs

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    schema Y 协议，例如 rtsp或rtmp
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 obs

  • 响应：

    {
  "code" : 0,
  "online" : true, # 是否在线
  "readerCount" : 0, # 本协议观看人数
  "totalReaderCount" : 0, # 观看总人数，包括hls/rtsp/rtmp/http-flv/ws-flv
  "tracks" : [ # 轨道列表
        {
           "channels" : 1, # 音频通道数
           "codec_id" : 2, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecAAC", # 编码类型名称 
           "codec_type" : 1, # Video = 0, Audio = 1
           "ready" : true, # 轨道是否准备就绪
           "sample_bit" : 16, # 音频采样位数
           "sample_rate" : 8000 # 音频采样率
        },
        {
           "codec_id" : 0, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
           "codec_id_name" : "CodecH264", # 编码类型名称  
           "codec_type" : 0, # Video = 0, Audio = 1
           "fps" : 59,  # 视频fps
           "height" : 720, # 视频高
           "ready" : true,  # 轨道是否准备就绪
           "width" : 1280 # 视频宽
        }
  ]
}

18、`/index/api/getRtpInfo`

  • 功能：获取rtp代理时的某路ssrc rtp信息

  • 范例：http://127.0.0.1/index/api/getRtpInfo?stream_id=1A2B3C4D

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    stream_id Y RTP的ssrc，16进制字符串或者是流的id(openRtpServer接口指定)

  • 响应：

    {
   "code" : 0,
   "exist" : true, # 是否存在
   "peer_ip" : "192.168.0.23", # 推流客户端ip
   "peer_port" : 54000 # 客户端端口号
   "local_ip" : "0.0.0.0", #本地监听的网卡ip
   "local_port" : 10000
}

19、`/index/api/getMp4RecordFile`

  • 功能：搜索文件系统，获取流对应的录像文件列表或日期文件夹列表

  • 范例：http://127.0.0.1/index/api/getMp4RecordFile?vhost=__defaultVhost__&app=live&stream=ss&period=2020-01

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    vhost Y 流的虚拟主机名
    app Y 流的应用名
    stream Y 流的ID
    period Y 流的录像日期，格式为2020-02-01,如果不是完整的日期，那么是搜索录像文件夹列表，否则搜索对应日期下的mp4文件列表
    customized_path N 自定义搜索路径，与startRecord方法中的customized_path一样，默认为配置文件的路径

  • 响应：

    # 搜索文件夹列表(按照前缀匹配规则)：period = 2020-01
{
   "code" : 0,
   "data" : {
      "paths" : [ "2020-01-25", "2020-01-24" ],
      "rootPath" : "/www/record/live/ss/"
   }
}

# 搜索mp4文件列表：period = 2020-01-24
{
   "code" : 0,
   "data" : {
      "paths" : [
         "22-20-30.mp4",
         "22-13-12.mp4",
         "21-57-07.mp4",
         "21-19-18.mp4",
         "21-24-21.mp4",
         "21-15-10.mp4",
         "22-14-14.mp4"
      ],
      "rootPath" : "/www/live/ss/2020-01-24/"
   }
}

20、`/index/api/startRecord`

  • 功能：开始录制hls或MP4

  • 范例：http://127.0.0.1/index/api/startRecord?type=1&vhost=__defaultVhost__&app=live&stream=obs

  • 参数：

    参数 是否必选 释意 类型
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数 string
    type Y 0为hls，1为mp4 0/1
    vhost Y 虚拟主机，例如__defaultVhost__ string
    app Y 应用名，例如 live string
    stream Y 流id，例如 obs string
    customized_path N 录像保存目录 string
    max_second N mp4录像切片时间大小,单位秒，置0则采用配置项 int

  • 响应：

    {
   "code" : 0,
   "result" : true # 成功与否
}

21、`/index/api/stopRecord`

  • 功能：停止录制流

  • 范例：http://127.0.0.1/index/api/stopRecord?type=1&vhost=__defaultVhost__&app=live&stream=obs

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    type Y 0为hls，1为mp4
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 obs

  • 响应：

    {
   "code" : 0,
   "result" : true # 成功与否
}

22、`/index/api/isRecording`

  • 功能：获取流录制状态

  • 范例：http://127.0.0.1/index/api/isRecording?type=1&vhost=__defaultVhost__&app=live&stream=obs

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    type Y 0为hls，1为mp4
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 obs

  • 响应：

    {
   "code" : 0,
   "status" : true # false:未录制,true:正在录制
}

23、`/index/api/getSnap`

  • 功能：获取截图或生成实时截图并返回

  • 范例：http://127.0.0.1/index/api/getSnap?url=rtmp://127.0.0.1/record/robot.mp4&timeout_sec=10&expire_sec=30

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    url Y 需要截图的url，可以是本机的，也可以是远程主机的
    timeout_sec Y 截图失败超时时间，防止FFmpeg一直等待截图
    expire_sec Y 截图的过期时间，该时间内产生的截图都会作为缓存返回

  • 响应：

    jpeg格式的图片，可以在浏览器直接打开

24、`/index/api/openRtpServer`

  • 功能：创建GB28181 RTP接收端口，如果该端口接收数据超时，则会自动被回收(不用调用closeRtpServer接口)

  • 范例：http://127.0.0.1/index/api/openRtpServer?port=0&tcp_mode=1&stream_id=test

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    port Y 接收端口，0则为随机端口
    tcp_mode Y 0 udp 模式，1 tcp 被动模式, 2 tcp 主动模式。 (兼容enable_tcp 为0/1)
    stream_id Y 该端口绑定的流ID，该端口只能创建这一个流(而不是根据ssrc创建多个)

  • 响应：

    {
   "code" : 0,
   "port" : 55463 #接收端口，方便获取随机端口号
}

25、`/index/api/closeRtpServer`

  • 功能：关闭GB28181 RTP接收端口

  • 范例：http://127.0.0.1/index/api/closeRtpServer?stream_id=test

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    stream_id Y 调用openRtpServer接口时提供的流ID

  • 响应：

    {
   "code": 0,
   "hit": 1 #是否找到记录并关闭
}

26、`/index/api/listRtpServer`

  • 功能：获取openRtpServer接口创建的所有RTP服务器

  • 范例：http://127.0.0.1/index/api/listRtpServer

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数

  • 响应：

    {
   "code" : 0,
   "data" : [
      {
         "port" : 52183, #绑定的端口号
         "stream_id" : "test" #绑定的流ID
      }
   ]
}

27、`/index/api/startSendRtp`

  • 功能：作为GB28181客户端，启动ps-rtp推流，支持rtp/udp方式；该接口支持rtsp/rtmp等协议转ps-rtp推流。第一次推流失败会直接返回错误，成功一次后，后续失败也将无限重试。

  • 范例：http://127.0.0.1/index/api/startSendRtp?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc&vhost=__defaultVhost__&app=live&stream=test&ssrc=1&dst_url=127.0.0.1&dst_port=10000&is_udp=0

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    ssrc Y 推流的rtp的ssrc,指定不同的ssrc可以同时推流到多个服务器
    dst_url Y 目标ip或域名
    dst_port Y 目标端口
    is_udp Y 是否为udp模式,否则为tcp模式
    src_port N 使用的本机端口，为0或不传时默认为随机端口
    pt N 发送时，rtp的pt（uint8_t）,不传时默认为96
    use_ps N 发送时，rtp的负载类型。为1时，负载为ps；为0时，为es；不传时默认为1
    only_audio N 当use_ps 为0时，有效。为1时，发送音频；为0时，发送视频；不传时默认为0

  • 响应：

    {
   "code": 0, #成功
   "local_port": 57152 #使用的本地端口号 
}
27.1 、`/index/api/startSendRtpPassive`

  • 功能：作为GB28181 Passive TCP服务器；该接口支持rtsp/rtmp等协议转ps-rtp被动推流。调用该接口，zlm会启动tcp服务器等待连接请求，连接建立后，zlm会关闭tcp服务器，然后源源不断的往客户端推流。第一次推流失败会直接返回错误，成功一次后，后续失败也将无限重试(不停地建立tcp监听，超时后再关闭)。

  • 范例：http://127.0.0.1/index/api/startSendRtpPassive?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc&vhost=__defaultVhost__&app=live&stream=test&ssrc=1

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    vhost Y 虚拟主机，例如__defaultVhost__
    app Y 应用名，例如 live
    stream Y 流id，例如 test
    ssrc Y 推流的rtp的ssrc,指定不同的ssrc可以同时推流到多个服务器
    src_port N 使用的本机端口，为0或不传时默认为随机端口
    pt N 发送时，rtp的pt（uint8_t）,不传时默认为96
    use_ps N 发送时，rtp的负载类型。为1时，负载为ps；为0时，为es；不传时默认为1
    only_audio N 当use_ps 为0时，有效。为1时，发送音频；为0时，发送视频；不传时默认为0

  • 响应：

    {
   "code": 0, #成功
   "local_port": 57152 #使用的本地端口号 
}

28、`/index/api/stopSendRtp`

29、`/index/api/getStatistic`

  • 功能：获取主要对象个数统计，主要用于分析内存性能

  • 范例：http://127.0.0.1/index/api/getStatistic?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数

  • 响应：

    {
"code": 0,
"data": {
    "Buffer": 2,
    "BufferLikeString": 1,
    "BufferList": 0,
    "BufferRaw": 1,
    "Frame": 0,
    "FrameImp": 0,
    "MediaSource": 0,
    "MultiMediaSourceMuxer": 0,
    "Socket": 66,
    "TcpClient": 0,
    "TcpServer": 64,
    "TcpSession": 1
}
}

30、`/index/api/addStreamPusherProxy`

  • 功能：添加rtsp/rtmp主动推流(把本服务器的直播流推送到其他服务器去)

  • 范例：http://127.0.0.1/index/api/addStreamPusherProxy?vhost=__defaultVhost__&app=proxy&stream=test&dst_url=rtmp://127.0.0.1/live/test2

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数
    vhost Y 添加的流的虚拟主机，例如__defaultVhost__
    schema Y 协议，例如 rtsp或rtmp
    app Y 添加的流的应用名，例如live
    stream Y 需要转推的流id
    dst_url Y 目标转推url，带参数需要自行url转义
    retry_count N 转推失败重试次数，默认无限重试
    rtp_type N rtsp推流时，推流方式，0：tcp，1：udp
    timeout_sec N 推流超时时间，单位秒，float类型

  • 响应：

    {
   "code" : 0,
   "data" : {
      "key" : "rtmp/__defaultVhost__/proxy/test/4AB43C9EABEB76AB443BB8260C8B2D12"  # 流的唯一标识
   }
}

31、`/index/api/delStreamPusherProxy(可以使用close_streams接口关闭源直播流也可以停止推流)`

32、`/index/api/version(获取版本信息)`

  • 功能：获取版本信息，如分支，commit id, 编译时间

  • 范例：http://127.0.0.1/index/api/version

  • 参数：

    参数 是否必选 释意
    secret Y api操作密钥(配置文件配置)，如果操作ip是127.0.0.1，则不需要此参数

  • 响应：

    {
  "code": 0,
  "data": {
      "branchName": "master",
      "buildTime": "2023-04-19T10:34:34",
      "commitHash": "f143898"
   }
}

四、WEB HooK说明

MediaServer可以把内部的一些事件通过http post 第三方http服务器的方式通知出去，如果是鉴权事件，且访问IP是127.0.0.1或者鉴权url参数与admin_params一致，那么会直接鉴权成功(不会触发鉴权web hook)。

功能目录（点击跳转）

enable -------------------------------- 是否开启http hook
admin_params -------------------------------- 触发http post超时时间
timeoutSec -------------------------------- 超级管理员的url参数

on_flow_report -------------------------------- 流量统计事件
on_http_access -------------------------------- 访问文件时触发
on_play -------------------------------- 播放器鉴权事件
on_publish -------------------------------- 推流鉴权事件
on_record_mp4 -------------------------------- 录制mp4完成后通知事件
on_rtsp_auth -------------------------------- rtsp专用的鉴权事件权事件
on_rtsp_realm -------------------------------- 该rtsp流是否开启rtsp专用方式的鉴
on_shell_login -------------------------------- shell登录鉴权
on_stream_changed -------------------------------- 流注册或注销
on_stream_none_reader -------------------------------- 流无人观看时事件
on_stream_not_found -------------------------------- 流未找到事件
on_server_started -------------------------------- 服务器启动事件
on_server_keepalive -------------------------------- 服务器定时上报时间
on_rtp_server_timeout -------------------------------- 调用openRtpServer 接口

详解

1、enable :

  • 解释:

    是否开启http hook，如果选择关闭，ZLMediaKit将采取默认动作(例如不鉴权等)

2、timeoutSec：

  • 解释:

    事件触发http post超时时间。

3、admin_params：

  • 解释:

    超级管理员的url参数，如果访问者url参数与此一致，那么rtsp/rtmp/hls/http-flv/ws-flv播放或推流将无需鉴权。该选项用于开发者调试用。

4、on_flow_report：

  • 解释:

    流量统计事件，播放器或推流器断开时并且耗用流量超过特定阈值时会触发此事件，阈值通过配置文件general.flowThreshold配置；此事件对回复不敏感。

  • 触发请求：

    POST /index/hook/on_flow_report HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 298
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "duration" : 6,
   "params" : "token=1677193e-1244-49f2-8868-13b3fcc31b17",
   "player" : false,
   "schema" : "rtmp",
   "stream" : "obs",
   "totalBytes" : 1508161,
   "vhost" : "__defaultVhost__",
   "ip" : "192.168.0.21",
   "port" : 55345,
   "id" : "140259799100960"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 流应用名
    duration int tcp链接维持时间，单位秒
    params string 推流或播放url参数
    player bool true为播放器，false为推流器
    schema string 播放或推流的协议，可能是rtsp、rtmp、http
    stream string 流ID
    totalBytes int 耗费上下行流量总和，单位字节
    vhost string 流虚拟主机
    ip string 客户端ip
    port int 客户端端口号
    id string TCP链接唯一ID
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复：

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 40
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 07:09:32 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "msg" : "success"
}

5、on_http_access：

  • 解释:

    访问http文件服务器上hls之外的文件时触发。

  • 触发请求：

    POST /index/hook/on_http_access HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 583
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "header.Accept" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
   "header.Accept-Encoding" : "gzip, deflate",
   "header.Accept-Language" : "en-US,en;q=0.5",
   "header.Cache-Control" : "max-age=0",
   "header.Connection" : "keep-alive",
   "header.Host" : "10.0.17.132",
   "header.Upgrade-Insecure-Requests" : "1",
   "header.User-Agent" : "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:62.0) Gecko/20100101 Firefox/62.0",
   "id" : "140259799100960",
   "ip" : "10.0.17.132",
   "is_dir" : true,
   "params" : "",
   "path" : "/live/",
   "port" : 65073
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    header.* string http客户端请求header
    id string TCP链接唯一ID
    ip string http客户端ip
    is_dir bool http 访问路径是文件还是目录
    params string http url参数
    path string 请求访问的文件或目录
    port unsigned short http客户端端口号
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 68
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 07:27:01 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "err" : "",
   "path" : "",
   "second" : 600
}

  • 回复参数详解：

    参数名 参数类型 参数解释
    code int 请固定返回0
    err string 不允许访问的错误提示，允许访问请置空
    path string 该客户端能访问或被禁止的顶端目录，如果为空字符串，则表述为当前目录
    second int 本次授权结果的有效期，单位秒
    mediaServerId string 服务器id,通过配置文件设置

6、on_play：

  • 解释:

    播放器鉴权事件，rtsp/rtmp/http-flv/ws-flv/hls的播放都将触发此鉴权事件； 如果流不存在，那么先触发on_play事件然后触发on_stream_not_found事件。 播放rtsp流时，如果该流启动了rtsp专属鉴权(on_rtsp_realm)那么将不再触发on_play事件。

  • 触发请求：

    POST /index/hook/on_play HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 189
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "id" : "140574554588960",
   "ip" : "10.0.17.132",
   "params" : "",
   "port" : 65217,
   "schema" : "rtmp",
   "stream" : "obs",
   "vhost" : "__defaultVhost__"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 流应用名
    id string TCP链接唯一ID
    ip string 播放器ip
    params string 播放url参数
    port unsigned short 播放器端口号
    schema string 播放的协议，可能是rtsp、rtmp、http
    stream string 流ID
    vhost string 流虚拟主机
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 40
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 07:41:21 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "msg" : "success"
}

  • 回复参数详解：

    参数名 参数类型 参数解释
    code int 错误代码，0代表允许播放
    msg string 不允许播放时的错误提示

7、on_publish：

  • 解释:

    rtsp/rtmp/rtp推流鉴权事件。

  • 触发请求：

    POST /index/hook/on_publish HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 231
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "id" : "140186529001776",
   "ip" : "10.0.17.132",
   "params" : "token=1677193e-1244-49f2-8868-13b3fcc31b17",
   "port" : 65284,
   "schema" : "rtmp",
   "stream" : "obs",
   "vhost" : "__defaultVhost__"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 流应用名
    id string TCP链接唯一ID
    ip string 推流器ip
    params string 推流url参数
    port unsigned short 推流器端口号
    schema string 推流的协议，可能是rtsp、rtmp
    stream string 流ID
    vhost string 流虚拟主机
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 89
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 07:46:43 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
 "code" : 0,
 "add_mute_audio" : true,
 "continue_push_ms" : 10000,
 "enable_audio" : true,
 "enable_fmp4" : true,
 "enable_hls" : true,
 "enable_mp4" : false,
 "enable_rtmp" : true,
 "enable_rtsp" : true,
 "enable_ts" : true,
 "hls_save_path" : "/hls_save_path/",
 "modify_stamp" : false,
 "mp4_as_player" : false,
 "mp4_max_second" : 3600,
 "mp4_save_path" : "/mp4_save_path/"
}

  • 回复参数详解：

    参数名 参数类型 参数解释 必须参数
    code int 错误代码，0代表允许推流 Y
    msg string 不允许推流时的错误提示 Y
    enable_hls bool 是否转换成hls协议 N
    enable_mp4 bool 是否允许mp4录制 N
    enable_rtsp bool 是否转rtsp协议 N
    enable_rtmp bool 是否转rtmp/flv协议 N
    enable_ts bool 是否转http-ts/ws-ts协议 N
    enable_fmp4 bool 是否转http-fmp4/ws-fmp4协议 N
    enable_audio bool 转协议时是否开启音频 N
    add_mute_audio bool 转协议时，无音频是否添加静音aac音频 N
    mp4_save_path string mp4录制文件保存根目录，置空使用默认 N
    mp4_max_second int mp4录制切片大小，单位秒 N
    hls_save_path string hls文件保存保存根目录，置空使用默认 N
    continue_push_ms uint32 断连续推延时，单位毫秒，置空使用配置文件默认值 N
    mp4_as_player bool MP4录制是否当作观看者参与播放人数计数 N
    modify_stamp bool 该流是否开启时间戳覆盖 N

8、on_record_mp4:

  • 解释:

    录制mp4完成后通知事件；此事件对回复不敏感。

  • 触发请求：

    POST /index/hook/on_record_mp4 HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 473
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "file_name" : "15-53-02.mp4",
   "file_path" : "/root/zlmediakit/httpRoot/__defaultVhost__/record/live/obs/2019-09-20/15-53-02.mp4",
   "file_size" : 1913597,
   "folder" : "/root/zlmediakit/httpRoot/__defaultVhost__/record/live/obs/",
   "start_time" : 1568965982,
   "stream" : "obs",
   "time_len" : 11.0,
   "url" : "record/live/obs/2019-09-20/15-53-02.mp4",
   "vhost" : "__defaultVhost__"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 录制的流应用名
    file_name string 文件名
    file_path string 文件绝对路径
    file_size int 文件大小，单位字节
    folder string 文件所在目录路径
    start_time int 开始录制时间戳
    stream string 录制的流ID
    time_len float 录制时长，单位秒
    url string http/rtsp/rtmp点播相对url路径
    vhost string 流虚拟主机
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 40
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 07:53:13 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "msg" : "success"
}

9、on_rtsp_realm：

  • 解释:

    该rtsp流是否开启rtsp专用方式的鉴权事件，开启后才会触发on_rtsp_auth事件。

    需要指出的是rtsp也支持url参数鉴权，它支持两种方式鉴权。

  • 触发请求：

    POST /index/hook/on_rtsp_realm HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 189
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "id" : "140553560034336",
   "ip" : "10.0.17.132",
   "params" : "",
   "port" : 65473,
   "schema" : "rtsp",
   "stream" : "obs",
   "vhost" : "__defaultVhost__"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 流应用名
    id string TCP链接唯一ID
    ip string rtsp播放器ip
    params string 播放rtsp url参数
    port unsigned short rtsp播放器端口号
    schema string rtsp或rtsps
    stream string 流ID
    vhost string 流虚拟主机
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 51
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 08:05:49 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "realm" : "zlmediakit_reaml"
}

  • 回复参数详解：

    参数名 参数类型 参数解释
    code int 请固定返回0
    realm string 该rtsp流是否需要rtsp专有鉴权，空字符串代码不需要鉴权

10、on_rtsp_auth：

  • 解释:

    rtsp专用的鉴权事件，先触发on_rtsp_realm事件然后才会触发on_rtsp_auth事件。

  • 触发请求：

    POST /index/hook/on_rtsp_auth HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 274
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "id" : "140553560034336",
   "ip" : "10.0.17.132",
   "must_no_encrypt" : false,
   "params" : "",
   "port" : 65473,
   "realm" : "zlmediakit_reaml",
   "schema" : "rtsp",
   "stream" : "obs",
   "user_name" : "test",
   "vhost" : "__defaultVhost__"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 流应用名
    id string TCP链接唯一ID
    ip string rtsp播放器ip
    must_no_encrypt bool 请求的密码是否必须为明文(base64鉴权需要明文密码)
    params string rtsp url参数
    port unsigned short rtsp播放器端口号
    realm string rtsp播放鉴权加密realm
    schema string rtsp或rtsps
    stream string 流ID
    user_name string 播放用户名
    vhost string 流虚拟主机
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 61
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 08:05:49 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "encrypted" : false,
   "passwd" : "test"
}

  • 回复参数详解：

    参数名 参数类型 参数解释
    code int 错误代码，0代表允许播放
    msg string 播放鉴权失败时的错误提示
    encrypted bool 用户密码是否已加密
    passwd string 用户密码

11、on_shell_login：

  • 解释:

    shell登录鉴权，ZLMediaKit提供简单的telnet调试方式

    使用telnet 127.0.0.1 9000能进入MediaServer进程的shell界面。

  • 触发请求：

    POST /index/hook/on_shell_login HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 124
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "id" : "140227419332496",
   "ip" : "10.0.17.132",
   "passwd" : "111111",
   "port" : 49242,
   "user_name" : "xzl"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    id string TCP链接唯一ID
    ip string telnet 终端ip
    passwd bool telnet 终端登录用户密码
    port unsigned short telnet 终端端口号
    user_name string telnet 终端登录用户名
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 40
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 08:23:00 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "msg" : "success"
}

  • 回复参数详解：

    参数名 参数类型 参数解释
    code int 错误代码，0代表允许登录telnet
    msg string 不允许登录telnet时的错误提示

12、on_stream_changed:

  • 解释:

    rtsp/rtmp流注册或注销时触发此事件；此事件对回复不敏感。

  • 触发请求：

    • 注销时:
    POST /index/hook/on_stream_changed HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 118
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "regist" : false,
   "schema" : "rtsp",
   "stream" : "obs",
   "vhost" : "__defaultVhost__"
}

    • 注册时：

      POST /index/hook/on_stream_changed HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 118
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
    "regist" : true,
    "aliveSecond": 0, #存活时间，单位秒
    "app": "live", # 应用名
    "bytesSpeed": 0, #数据产生速度，单位byte/s
    "createStamp": 1617956908,  #GMT unix系统时间戳，单位秒
    "mediaServerId": "your_server_id", # 服务器id
    "originSock": {
        "identifier": "000001C257D35E40",
        "local_ip": "172.26.20.112", # 本机ip
        "local_port": 50166, # 本机端口
        "peer_ip": "172.26.20.112", # 对端ip
        "peer_port": 50155 # 对端port
    },
    "originType": 8,  # 产生源类型，包括 unknown = 0,rtmp_push=1,rtsp_push=2,rtp_push=3,pull=4,ffmpeg_pull=5,mp4_vod=6,device_chn=7,rtc_push=8
    "originTypeStr": "rtc_push",
    "originUrl": "", #产生源的url
    "readerCount": 0, # 本协议观看人数
    "schema": "rtsp", # 协议
    "stream": "test",  # 流id
    "totalReaderCount": 0, # 观看总人数，包括hls/rtsp/rtmp/http-flv/ws-flv/rtc
    "tracks": [{
       "channels" : 1, # 音频通道数
       "codec_id" : 2, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
       "codec_id_name" : "CodecAAC", # 编码类型名称 
       "codec_type" : 1, # Video = 0, Audio = 1
       "ready" : true, # 轨道是否准备就绪
       "sample_bit" : 16, # 音频采样位数
       "sample_rate" : 8000 # 音频采样率
    },
    {
       "codec_id" : 0, # H264 = 0, H265 = 1, AAC = 2, G711A = 3, G711U = 4
       "codec_id_name" : "CodecH264", # 编码类型名称  
       "codec_type" : 0, # Video = 0, Audio = 1
       "fps" : 59,  # 视频fps
       "height" : 720, # 视频高
       "ready" : true,  # 轨道是否准备就绪
       "width" : 1280 # 视频宽
    }],
    "vhost": "__defaultVhost__"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 流应用名
    regist bool 流注册或注销
    schema string rtsp或rtmp
    stream string 流ID
    vhost string 流虚拟主机
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 40
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 08:27:35 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "msg" : "success"
}

13、on_stream_none_reader：

  • 解释:

    流无人观看时事件，用户可以通过此事件选择是否关闭无人看的流。 一个直播流注册上线了，如果一直没人观看也会触发一次无人观看事件，触发时的协议schema是随机的，看哪种协议最晚注册(一般为hls)。 后续从有人观看转为无人观看，触发协议schema为最后一名观看者使用何种协议。 目前mp4/hls录制不当做观看人数(mp4录制可以通过配置文件mp4_as_player控制，但是rtsp/rtmp/rtp转推算观看人数，也会触发该事件。

  • 触发请求：

    POST /index/hook/on_stream_none_reader HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 98
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "schema" : "rtmp",
   "stream" : "obs",
   "vhost" : "__defaultVhost__"
}

  • 请求参数详解：

参数名 参数类型 参数解释
app string 流应用名
schema string rtsp或rtmp
stream string 流ID
vhost string 流虚拟主机
mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 37
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 08:51:23 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "close" : true,
   "code" : 0
}

  • 回复参数详解：

    参数名 参数类型 参数解释
    code int 请固定返回0
    close bool 是否关闭推流或拉流

14、on_stream_not_found：

  • 解释:

    流未找到事件，用户可以在此事件触发时，立即去拉流，这样可以实现按需拉流；此事件对回复不敏感。

  • 触发请求：

    POST /index/hook/on_stream_not_found HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 189
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "mediaServerId" : "your_server_id",
   "app" : "live",
   "id" : "140183261486112",
   "ip" : "10.0.17.132",
   "params" : "",
   "port" : 49614,
   "schema" : "rtsp",
   "stream" : "obs",
   "vhost" : "__defaultVhost__"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    app string 流应用名
    id string TCP链接唯一ID
    ip string 播放器ip
    params string 播放url参数
    port unsigned short 播放器端口号
    schema string 播放的协议，可能是rtsp、rtmp
    stream string 流ID
    vhost string 流虚拟主机
    mediaServerId string 服务器id,通过配置文件设置

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 51
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 08:55:49 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "msg" : "success
}

15、on_server_started

  • 解释:

    服务器启动事件，可以用于监听服务器崩溃重启；此事件对回复不敏感。

  • 触发请求：

    POST /index/hook/on_server_started HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 3096
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "api.apiDebug" : "1",
   "api.secret" : "035c73f7-bb6b-4889-a715-d9eb2d1925cc",
   "ffmpeg.bin" : "/usr/local/bin/ffmpeg",
   "ffmpeg.cmd" : "%s -re -i %s -c:a aac -strict -2 -ar 44100 -ab 48k -c:v libx264 -f flv %s",
   "ffmpeg.log" : "./ffmpeg/ffmpeg.log",
   "general.mediaServerId" : "your_server_id",
   "general.addMuteAudio" : "1",
   "general.enableVhost" : "1",
   "general.flowThreshold" : "1024",
   "general.maxStreamWaitMS" : "5000",
   "general.publishToHls" : "1",
   "general.publishToMP4" : "0",
   "general.publishToRtxp" : "1",
   "general.resetWhenRePlay" : "1",
   "general.streamNoneReaderDelayMS" : "5000",
   "general.ultraLowDelay" : "1",
   "hls.fileBufSize" : "65536",
   "hls.filePath" : "./httpRoot",
   "hls.segDur" : "2",
   "hls.segNum" : "3",
   "hls.segRetain" : "5",
   "hook.admin_params" : "secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc",
   "hook.enable" : "1",
   "hook.on_flow_report" : "https://127.0.0.1/index/hook/on_flow_report",
   "hook.on_http_access" : "https://127.0.0.1/index/hook/on_http_access",
   "hook.on_play" : "https://127.0.0.1/index/hook/on_play",
   "hook.on_publish" : "https://127.0.0.1/index/hook/on_publish",
   "hook.on_record_mp4" : "https://127.0.0.1/index/hook/on_record_mp4",
   "hook.on_rtsp_auth" : "https://127.0.0.1/index/hook/on_rtsp_auth",
   "hook.on_rtsp_realm" : "https://127.0.0.1/index/hook/on_rtsp_realm",
   "hook.on_server_started" : "http://127.0.0.1/index/hook/on_server_started",
   "hook.on_shell_login" : "https://127.0.0.1/index/hook/on_shell_login",
   "hook.on_stream_changed" : "https://127.0.0.1/index/hook/on_stream_changed",
   "hook.on_stream_none_reader" : "https://127.0.0.1/index/hook/on_stream_none_reader",
   "hook.on_stream_not_found" : "https://127.0.0.1/index/hook/on_stream_not_found",
   "hook.timeoutSec" : "10",
   "http.charSet" : "utf-8",
   "http.keepAliveSecond" : "15",
   "http.maxReqCount" : "100",
   "http.maxReqSize" : "4096",
   "http.notFound" : "<html><head><title>404 Not Found</title></head><body bgcolor=\"white\"><center><h1>您访问的资源不存在</h1></center><hr><center>ZLMediaKit-4.0</center></body></html>",
   "http.port" : "80",
   "http.rootPath" : "./httpRoot",
   "http.sendBufSize" : "65536",
   "http.sslport" : "443",
   "multicast.addrMax" : "239.255.255.255",
   "multicast.addrMin" : "239.0.0.0",
   "multicast.udpTTL" : "64",
   "record.appName" : "record",
   "record.fastStart" : "0",
   "record.fileBufSize" : "65536",
   "record.filePath" : "./httpRoot",
   "record.fileRepeat" : "0",
   "record.fileSecond" : "3600",
   "record.sampleMS" : "500",
   "rtmp.handshakeSecond" : "15",
   "rtmp.keepAliveSecond" : "15",
   "rtmp.modifyStamp" : "1",
   "rtmp.port" : "1935",
   "rtp.audioMtuSize" : "600",
   "rtp.clearCount" : "10",
   "rtp.cycleMS" : "46800000",
   "rtp.maxRtpCount" : "50",
   "rtp.videoMtuSize" : "1400",
   "rtsp.authBasic" : "0",
   "rtsp.directProxy" : "1",
   "rtsp.handshakeSecond" : "15",
   "rtsp.keepAliveSecond" : "15",
   "rtsp.modifyStamp" : "0",
   "rtsp.port" : "554",
   "rtsp.sslport" : "322",
   "shell.maxReqSize" : "1024",
   "shell.port" : "9000"
}

  • 请求参数详解： 配置文件json对象

  • 默认回复:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 51
Content-Type: application/json; charset=utf-8
Date: Fri, Sep 20 2019 08:55:49 GMT
Keep-Alive: timeout=10, max=100
Server: ZLMediaKit-4.0

{
   "code" : 0,
   "msg" : "success
}

16、on_server_keepalive

  • 解释:

    服务器定时上报时间，上报间隔可配置，默认10s上报一次

  • 触发请求

    POST /index/hook/on_server_keepalive HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 189
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "data" : {
      "Buffer" : 12,
      "BufferLikeString" : 0,
      "BufferList" : 0,
      "BufferRaw" : 12,
      "Frame" : 0,
      "FrameImp" : 0,
      "MediaSource" : 0,
      "MultiMediaSourceMuxer" : 0,
      "RtmpPacket" : 0,
      "RtpPacket" : 0,
      "Socket" : 108,
      "TcpClient" : 0,
      "TcpServer" : 96,
      "TcpSession" : 0,
      "UdpServer" : 12,
      "UdpSession" : 0
   },
   "mediaServerId" : "192.168.255.10"
}

17、on_rtp_server_timeout

  • 解释:

    调用openRtpServer 接口，rtp server 长时间未收到数据,执行此web hook,对回复不敏感

  • 触发请求

    POST /index/hook/on_rtp_server_timeout HTTP/1.1
Accept: */*
Accept-Language: zh-CN,zh;q=0.8
Connection: keep-alive
Content-Length: 189
Content-Type: application/json
Host: 127.0.0.1
Tools: ZLMediaKit
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36

{
   "local_port" : 0,
   "re_use_port" : true,
   "ssrc" : 0,
   "stream_id" : "test",
   "tcp_mode" : 0,
   "mediaServerId" : "192.168.255.10"
}

  • 请求参数详解：

    参数名 参数类型 参数解释
    local_port int openRtpServer 输入的参数
    re_use_port bool openRtpServer 输入的参数
    ssrc uint32 openRtpServer 输入的参数
    stream_id string openRtpServer 输入的参数
    tcp_mode int openRtpServer 输入的参数
    mediaServerId string 服务器id,通过配置文件设置

五、播放url规则

1、url的组成部分

以rtsp://somedomain.com:554/live/0?token=abcdefg&field=value为例,该url分为以下几个部分：

  • 协议(scheam) : rtsp协议,默认端口554
  • 虚拟主机(vhost) : somedomain.com,该字段既可以是域名也可以是ip，如果是ip则对应的虚拟主机为__defaultVhost__
  • 服务端口号(port) : 554,如果不指定端口号，则使用协议默认端口号
  • 应用名(app) : live
  • 流ID(streamid) : 0
  • 参数(args) : token=abcdefg&field=value

2、ZLMediaKit中的流媒体源

在ZLMediaKit中，流媒体源是一种可以被用于直播转发、推流转发等功能的数据对象，在本项目中被称作为MediaSource，目前支持5种类型的流媒体源，分别是RtspMediaSource、RtmpMediaSource、HlsMediaSource、TSMediaSource、FMP4MediaSource。

定位一个流媒体源，主要通过4个元素(我们后续称其为4元组)，分别是:

  • 协议(scheam)
  • 虚拟主机(vhost)
  • 应用名(app)
  • 流ID(streamid)

RtspMediaSource支持 rtsp播放、rtsp推流、webrtc播放、webrtc推流。

RtmpMediaSource支持 rtmp推流/播放、http-flv播放、ws-flv播放。

HlsMediaSource支持 hls播放。

TSMediaSource 支持 http-ts播放、ws-ts播放。

FMP4MediaSource 支持 http-fmp4播放、ws-fmp4播放。

3、流媒体源对应的播放url

假定有一个RtspMediaSource，它的4元组分别为 rtsp(RtspMediaSource固定为rtsp)、somedomain.com、live、0 那么播放这个流媒体源的url对应为:

  • rtsp://somedomain.com/live/0
  • rtsps://somedomain.com/live/0
  • rtsp://127.0.0.1/live/0?vhost=somedomain.com
  • rtsps://127.0.0.1/live/0?vhost=somedomain.com

如果有一个RtmpMediaSource，它的4元组分别为 rtmp(RtmpMediaSource固定为rtmp)、somedomain.com、live、0 那么播放这个流媒体源的url对应为:

  • rtmp://somedomain.com/live/0
  • rtmps://somedomain.com/live/0
  • rtmp://127.0.0.1/live/0?vhost=somedomain.com
  • rtmps://127.0.0.1/live/0?vhost=somedomain.com

rtmp类型的流媒体源也支持http-flv、websocket直播，对应的url如下：

注意: 老代码flv直播后缀为.flv,新代码才改成了.live.flv

  • http://somedomain.com/live/0.live.flv
  • https://somedomain.com/live/0.live.flv
  • http://127.0.0.1/live/0.live.flv?vhost=somedomain.com
  • https://127.0.0.1/live/0.live.flv?vhost=somedomain.com
  • ws://somedomain.com/live/0.live.flv
  • wss://somedomain.com/live/0.live.flv
  • ws://127.0.0.1/live/0.live.flv?vhost=somedomain.com
  • wss://127.0.0.1/live/0.live.flv?vhost=somedomain.com

当然，ZLMediaKit一般会把rtsp、rtmp流媒体源互相转换，也会转换成hls/http-ts/ws-ts/http-fmp4/ws-fmp4，播放的url如下：

  • HLS
    • http://somedomain.com/live/0/hls.m3u8
    • https://somedomain.com/live/0/hls.m3u8
    • http://127.0.0.1/live/0/hls.m3u8?vhost=somedomain.com
    • https://127.0.0.1/live/0/hls.m3u8?vhost=somedomain.com
  • HTTP-TS/WS-TS(后缀为.live.ts,目的是为了解决与hls的冲突)
    • http://somedomain.com/live/0.live.ts
    • https://somedomain.com/live/0.live.ts
    • http://127.0.0.1/live/0.live.ts?vhost=somedomain.com
    • https://127.0.0.1/live/0.live.ts?vhost=somedomain.com
    • ws://somedomain.com/live/0.live.ts
    • wss://somedomain.com/live/0.live.ts
    • ws://127.0.0.1/live/0.live.ts?vhost=somedomain.com
    • wss://127.0.0.1/live/0.live.ts?vhost=somedomain.com
  • HTTP-fMP4/WS-fMP4(后缀为.live.mp4,目的是为了解决与mp4点播的冲突)
    • http://somedomain.com/live/0.live.mp4
    • https://somedomain.com/live/0.live.mp4
    • http://127.0.0.1/live/0.live.mp4?vhost=somedomain.com
    • https://127.0.0.1/live/0.live.mp4?vhost=somedomain.com
    • ws://somedomain.com/live/0.live.mp4
    • wss://somedomain.com/live/0.live.mp4
    • ws://127.0.0.1/live/0.live.mp4?vhost=somedomain.com
    • wss://127.0.0.1/live/0.live.mp4?vhost=somedomain.com

一般而言，上述url在ZLMediaKit都有效，因为ZLMediaKit默认转换流媒体源。

4、点播url

ZLMediaKit的点播一般通过mp4文件来实现，推荐大家使用http mp4点播，这样是最简单，服务器也无需解复用mp4文件，当然ZLMediaKit目前也支持rtsp、rtmp、http-flv、websocket-flv的mp4点播， 对应的url跟直播url类似，不在赘述，这里只介绍区别。

  • ZLMediaKit对点播限制应用名，默认为record

  • 假如一个mp4文件放置在http根目录record文件夹(

    www/record

    )下，他的相对路径为:

    www/record/0.mp4

    ,那么点播url则为:

    • rtsp://somedomain.com/record/0.mp4
    • rtmp://somedomain.com/record/0.mp4
    • http://somedomain.com/record/0.mp4(这里是通用的http文件点播，服务器不用解复用文件)
    • http://somedomain.com/record/0.mp4.live.flv（这里是http-flv直播，不是http点播，服务器需要解复用文件）
    • ws://somedomain.com/record/0.mp4.live.flv
    • http://somedomain.com/record/0.mp4.live.ts（这里是http-ts直播，不是http点播，服务器需要解复用文件）
    • ws://somedomain.com/record/0.mp4.live.ts
    • http://somedomain.com/record/0.mp4.live.mp4（这里是http-fmp4直播，不是http点播，服务器需要解复用文件）
    • ws://somedomain.com/record/0.mp4.live.mp4

  • 如果开启了虚拟主机，那么点播文件需要放置在 www/somedomain.com/record/0.mp4。

5、webrtc推流/播放

webrtc播放跟上述方式不太一样，webrtc协议本身不定义信令交互协议，用户自己去实现sdp+icecandidate交换逻辑，所以webrtc并没有一个标准的播放器，需要自己使用js或native sdk去实现播放。

zlmediakit实现的webrtc sdp+icecandidate交换方式是http post方式，接口名为/index/api/webrtc, 该接口使用post content传递 offer sdp, 同时url query参数传递媒体源4元组中的app steam_id，由于http协议本身支持vhost，所以不需要另外指定vhost。 webrtc在zlmediakit中可以认为是rtsp协议的另外表现形式，他们推流、播放使用的数据源都相同，都是RtspMediaSource。

在webrtc推流时，交互webrtc sdp+icecandidate的http post接口类似为：http://127.0.0.1/index/api/webrtc?app=live&stream=test&type=push

在webrtc播放时，交互webrtc sdp+icecandidate的http post接口类似为：http://127.0.0.1/index/api/webrtc?app=live&stream=test&type=play。

zlmeiakit工程自带webrtc测试播放/推流器，用户启动zlmediakit后，浏览器访问http://127.0.0.1/webrtc/就可以访问之。

另外，zlmediakit也支持使用webrtc播放mp4文件，http post接口类似为：http://127.0.0.1/index/api/webrtc?app=record&stream=test.mp4&type=play。

6、url参数

ZLMediaKit会识别url中问号后面的字符串为url参数，其格式跟http一致，其中参数vhost是ZLMediaKit内置支持的参数，支持指定vhost。 url参数主要用于播放、推流鉴权，在触发hook api时，会把这些参数提交给第三方业务服务器

# 文档资料
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

Rust 命令行密码管理器工具开发

avatar AtomGit开源社区
cover

AI 浪潮终章奏凯！GitCode & 文心大模型 & 智源研究院 AI 应用开发大赛圆满落幕

avatar AtomGit开源社区
cover

AI 重塑开源协作：AtomGit 开源实践交流分论坛在京顺利举行

avatar AtomGit开源社区