mediamtx API文档：OpenAPI规范与接口调用示例

【免费下载链接】mediamtx Ready-to-use SRT / WebRTC / RTSP / RTMP / LL-HLS media server and media proxy that allows to read, publish, proxy and record video and audio streams. 项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx

概述

MediaMTX是一个功能强大的媒体服务器和代理，支持SRT、WebRTC、RTSP、RTMP、LL-HLS等多种流媒体协议。其控制API（Control API）提供了完整的RESTful接口，允许开发者监控、管理和配置媒体流服务。本文详细解析MediaMTX的OpenAPI规范，并提供实用的接口调用示例。

API基础配置

启用API功能

在MediaMTX配置文件中启用API功能：

api: yes
apiAddress: ":9997"

默认访问地址

API默认监听在 http://localhost:9997，所有接口都位于 /v3 路径下。

OpenAPI规范结构

MediaMTX使用OpenAPI 3.0.0规范定义API接口，主要包含以下组件：

基本信息

openapi: 3.0.0
info:
  version: 1.0.0
  title: MediaMTX API
  description: API of MediaMTX, a server and proxy that supports various protocols.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

核心数据模型

MediaMTX API定义了丰富的数据模型，主要包括：

模型名称	描述	主要字段
GlobalConf	全局配置	logLevel, authMethod, apiAddress, metrics等
PathConf	路径配置	name, source, record, maxReaders等
Path	活动路径信息	name, source, ready, tracks, bytesReceived等
RTMPConn	RTMP连接信息	id, state, path, bytesReceived等
RTSPSession	RTSP会话信息	id, state, transport, rtpPacketsReceived等
SRTConn	SRT连接信息	丰富的网络统计信息
WebRTCSession	WebRTC会话信息	peerConnectionEstablished, localCandidate等

API接口分类

1. 认证管理接口

POST /v3/auth/jwks/refresh

手动刷新JWT JWKS（JSON Web Key Set）。

2. 配置管理接口

全局配置操作

GET /v3/config/global/get
PATCH /v3/config/global/patch

路径配置操作

GET /v3/config/pathdefaults/get
PATCH /v3/config/pathdefaults/patch
GET /v3/config/paths/list
GET /v3/config/paths/get/{name}
POST /v3/config/paths/add/{name}
PATCH /v3/config/paths/patch/{name}
POST /v3/config/paths/replace/{name}
DELETE /v3/config/paths/delete/{name}

3. 运行时监控接口

路径监控

GET /v3/paths/list
GET /v3/paths/get/{name}

协议连接监控

GET /v3/rtmpconns/list
GET /v3/rtmpconns/get/{id}
POST /v3/rtmpconns/kick/{id}

GET /v3/rtspsessions/list  
GET /v3/rtspsessions/get/{id}
POST /v3/rtspsessions/kick/{id}

GET /v3/srtconns/list
GET /v3/srtconns/get/{id}
POST /v3/srtconns/kick/{id}

GET /v3/webrtcsessions/list
GET /v3/webrtcsessions/get/{id}
POST /v3/webrtcsessions/kick/{id}

HLS多路复用器监控

GET /v3/hlsmuxers/list
GET /v3/hlsmuxers/get/{name}

录制文件管理

GET /v3/recordings/list
GET /v3/recordings/get/{name}
DELETE /v3/recordings/deletesegment

接口调用示例

示例1：获取所有活动路径

curl -X GET "http://localhost:9997/v3/paths/list"

响应示例：

{
  "pageCount": 1,
  "itemCount": 2,
  "items": [
    {
      "name": "live",
      "confName": "live",
      "source": {
        "type": "rtspSession",
        "id": "550e8400-e29b-41d4-a716-446655440000"
      },
      "ready": true,
      "readyTime": "2024-01-15T10:30:00Z",
      "tracks": ["video", "audio"],
      "bytesReceived": 10485760,
      "bytesSent": 5242880,
      "readers": [
        {
          "type": "rtspSession",
          "id": "550e8400-e29b-41d4-a716-446655440001"
        }
      ]
    }
  ]
}

