MediaMTX 配置文件完整参考mediamtx.yml 全参数详解与热加载实战【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtxMediaMTX 是一个开箱即用的实时媒体服务器与媒体代理支持 MoQMedia over QUIC、SRT、WebRTC、RTSP、RTMP、LL-HLS、MPEG-TS 与 RTP 等协议的推流、拉流、转发、录制与回放。本文以仓库根目录的 mediamtx.yml 全量配置文件为骨架逐节讲解每一个可用参数的含义、默认值与取值范围并结合 internal/conf/conf.go、internal/conf/env/env.go 与 internal/confwatcher/confwatcher.go 等源码说明配置加载、校验、环境变量覆盖与热加载的底层机制。读完本文你将能够完全掌控 MediaMTX 的每一项配置并能按需实现内网/公网环境下的多协议流媒体服务。配置文件在项目中的定位mediamtx.yml是 MediaMTX 的默认配置文件随发布包分发在使用 Docker 镜像时它位于镜像根目录/mediamtx.yml。配置参考页 docs/5-references/1-configuration-file.md 本质上就是这份全量配置文件的带注释拷贝而 docs/2-features/05-configuration.md 则说明了如何修改这些参数。配置文件整体由三大部分组成Global settings全局设置作用于服务器整体包括通用、认证、Control API、Metrics、PPROF、Playback 以及 RTSP / RTMP / HLS / WebRTC / SRT / MoQ 各协议服务器pathDefaults默认路径设置对所有路径生效的默认值可在具体路径中覆盖paths路径设置以 map 形式按路径名配置支持普通路径与正则表达式路径并可覆盖任意 pathDefaults 项。从源码结构看internal/conf/conf.go 中的Conf结构体是这份 YAML 的精确映射字段的json标签与配置键一一对应setDefaults()conf.go在读取文件前先写入全部默认值因此 YAML 中即使省略某些参数服务器也能以默认值运行。配置加载流程从 YAML 到运行态conf.Load()conf.go定义了配置生效的完整链路顺序如下调用setDefaults()填充全部默认值通过loadFromFile()读取配置文件若未显式指定路径则在defaultConfPaths中挑选第一个存在的文件见firstThatExists()conf.go当配置文件未显式指定时它是可选的找不到也不报错依次加载环境变量覆盖先读旧前缀RTSP兼容旧版本再读MTX前缀调用setAllNilSlicesToEmptyRecursive()把空切片统一置为空 slice保证易用性与兼容性调用Validate()conf.go做全面校验检查必填项、取值范围、各协议端口依赖关系并把废弃参数自动迁移到新参数同时打印 warning 日志。Validate()中的校验规则非常细致例如readTimeout、writeTimeout、writeQueueSize必须大于零且writeQueueSize必须是 2 的幂conf.goudpMaxPayloadSize必须小于 1472conf.go使用authMethod: http时必须填写authHTTPAddress且必须是 HTTP(S) URL启用 WebRTC 时webrtcLocalUDPAddress、webrtcLocalTCPAddress、webrtcICEServers2三者至少填其一。配置校验失败时服务器会拒绝启动并在日志中给出具体错误。命令行入口在 main.go 与 internal/core/core.go通过 kong 解析命令行参数其中--confpath用于指定配置文件路径默认即mediamtx.yml--version、--check-version、--upgrade分别用于查看版本、检查更新与自动升级。修改配置的四种途径1. 直接编辑配置文件支持热加载编辑随发布包附带的mediamtx.yml即可。Docker 场景下可通过挂载覆盖镜像内的配置文件docker run --rm -it --networkhost -v $PWD/mediamtx.yml:/mediamtx.yml:ro bluenviron/mediamtx:1服务器运行期间写入配置文件会被自动检测并热加载只要可能变更会在不断开现有客户端的情况下应用。这一机制由 internal/confwatcher/confwatcher.go 实现——它基于fsnotify监听配置文件所在目录通过比较符号链接解析后的实际路径来识别文件被替换的场景并对事件做 1 秒最小间隔与 10ms 追加等待的防抖处理confwatcher.go随后触发 internal/core/core.go 的reloadConf()完成重载。closeResources()core.go会逐项对比新旧配置决定哪些组件需要重建、哪些只需ReloadPathConfs等轻量更新从而实现最小化影响的热更新。2. 环境变量覆盖任意参数都可用MTX_PARAMNAME形式的环境变量覆盖其中PARAMNAME为参数名的大写形式。例如覆盖 RTSP 监听地址MTX_RTSPADDRESS127.0.0.1:8554 ./mediamtx数组参数用逗号分隔MTX_RTSPTRANSPORTStcp,udpmap 中的参数用下划线串联MTX_PATHS_TEST_SOURCErtsp://myurl ./mediamtx列表中的参数按位置编号覆盖这对通过环境变量注入认证用户特别有用MTX_AUTHINTERNALUSERS_0_USERusername MTX_AUTHINTERNALUSERS_0_PASSpasswordDocker 中可用-e传递任意配置docker run --rm -it --networkhost -e MTX_PATHS_TEST_SOURCErtsp://myurl bluenviron/mediamtx:1从源码看internal/conf/env/env.go 的loadEnvInternal()通过反射递归遍历Conf结构体字符串、整数、浮点、布尔各有对应的解析分支布尔支持yes/true/no/falsemap 键名需大写且会被转为小写匹配配置键struct 字段通过json标签大写后拼入前缀切片类型支持逗号分隔结构体切片则按前缀_0_字段的编号逐项填充。3. Control API 动态修改启用api: true后可通过 Control API 的 REST 接口在运行中增删改路径、全局配置与 pathDefaults。internal/conf/conf.go 提供了PatchGlobal、PatchPathDefaults、AddPath、PatchPath、ReplacePath、RemovePath等方法对应这些操作API 请求到达后同样走reloadConf()热加载链路。4. 加密配置文件出于安全需要可用 NaCL 库的crypto_secretbox函数对配置文件整体加密将 base64 编码后的密文写入配置文件再用MTX_CONFKEY变量提供密钥启动MTX_CONFKEYmykey ./mediamtx解密逻辑在conf.Load()的loadFromFile()中读取文件后若检测到MTX_CONFKEY或旧前缀RTSP_CONFKEY环境变量则先用 internal/conf/decrypt/decrypt.go 解密再交给 YAML 解析。全局设置GenerallogLevel: info # 日志级别error / warn / info / debug logDestinations: [stdout] # 日志目的地stdout / file / syslog logStructured: false # stdout 或 file 场景下输出 JSONL 结构化日志 logFile: mediamtx.log # logDestinations 含 file 时的日志文件 sysLogPrefix: mediamtx # logDestinations 含 syslog 时使用的前缀 dumpPackets: false # 将数据包转储到磁盘用于调试 readTimeout: 10s # 读操作超时 writeTimeout: 10s # 写操作超时 writeQueueSize: 512 # 出站包队列大小越大吞吐越高、越占内存必须是 2 的幂 udpMaxPayloadSize: 1452 # 出站 UDP 负载上限默认 以太网 1500 - IPv6/UDP 头 48低 MTU 网络可调小 udpReadBufferSize: 0 # 每个 UDP socket 的读缓冲区大小0 表示使用操作系统默认值增大可降低丢包 runOnConnect: # 客户端连接时执行的命令断开时以 SIGINT 终止 # 可用环境变量MTX_CONN_TYPE、MTX_CONN_ID、RTSP_PORT runOnConnectRestart: false runOnDisconnect: # 客户端断开时执行的命令环境变量同 runOnConnect其中logDestinations的实现对应 internal/logger 下的destination_stdout.go、destination_file.go、destination_syslog_*.go三组目的地logLevel对应 internal/logger/level.go。注意readTimeout/writeTimeout/writeQueueSize的校验规则三者都必须大于 0且writeQueueSize必须为 2 的幂conf.goudpMaxPayloadSize必须小于 1472。全局设置AuthenticationauthMethod: internal # 认证方式 # internal凭据存于配置文件 # http每次认证请求调用外部 HTTP URL # jwt凭据为外部身份服务器签发的 JWT authInternalUsers: # internal 方式下启用的用户列表 - user: any # 用户名any 表示任意用户含匿名 pass: # 密码any 用户不使用密码 ips: [] # 允许使用的 IP 或网段空列表表示任意 IP permissions: - action: publish # 可用动作publish / read / playback / api / metrics / pprof path: # 可限制到特定路径空表示任意路径可用 ~ 前缀使用正则 - action: read path: - action: playback path: - user: any # 默认管理员本地 IP 下免认证使用 API、Metrics、PPROF pass: ips: [127.0.0.1, ::1] permissions: - action: api - action: metrics - action: pprof authHTTPAddress: # HTTP 认证地址用户每次操作时服务器以 POST 调用该 URL # 响应码为 20x 则放行否则拒绝 authHTTPFingerprint: # 认证服务器证书自签名/无效时提供 SHA-256 指纹以放行 authHTTPExclude: [] # 排除在 HTTP 认证之外的动作格式同用户权限 authJWTJWKS: # JWT 认证的 JWKS URL用于拉取一次验证 JWT 的公钥 authJWTJWKSFingerprint: # JWKS 服务器证书指纹用途同 authHTTPFingerprint authJWTClaimKey: mediamtx_permissions # 存放权限的 claim 名 authJWTExclude: [] # 排除在 JWT 认证之外的动作 authJWTIssuer: # 期望的 iss claim留空跳过校验 authJWTAudience: # 期望的 aud claim留空跳过校验JWT 的权限 claim 示例{ mediamtx_permissions: [ { action: publish, path: somepath } ] }用户需在Authorization头或密码字段中携带 JWT。指纹的获取命令如下openssl s_client -connect auth_http_domain:443 /dev/null 2/dev/null | sed -n /BEGIN/,/END/p server.crt openssl x509 -in server.crt -noout -fingerprint -sha256 | cut -d -f2 | tr -d :默认的内部用户defaultAuthInternalUsers定义在 conf.go与上面 YAML 注释中的默认管理员一致。校验规则conf.go还包括用户名不能为空any用户不能设置密码authMethod为http时authHTTPAddress不能为空且必须是 HTTP URL为jwt时authJWTJWKS必填且必须是 HTTP URL。全局设置Control API / Metrics / PPROF / Playback 服务这四个 HTTP 服务参数结构完全一致均支持启用开关、监听地址、HTTPS 与 CORS、可信代理配置# Control API控制服务器 api: false # 启用控制 API 服务 apiAddress: :9997 # TCP/HTTP 监听地址 apiEncryption: false # 启用 HTTPS apiServerKey: server.key # HTTPS 时需要的私钥 apiServerCert: server.crt # HTTPS 时需要的证书 apiAllowOrigins: [] # 允许的 CORS 来源支持通配符如 [http://*.example.com] apiTrustedProxies: [] # 前置代理 IP/CIDR可透传 X-Forwarded-For / X-Forwarded-Proto # MetricsPrometheus 兼容指标 metrics: false metricsAddress: :9998 metricsEncryption: false metricsServerKey: server.key metricsServerCert: server.crt metricsAllowOrigins: [] metricsTrustedProxies: [] # PPROF性能剖析 pprof: false pprofAddress: :9999 pprofEncryption: false pprofServerKey: server.key pprofServerCert: server.crt pprofAllowOrigins: [] pprofTrustedProxies: [] # Playback录制文件下载/回放服务 playback: false playbackAddress: :9996 playbackEncryption: false playbackServerKey: server.key playbackServerCert: server.crt playbackAllowOrigins: [*] playbackTrustedProxies: []证书生成命令openssl genrsa -out server.key 2048 openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650启用这些服务时Validate()要求对应的 Address 不能为空conf.go。全局设置RTSP 服务器rtsp: true # 启用 RTSP 服务推流与拉流 rtspTransports: [udp, multicast, tcp] # 启用的传输协议握手始终走 TCP rtspEncryption: no # 安全协议变体no / strict / optional rtspAddress: :8554 # TCP/RTSP 监听地址encryption 为 no/optional 时需要 rtspsAddress: :8322 # TCP/RTSPS 监听地址encryption 为 strict/optional 时需要 rtpAddress: :8000 # UDP/RTP 监听rtspTransports 含 udp 且 encryption 为 no/optional rtcpAddress: :8001 # UDP/RTCP 监听 multicastIPRange: 224.1.0.0/16 # 组播 IP 范围含 multicast 且 encryption 为 no/optional multicastRTPPort: 8002 # 组播 RTP 端口 multicastRTCPPort: 8003 # 组播 RTCP 端口 srtpAddress: :8004 # UDP/SRTP 监听udp 传输 strict/optional 加密 srtcpAddress: :8005 # UDP/SRTCP 监听 multicastSRTPPort: 8006 # 组播 SRTP 端口multicast strict/optional multicastSRTCPPort: 8007 # 组播 SRTCP 端口 rtspServerKey: server.key # RTSPS 私钥strict/optional 时需要 rtspServerCert: server.crt # RTSPS 证书 rtspAuthMethods: [basic] # RTSP 认证方法basic / digest # digest 不提供额外安全仅为兼容而保留 rtspTrustedProxies: [] # 前置代理 IP/CIDR命中时从 PROXY protocol 头取 IP 与认证信息RTSP 部分的校验逻辑最为复杂conf.go不同rtspEncryption取值要求不同的地址族齐全rtspAuthMethods至少一项若启用 digest 认证则authMethod必须为internal且内部用户不得使用哈希凭据。RTSP 具体特性可参考 RTSP 特性指南。全局设置RTMP 服务器rtmp: true # 启用 RTMP 服务推流与拉流 rtmpEncryption: no # 安全变体 RTMPSno / strict / optional rtmpAddress: :1935 # TCP/RTMP 监听no/optional rtmpsAddress: :1936 # TCP/RTMPS 监听strict/optional rtmpServerKey: server.key rtmpServerCert: server.crt rtmpTrustedProxies: [] # 前置代理命中时从 PROXY protocol 头取 IP全局设置HLS 服务器hls: true # 启用 HLS 服务拉流 hlsAddress: :8888 # TCP/HTTP 监听地址 hlsEncryption: false # 启用 HTTPSApple 设备上 Low-Latency HLS 正常工作需要 HTTPS hlsServerKey: server.key hlsServerCert: server.crt hlsAllowOrigins: [*] hlsTrustedProxies: [] # 命中时从 X-Forwarded-For 取客户端 IP hlsAlwaysRemux: false # HLS 默认仅在有人请求时才生成置 true 可始终生成消除首帧延迟 hlsVariant: lowLatency # 协议变体 # mpegts - MPEG-TS 分片兼容性最好 # fmp4 - 分片 MP4更高效 # lowLatency - Low-Latency HLS hlsSegmentCount: 7 # 服务端保留的分片数用于拖动进度条不影响延迟 hlsSegmentDuration: 1s # 每个分片最小时长播放器通常缓冲 3 个分片再播放 # 实际时长还会受 IDR 帧间隔影响每个分片至少含一个 IDR 帧 hlsPartDuration: 200ms # 每个 part 的最小时长LL-HLS 用 part 代替分片 # 受音视频采样距离影响会调整以产出时长相近的分片 hlsSegmentMaxSize: 50M # 单个分片最大体积防止内存耗尽 hlsDirectory: # 分片与非低延迟播放列表的落盘目录 # 可卸载内存压力也可生成自洽目录交给 CDN 直接服务 hlsMuxerCloseAfter: 60s # 无读者请求后等待该时长再关闭 muxer hlsCDNSecret: # CDN 识别密钥CDN 需在每个请求的 Authorization: Bearer 头中携带校验规则hlsVariant为lowLatency时hlsSegmentCount至少为 7其它变体至少为 3conf.gohlsCDNSecret只允许特定字符conf.go。全局设置WebRTC 服务器webrtc: true # 启用 WebRTC 服务推流与拉流 webrtcAddress: :8889 # TCP/HTTP 监听地址 webrtcEncryption: false # HTTPS 仅覆盖 WebRTC 握手 # WebRTC 数据流始终经握手交换的密钥加密 webrtcServerKey: server.key webrtcServerCert: server.crt webrtcAllowOrigins: [*] webrtcTrustedProxies: [] webrtcLocalUDPAddress: :8189 # UDP/ICE 监听地址留空则禁用 webrtcLocalTCPAddress: # TCP/ICE 监听地址默认禁用TCP 效率低拥塞时引入延迟 webrtcIPsFromInterfaces: true # 从网卡收集 IP 发给客户端 webrtcIPsFromInterfacesList: [] # 指定网卡空表示全部 webrtcAdditionalHosts: [] # 额外发送给客户端的主机或 IP webrtcICEServers2: [] # ICE 服务器 # STUN 用于获取/分享服务器公网 IP # TURN/TURNS 强制所有流量经过其中转 # - url: stun:stun.l.google.com:19302 # username: # 用户名为 AUTH_SECRET 时为基于密钥的认证 # password: # 密钥须填入密码字段 # clientOnly: false webrtcSTUNGatherTimeout: 5s # STUN 候选收集超时 webrtcHandshakeTimeout: 10s # WebRTC 握手超时 webrtcTrackGatherTimeout: 2s # 轨道收集超时校验要点conf.goICE 服务器 URL 必须以stun:、turn:或turns:开头webrtcLocalUDPAddress、webrtcLocalTCPAddress、webrtcICEServers2至少填一个若启用了本地监听且webrtcIPsFromInterfaces为 false则必须提供webrtcAdditionalHosts。更细的调优见 WebRTC 特性指南。全局设置SRT 与 MoQ 服务器srt: true # 启用 SRT 服务推流与拉流 srtAddress: :8890 # UDP/SRT 监听地址 moq: true # 启用 MoQMedia over QUIC服务推流与拉流 moqHTTP2Address: :8892 # TCP/HTTP2 监听托管 Web 客户端 moqHTTP3Address: :8892 # UDP/HTTP3 监听托管 WebTransport 端点 moqQUICAddress: :8893 # UDP/QUIC 监听用于原生 MoQ-over-QUIC moqServerKey: auto.key # 私钥若设为 auto.key 则自动生成并保存在当前目录 moqServerCert: auto.crt moqAllowOrigins: [*] moqTrustedProxies: [] # 可信代理用于透传 X-Forwarded-For 真实 IPmoqServerKey: auto.key配合自动生成的auto.crt让 MoQ 服务零配置即可运行这一点是 MoQ 服务器与其它协议服务器默认server.key/server.crt的主要差异。pathDefaults默认路径设置pathDefaults下的设置对所有路径生效除非在paths中覆盖。对应源码 internal/conf/path.go 中的Path结构体。通用设置pathDefaults: # source 支持的全部取值 # * publisher - 由 RTSP/RTMP/WebRTC/SRT 客户端推流 # * rtsp://user:passhost:port/path - 从其它 RTSP 服务器/摄像头拉流 # * rtsps://user:passhost:port/path - 同上RTSPS # * rtsphttp://user:passhost:port/path - 同上HTTP 隧道 # * rtspshttp://user:passhost:port/path - 同上HTTPS 隧道 # * rtspws://user:passhost:port/path - 同上WebSocket 隧道 # * rtspsws://user:passhost:port/path - 同上安全 WebSocket 隧道 # * rtmp://user:passhost:port/path#streamKey - 从其它 RTMP 服务器/摄像头拉流 # * rtmps://user:passhost:port/path#streamKey - 同上RTMPS # * http://user:passhost:port/stream.m3u8 - 从其它 HLS 服务器/摄像头拉流 # * https://user:passhost:port/stream.m3u8 - 同上HTTPS # * udpmpegts://ip:port - 在指定地址监听 MPEG-TS over UDP # * unixmpegts://socketPath - 从 Unix socket 拉取 MPEG-TS # * udprtp://ip:port - 在指定地址监听 RTP over UDP # * srt://host:port?streamidstreamid - 从其它 SRT 服务器/摄像头拉流 # * moqt://user:passhost:port/path - 从其它 MoQ 服务器拉流 # * whep://host:port/path - 从其它 WebRTC 服务器HTTPWHEP拉流 # * wheps://host:port/path - 同上HTTPSWHEP # * redirect - 由其它路径或服务器提供 # * rpiCamera - 由树莓派摄像头提供 # 可用变量$MTX_QUERY首个读者传入的查询参数、$G1/$G2/...路径名为正则时的捕获组 source: publisher sourceFingerprint: # 拉流源 TLS 证书自签名/无效时提供 SHA-256 指纹放行 sourceOnDemand: false # 仅当存在读者时才拉取 URL 源节省带宽 sourceOnDemandStartTimeout: 10s # 按需启动时读者最多等待的时间 sourceOnDemandCloseAfter: 10s # 无读者后等待该时长再关闭源 maxReaders: 0 # 最大读者数0 表示不限 srtReadPassphrase: # 从此路径读流所需的 SRT 加密口令 useAbsoluteTimestamp: false # 使用帧的绝对时间戳而非替换为当前时间source的解析与校验在 path.go 的validate()中每种 scheme 前缀有独立的校验分支RTSP 系列、RTMP、HTTP(S)、UDP/UDPmpegts/UDPrtp、SRT、MoQT、WHEP、redirect、rpiCameraURL 校验要求用户名与密码必须成对出现。另外正则路径或all_others若配置静态源则必须开启sourceOnDemandpath.go否则启动校验会失败。常开可用Always availablealwaysAvailable: false # 常开模式流不可用时循环播放离线片段 alwaysAvailableTracks: [] # 默认离线片段的轨道 # 可用编解码AV1、VP9、H265、H264、Opus、MPEG4Audio、G711、LPCM # - codec: H264 # sampleRate: 48000 # MPEG4Audio/G711/LPCM 必须提供采样率与声道数 # channelCount: 2 # muLaw: false # G711 必须提供 muLaw alwaysAvailableFile: # 用 MP4 文件替代默认离线片段约束alwaysAvailable不能用于正则路径、不能与sourceOnDemand/runOnDemand/useAbsoluteTimestamp混用alwaysAvailableFile与alwaysAvailableTracks互斥且文件必须是含受支持编解码轨道的有效 MP4校验见 path.go 的checkAlwaysAvailableFile()会检查ftyp魔数与轨道编解码类型。详细用法参考 常开可用指南。转发Forwardforward: [] # 将本路径流转发到外部服务器 # 支持的目的地格式 # * rtsp://user:passhost:port/path - 转发到其它 RTSP 服务器 # * rtsps://user:passhost:port/path - 转发到其它 RTSPS 服务器 # * rtmp://user:passhost:port/path#streamKey - 转发到其它 RTMP 服务器 # * rtmps://user:passhost:port/path#streamKey # * srt://host:port?streamidstreamid # * moqt://user:passhost:port/path - 转发到其它 Media-over-QUIC 服务器 # * whip://host:port/path/whip - 经 HTTPWHIP 转发到 WebRTC 服务器 # * whips://host:port/path/whip - 经 HTTPSWHIP 转发 # 可用变量$MTX_PATH路径名、$G1/$G2/...正则捕获组 # - dest: # destFingerprint: # 目标证书自签名/无效时提供 SHA-256 指纹 # moqTransport: quic # MoQ 转发时的传输协议quic / webtransport # whipBearerToken: # 使用 WHIP 时放入 Authorization: Bearer 头的令牌转发目标解析与校验见 internal/conf/forward_dest.go实现位于 internal/forward 目录rtsp、rtmp、srt、moq、webrtc 各一份 dest 实现。录制Recordrecord: false # 将流录制到磁盘 recordPath: ./recordings/%path/%Y-%m-%d_%H-%M-%S-%f # 录制分片路径扩展名自动追加 # 可用变量%path路径名、%Y %m %d年月日、 # %H %M %S时分秒、%f微秒、%z时区、%sUnix 时间戳 recordFormat: fmp4 # 录制格式fmp4分片 MP4/ mpegtsMPEG-TS recordPartDuration: 1s # fMP4 分片由若干小 MP4 文件part拼接而成此为每 part 时长 # MPEG-TS 分片按该周期把 188 字节包刷盘 # 系统故障时最后一段 part 会丢失因此 part 时长等于 RPO恢复点目标 recordMaxPartSize: 50M # 防止内存耗尽 recordSegmentDuration: 1h # 每个分片的最小时长 recordDeleteAfter: 1d # 分片保留时长之后自动删除0s 表示不自动删除校验规则path.gorecordPath必须包含%path与%s或%Y %m %d %H %M %S组合启用 Playback 服务时还必须包含%f分片时长上限为 1 天recordDeleteAfter非零时不能小于recordSegmentDuration。录制实现见 internal/recorder 与 internal/recordcleaner/cleaner.go回放见 internal/playback。推流源source 为 publisher 时overridePublisher: true # 允许另一客户端顶替当前推流者 srtPublishPassphrase: # 向此路径推流所需的 SRT 加密口令10~79 字符 rtspDemuxMpegts: false # 将 RTSP 上的 MPEG-TSMP2T/90000解复用为基本流 # 使 H.264/H.265/AAC 等作为原生轨道暴露 # 从而让 HLS、WebRTC 等输出透明兼容 MPEG-TS 源RTSP 源source 为 RTSP/RTSPS URL 时rtspTransport: automatic # 拉流传输协议automatic / udp / multicast / tcp rtspAnyPort: false # 兼容不提供服务器端口或使用随机端口的源有安全隐患 # 仅在源有要求时使用 rtspRangeType: # 发送给源的 Range 头从指定偏移开始播放 # clock - 绝对时间 # npt - Normal Play Time # smpte - 相对录制起点的 SMPTE 时间戳 rtspRangeStart: # Range 起点格式依 rtspRangeType # clock: UTC ISO 8601如 20230812T120000Z # npt/smpte: 时长如 300ms、1.5m、2h45m # 合法时间单位ns、us或 µs、ms、s、m、h rtspScale: # 播放速率Scale 头负值为倒放1 快进0~1 慢放 rtspUDPSourcePortRange: [32768, 60999] # 出站 UDP 包源端口范围RTP / MoQ / WHEP / redirect / rpiCamera 源# RTP 源source 为 udprtp 时 rtpSDP: # RTP 流的 SDP会话描述协议udprtp 源必填 # MoQ 源source 为 moqt URL 时 moqTransport: quic # 拉流传输协议quic / webtransport # WebRTC/WHEP 源source 为 whep/wheps 时 whepBearerToken: # 放入 Authorization: Bearer 头的令牌 whepSTUNGatherTimeout: 5s whepHandshakeTimeout: 10s whepTrackGatherTimeout: 2s # redirect 源source 为 redirect 时 sourceRedirect: # 重定向目标路径可为相对路径如 /otherstream或绝对 RTSP URL # 树莓派摄像头源source 为 rpiCamera 时 rpiCameraCamID: 0 # 摄像头 ID rpiCameraSecondary: false # 是否为辅助流 rpiCameraWidth: 1920 rpiCameraHeight: 1080 rpiCameraHFlip: false # 水平翻转 rpiCameraVFlip: false # 垂直翻转 rpiCameraBrightness: 0 # 亮度 [-1, 1] rpiCameraContrast: 1 # 对比度 [0, 16] rpiCameraSaturation: 1 # 饱和度 [0, 16] rpiCameraSharpness: 1 # 锐度 [0, 16] rpiCameraExposure: normal # 曝光模式normal / short / long / custom rpiCameraAWB: auto # 自动白平衡auto / incandescent / tungsten / fluorescent / # indoor / daylight / cloudy / custom rpiCameraAWBGains: [0, 0] # 手动白平衡增益 [红, 蓝]可替代 rpiCameraAWB rpiCameraDenoise: off # 降噪模式off / cdn_off / cdn_fast / cdn_hq rpiCameraShutter: 0 # 固定快门速度微秒 rpiCameraMetering: centre # AEC/AGC 测光模式centre / spot / matrix / custom rpiCameraGain: 0 # 固定增益 rpiCameraEV: 0 # 曝光补偿 [-10, 10] rpiCameraROI: # 感兴趣区域格式 x,y,width,height均归一化到 0~1 rpiCameraHDR: false # 是否在树莓派 Camera 3 上启用 HDR rpiCameraTuningFile: # 调优文件 rpiCameraMode: # 传感器模式 [宽]:[高]:[位深]:[packing]位深与 packing 可选 rpiCameraFPS: 30 # 帧率 rpiCameraAfMode: continuous # 自动对焦模式auto / manual / continuous rpiCameraAfRange: normal # 对焦范围normal / macro / full rpiCameraAfSpeed: normal # 对焦速度normal / fast rpiCameraLensPosition: 0.0 # 镜头位置仅手动对焦距离 d 1 / value # 0 对焦无穷远0.5 对焦 2 米外物体2 对焦 50cm 处 rpiCameraAfWindow: # 对焦窗口x,y,width,height占整幅图像的比例 rpiCameraFlickerPeriod: 0 # 手动闪烁校正周期微秒 rpiCameraTextOverlayEnable: false # 每帧叠加文字 rpiCameraTextOverlay: %Y-%m-%d %H:%M:%S - MediaMTX # 叠加文本strftime() 格式 rpiCameraCodec: auto # 编码auto / hardwareH264 / softwareH264 / mjpeg # auto 时主流优先 hardwareH264硬件编码器可用时 # 否则 softwareH264辅助流为 mjpeg rpiCameraIDRPeriod: 60 # IDR 帧间隔hardwareH264/softwareH264 时 rpiCameraBitrate: 5000000 # 码率hardwareH264/softwareH264 时 rpiCameraH264Profile: auto # auto / baseline / main / high # auto 时hardwareH264 默认 mainsoftwareH264 默认 baseline rpiCameraH264Level: 4.1 # 4.0 / 4.1 / 4.2 rpiCameraMJPEGQuality: 60 # M-JPEG 质量 0-100rpiCamera 参数校验在 path.go编码为 MJPEG 时宽高必须是 8 的倍数且小于 2048各枚举值曝光、AWB、降噪、测光、对焦模式/范围/速度、编码、profile、level都有白名单同一摄像头 ID 的辅助流必须关联到一个主流且主流只能关联一个辅助流。钩子Hooks# 路径初始化时执行可用于服务器启动时推流程序关闭时以 SIGINT 终止 # 环境变量MTX_PATH、RTSP_PORT、G1/G2/... runOnInit: runOnInitRestart: false # 有读者请求且尚未有人推流时执行可用于按需推流无读者时以 SIGINT 终止 # 环境变量MTX_PATH、MTX_QUERY首个读者的查询参数URL 编码、RTSP_PORT、G1/G2/... runOnDemand: runOnDemandRestart: false runOnDemandStartTimeout: 10s # 读者最长等待 runOnDemand 开始推流的时间 runOnDemandCloseAfter: 10s # 无读者后等待该时长再关闭命令 runOnUnDemand: # 无读者时执行环境变量同 runOnDemand # 流可读时执行流不可读时以 SIGINT 终止 # 环境变量MTX_PATH、MTX_QUERY推流者的查询参数URL 编码、MTX_SOURCE_TYPE、 # MTX_SOURCE_ID、RTSP_PORT、G1/G2/... runOnAvailable: runOnAvailableRestart: false runOnUnavailable: # 流不可读时执行环境变量同 runOnAvailable # 流在线可读且由在线源提供非离线片段时执行 # 环境变量同 runOnAvailable runOnOnline: runOnOnlineRestart: false runOnOffline: # 客户端开始读流时执行客户端停止读流时以 SIGINT 终止 # 环境变量MTX_PATH、MTX_QUERY读者的查询参数、MTX_READER_TYPE、MTX_READER_ID、 # RTSP_PORT、G1/G2/... runOnRead: runOnReadRestart: false runOnUnread: # 录制分片创建时执行 # 环境变量MTX_PATH、MTX_SEGMENT_PATH、RTSP_PORT、G1/G2/... runOnRecordSegmentCreate: # 录制分片完成时执行 # 环境变量MTX_PATH、MTX_SEGMENT_PATH、MTX_SEGMENT_DURATION、RTSP_PORT、G1/G2/... runOnRecordSegmentComplete:钩子约束path.gorunOnInit不能用于正则路径runOnDemand/runOnUnDemand仅当source为publisher时可用。钩子执行器位于 internal/externalcmd各钩子的业务逻辑见 internal/hooks。paths路径配置paths: # map 的键为路径名。 # 任何 pathDefaults 中的设置都可在此覆盖。 # 使用 ~ 前缀可用正则表达式匹配 # ~^(test1|test2)$ 匹配 test1 和 test2 # ~^prefix 匹配所有以 prefix 开头的路径 # 示例 # my_camera: # source: rtsp://my_camera # 不匹配任何其它条目的路径统一应用此配置 all_others:路径匹配逻辑在 internal/conf/path.go 的FindPathConf()中先精确匹配静态路径名失败后再按名称排序依次尝试正则路径all/all_others始终排在最后兜底匹配成功则返回对应配置与正则捕获组供$G1、$G2等变量使用。路径名校验IsValidPathName()path.go要求非空、不以/开头或结尾、仅含字母数字下划线点号减号斜杠且不允许./..路径段以防目录穿越攻击。路径配置的解析采用继承模型newPath()path.go先复制pathDefaults再用当前路径的配置逐字段覆盖copyStructFields因此每个paths条目都拥有完整、独立的生效配置。此外Validate()会检查all、all_others、~^.*$三个别名不能同时出现conf.go。完整配置示例组合实战以下示例综合了拉流、推流、录制、转发与认证的常见组合logLevel: info logDestinations: [stdout, file] logFile: /var/log/mediamtx.log authMethod: internal authInternalUsers: - user: any pass: permissions: - action: publish - action: read path: ~^public/.* - user: admin pass: secret permissions: - action: api - action: metrics api: true metrics: true rtsp: true rtspTransports: [tcp] hls: true hlsVariant: fmp4 webrtc: true pathDefaults: record: false recordPath: ./recordings/%path/%Y-%m-%d_%H-%M-%S-%f paths: # 从网络摄像头拉流 cam_front: source: rtsp://user:pass192.168.1.100:554/stream1 sourceOnDemand: true record: true # 拉取后同时转发到两个目的地 uplink: source: rtmp://ingest.example.com/live/camera1 forward: - dest: rtsps://backup.example.com/live/camera1 - dest: srt://relay.example.com:8890?streamidpublish/camera1 # 接受客户端推流并要求 SRT 推流口令 contributions: source: publisher srtPublishPassphrase: my-srt-passphrase maxReaders: 10 # 正则路径所有带前导前缀的相机 ~^ipcams/.*: source: publisher record: true # 兜底路径 all_others: source: publisher常见问题与排查建议启动失败并报参数错误Validate()会在启动时给出具体错误重点检查 2 的幂约束writeQueueSize、端口/地址依赖RTSP 各加密模式的地址族、WebRTC 三者必填其一等规则。配置改了没生效确认是写入--confpath指向的文件热加载依赖文件系统事件某些编辑器另存为替换文件的方式也已被 confwatcher.go 通过符号链接路径比较覆盖。想用环境变量覆盖数组/列表字符串数组用逗号分隔结构体列表用_0_、_1_索引前缀如MTX_AUTHINTERNALUSERS_0_USER。WebRTC 客户端连不上检查webrtcLocalUDPAddress/webrtcLocalTCPAddress/webrtcICEServers2与 NAT 穿透配置必要时用 STUN/TURN 并确认webrtcIPsFromInterfaces或webrtcAdditionalHosts让客户端能拿到可达地址。更多配置之外的实战细节可继续阅读 配置使用页、路径发布指南 与 路径读取指南各协议的服务端特性分别见 RTSP、WebRTC、SRT、RTMP 特性文档。【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考