MediaMTX 上手指南：5 分钟跑通八路协议的推流、拉流与录制-育师

MediaMTX 上手指南：5 分钟跑通八路协议的推流、拉流与录制

【免费下载链接】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

MediaMTX 是一个零依赖、单二进制运行的实时流媒体服务器，启动后同时开放 SRT、RTSP、RTMP、WebRTC、LL-HLS 等 8 路协议的收发端口，并自动完成协议间转换、录制与回放。适合想在几分钟内搭起一路流转接、监控分发或直播推流的开发者和运维。

它适合哪些场景

摄像机流多端分发：RTSP 摄像头推上来后，你用浏览器直接以 WebRTC 或 LL-HLS 方式观看，协议转换由服务器在内部完成，不需要自己写转接层。
直播留档与点播回放：开播同时把流写成 fMP4 或 MPEG-TS 分段，回看时通过内置的 HTTP 回放服务按时间段取流，可直接嵌进<video>标签。
流源中断时保持画面在线：开启alwaysAvailable后，发布端掉线期间服务器循环播放一个离线片段，观众端连接不断开，发布端恢复后无缝切回。
一路流分发到多个平台：用forward条目把同一路流以 SRT、RTSP、WHIP 等方式转发给其它服务器，或给 YouTube、Twitch 这类直播平台。

最快上手路径

不需要安装任何依赖，用 Docker 一条命令拉起服务，把常用端口映射出去：

docker run --rm -it \ -p 8554:8554 -p 1935:1935 \ -p 8888:8888 -p 8889:8889 \ -p 8189:8189/udp -p 8890:8890/udp \ bluenviron/mediamtx:1

Windows、macOS 或想快速验证时，从 Release 下载对应平台的单文件二进制，执行./mediamtx效果相同。启动后立即推流——以 FFmpeg 把一个 MP4 循环作为 RTSP 源推入路径mystream：

ffmpeg -re -stream_loop -1 -i file.mp4 -c copy \ -f rtsp rtsp://localhost:8554/mystream

再开一个终端拉流验证：

vlc --network-caching=50 rtsp://localhost:8554/mystream

此时路径mystream已同时在 8 个协议端口上可用，用http://localhost:8888/mystream/playlist.m3u8这类地址就能以其它协议读取同一路流。完整的默认配置项都写在 mediamtx.yml 里，每项都有注释；也可以不用改文件，用MTX_参数名形式的环境变量临时覆盖，例如MTX_RTSPTRANSPORTS=tcp ./mediamtx。

按任务拆解：你能用它做什么

推流与播放

发布端可以是 FFmpeg、OBS、GStreamer、浏览器（WebRTC/WHIP）、Raspberry Pi 摄像头，甚至直接拉另一路远程流当源。读流端同理，VLC、FFmpeg、浏览器都行。关键参数是pathDefaults.source：默认值publisher表示路径由客户端推流提供；把它改成rtsp://myurl就变成服务器主动去拉。

录制与回放

在配置文件里给路径或全局默认值打开录制开关，流会被按分段写到磁盘：

pathDefaults: record: yes recordFormat: fmp4 recordSegmentDuration: 1h recordDeleteAfter: 1d

关键参数recordDeleteAfter控制过期自动清理，设为0s则永久保留。回放服务通过playback: yes打开（默认监听 9996 端口）：/list?path=mystream返回该路径所有可回看的时间段 JSON，/get返回 fMP4 流，可直接作为<video>的 src；个别播放器不兼容时追加format=mp4输出标准 MP4。若想同步上云，把 rclone 命令挂到runOnRecordSegmentComplete钩子即可。

协议转换与压缩

同一路流推入后，所有协议端口天然互通，这步零配置。若需要转码（比如压到 600k 带宽），用runOnReady钩子在路径上线时拉起一个 FFmpeg 进程，把它编码后的结果再推回服务器的另一条路径；runOnReadyRestart: yes保证崩溃后自动重启。

转发与代理

转发：给路径加forward条目，dest写目标地址即可，如srt://host:port?streamid=...或whip://host:port/...。代理：把paths.mypath.source指向上游rtsp://地址，本服务器就变成一个透明的多级中转节点。

踩坑与调优

WebRTC 握手卡住，浏览器拿不到流原因：ICE 协商时服务器没有告知客户端可被它访问的地址。解法：把客户端能连到你的公网 IP 或内网地址填进webrtcAdditionalHosts，并确保容器或 NAT 把 UDP 8189 转发到服务器；若防火墙拦 UDP，设置webrtcLocalTCPAddress: :8189改走 TCP 兜底。

H265 或含 B 帧的 H264 推给 WebRTC 后浏览器播不了原因：多数浏览器不支持 WebRTC 读 H265，且 B 帧不在 WebRTC 规范内、被浏览器刻意排除。解法：推流前用 FFmpeg 转成无 B 帧的 H264 baseline profile 加 Opus 音频（-c:v libx264 -pix_fmt yuv420p、-c:a libopus），再推入服务器。

Docker 里 RTSP 的 UDP 传输报地址错误原因：Docker 网络栈会改写入站 UDP 包的真实源地址，导致 RTSP 会话校验失败。解法：设MTX_RTSPTRANSPORTS=tcp只用 TCP 传输，或给容器加--network=host绕过网络栈。

改动以上任何配置项后无需重启——服务器会热重载配置文件并在可能时不踢断现有连接。

需要说明边界：MediaMTX 本身只做流的接收、路由、录制，不做转码，压缩转码要靠钩子里的 FFmpeg 完成；规模化扩展则是按路径分片跑多个实例。下一步建议打开 docs/ 查一遍完整配置项，再给测试路径加上record: yes，用 Control API（默认 9997 端口）确认流的状态。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考