示例2：创建新的媒体路径

curl -X POST "http://localhost:9997/v3/config/paths/add/mystream" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "rtsp://camera.example.com/live",
    "record": true,
    "recordPath": "/recordings/%path",
    "maxReaders": 10
  }'

示例3：获取RTMP连接统计信息

curl -X GET "http://localhost:9997/v3/rtmpconns/list"

响应示例：

{
  "pageCount": 1,
  "itemCount": 1,
  "items": [
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "created": "2024-01-15T10:25:00Z",
      "remoteAddr": "192.168.1.100:1935",
      "state": "publish",
      "path": "live",
      "query": "app=live&name=stream",
      "bytesReceived": 15728640,
      "bytesSent": 0
    }
  ]
}

示例4：踢出WebRTC会话

curl -X POST "http://localhost:9997/v3/webrtcsessions/kick/6ba7b810-9dad-11d1-80b4-00c04fd430c8"

分页和查询参数

所有列表接口都支持分页参数：

参数	描述	默认值
itemsPerPage	每页项目数	100
page	页码	1

示例：

curl "http://localhost:9997/v3/paths/list?itemsPerPage=50&page=2"

错误处理

API使用标准HTTP状态码，错误响应格式：

{
  "error": "错误描述信息"
}

常见错误状态码：

• 400 Bad Request: 请求参数错误
• 401 Unauthorized: 认证失败
• 404 Not Found: 资源不存在
• 500 Internal Server Error: 服务器内部错误

认证和安全性

基本认证

curl -u username:password "http://localhost:9997/v3/paths/list"

JWT认证

curl -H "Authorization: Bearer <jwt-token>" "http://localhost:9997/v3/paths/list"

CORS配置

支持跨域请求，可通过配置调整：

apiAllowOrigin: "*"

高级用法

实时监控仪表板

结合API可以构建实时监控仪表板：

自动化运维脚本

#!/bin/bash

# 监控脚本示例
API_URL="http://localhost:9997/v3"

# 检查服务器状态
check_server() {
    response=$(curl -s -o /dev/null -w "%{http_code}" "$API_URL/paths/list")
    if [ "$response" -eq 200 ]; then
        echo "服务器运行正常"
        return 0
    else
        echo "服务器异常: HTTP $response"
        return 1
    fi
}

# 获取连接数统计
get_connections() {
    curl -s "$API_URL/rtmpconns/list" | jq '.itemCount'
    curl -s "$API_URL/rtspsessions/list" | jq '.itemCount'
    curl -s "$API_URL/webrtcsessions/list" | jq '.itemCount'
}

# 主监控循环
while true; do
    if check_server; then
        echo "当前连接数: RTMP=$(get_connections)"
        sleep 30
    else
        echo "服务器异常，等待重试..."
        sleep 60
    fi
done

最佳实践

1. 接口调用频率控制

建议监控接口调用间隔不小于5秒，配置变更接口谨慎调用。

2. 错误重试机制

实现指数退避重试机制处理临时性错误。

3. 数据缓存策略

对相对静态的数据（如配置信息）实施缓存，减少API调用。

4. 安全注意事项

• 生产环境务必启用认证
• 限制API访问IP范围
• 使用HTTPS加密通信

总结

MediaMTX的Control API提供了完整的管理和监控能力，通过标准的OpenAPI规范定义，支持多种流媒体协议的实时监控和配置管理。结合本文提供的示例和最佳实践，开发者可以快速构建强大的媒体流管理系统。

通过合理利用API接口，可以实现自动化运维、实时监控、动态配置等高级功能，大幅提升媒体流服务的可靠性和可维护性。

【免费下载链接】mediamtx Ready-to-use SRT / WebRTC / RTSP / RTMP / LL-HLS media server and media proxy that allows to read, publish, proxy and record video and audio streams. 项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx