MediaMTX 流媒体录制实战指南fMP4/MPEG-TS 分段录制配置、生命周期管理与 rclone 远程上传【免费下载链接】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 的录制Record功能如何把推送到服务器的实时视频/音频流写入磁盘形成可回放的分段文件并自动化上传到远程存储。读完本文你将掌握record系列参数的完整语义与默认值、录制文件的命名规则、分段与自动清理机制、录制生命周期钩子以及基于 rclone 的云端归档方案。支持的文件容器与编解码器MediaMTX 录制模块位于 internal/recorder 包。它不转码而是把到达服务器的流原样封装进以下两种容器之一因此支持的编解码器取决于容器类型容器支持的编解码器fMP4fragmented MP4.mp4视频AV1、VP9、H265、H264、MPEG-4 VideoH263、Xvid、MPEG-1/2 Video、M-JPEG音频Opus、MPEG-4 AudioAAC、MPEG-1/2 AudioMP3、AC-3、G711PCMA、PCMU、LPCMMPEG-TS.ts视频H265、H264、MPEG-4 VideoH263、Xvid、MPEG-1/2 Video音频Opus、MPEG-4 AudioAAC、MPEG-1/2 AudioMP3、AC-3从源码看fMP4 封装逻辑在 internal/recorder/format_fmp4.go它为每个媒体轨道分配自增 ID逐帧处理 H264/H265通过 DTS 提取器还原解码时间戳、把 NAL 转为 AVCC 布局、解析 AV1/VP9 关键帧与参数变化updateCodecParams、从 AC-3/MP3 帧头抽取采样率与声道数等。MPEG-TS 侧则由 internal/recorder/format_mpegts.go 负责。两点值得注意的边界行为见format_fmp4.go遇到不支持的轨道如 VP8、G722会被跳过若所有轨道都不支持则直接放弃录制并记录警告no supported tracks found, skipping recording含 B 帧的 MPEG-4/MPEG-1/2 Video 流暂时不支持源码会报...with B-frames are not supported (yet)。开启录制最小配置录制是按路径path级别控制的。在配置文件 mediamtx.yml 的pathDefaults中把record设为yes即可为所有路径开启录制pathDefaults: # Record streams to disk. record: yes若只想录制某一路径可把它放在paths下单独覆盖paths: camera1: record: yesrecord参数对应的配置结构体在 internal/conf/path.go其默认值为false即默认不录制。录制参数详解下面是一份完整的录制配置同时是 mediamtx.yml 中实际给出的默认值建议放到pathDefaults下作为全局限定或按路径覆盖pathDefaults: # Record streams to disk. record: yes # Path of recording segments. # Extension is added automatically. # Available variables are %path (path name), %Y %m %d (year, month, day), # %H %M %S (hours, minutes, seconds), %f (microseconds), %z (time zone), %s (unix epoch). recordPath: ./recordings/%path/%Y-%m-%d_%H-%M-%S-%f # Format of recorded segments. # Available formats are fmp4 (fragmented MP4) and mpegts (MPEG-TS). recordFormat: fmp4 # fMP4 segments are concatenation of small MP4 files (parts), each with this duration. # MPEG-TS segments are concatenation of 188-bytes packets, flushed to disk with this period. # When a system failure occurs, the last part gets lost. # Therefore, the part duration is equal to the RPO (recovery point objective). recordPartDuration: 1s # This prevents RAM exhaustion. recordMaxPartSize: 50M # Minimum duration of each segment. recordSegmentDuration: 1h # Delete segments after this timespan. # Set to 0s to disable automatic deletion. recordDeleteAfter: 1d各参数语义参数默认值说明recordfalse是否把流写入磁盘。recordPath./recordings/%path/%Y-%m-%d_%H-%M-%S-%f分段文件的保存路径模板扩展名.mp4或.ts由程序自动追加。支持%path、%Y %m %d、%H %M %S、%f、%z、%s等时间变量见下文文件命名模板。recordFormatfmp4封装格式仅允许fmp4或mpegts。该枚举定义在 internal/conf/record_format.go解析时会校验非法取值。recordPartDuration1s段内小块时长fMP4 的每个 part 是一个小 MP4 文件MPEG-TS 则按此周期把 188 字节 TS 包刷盘。系统故障时最后一个 part 会丢失因此该值就是 RPO恢复点目标——取值越小故障丢数据越少但磁盘 I/O 越频繁。recordMaxPartSize50M单个 part 的最大字节数防止内存耗尽part 数据先在内存缓冲见 internal/recorder/format_fmp4_part.go。recordSegmentDuration1h每个分段文件的最小时长。达到该时长即封口、开启新段。注意源码限制最大不能超过 1 天见下文校验规则。recordDeleteAfter1d分段文件保留时长超过即被后台清理器自动删除设为0s关闭自动删除。以上默认值定义在 internal/conf/path.go 的setDefaults中与配置文件保持一致。参数校验规则配置加载时会做严格校验见 internal/conf/path.go常见错误会导致启动失败recordPath必须包含%pathrecordPath必须包含%s或者完整的%Y、%m、%d、%H、%M、%S六件套保证文件名里能还原出精确时间若启用了 playback 回放服务器recordPath还必须包含%f微秒以避免分段重名recordSegmentDuration最大为1 天防止 MP4mvhd时长字段溢出recordDeleteAfter若不为 0则不能小于recordSegmentDuration否则文件刚生成就会被删。文件命名模板与时间变量recordPath中的变量由 internal/recordstore/path.go 的Path.Encode在创建分段时展开变量含义示例%path路径名camera1%Y%m%d年、月、日20260912%H%M%S时、分、秒070646%f微秒6 位123456%z时区偏移0800/Z%sUnix 纪元秒1757632006扩展名由PathAddExtension自动追加internal/recordstore/path.gofMP4 →.mp4MPEG-TS →.ts。默认模板./recordings/%path/%Y-%m-%d_%H-%M-%S-%f会生成类似./recordings/camera1/2026-09-12_07-06-46-123456.mp4的文件。建议始终保留%f它保证同一秒内开启的多个分段不会相互覆盖。注意路径名本身在 internal/conf/path.go 中被限制为字母数字及_ - / .且不允许.与..段从源头阻止了目录穿越攻击FindSegments供回放与清理使用还会二次校验。分段、落盘与自动清理的底层机制分段如何产生录制核心在 internal/recorder/recorder.go每个路径持有一个Recorder它内部串行创建recorderInstance见 internal/recorder/recorder_instance.go。实例在流开始时创建按recordSegmentDuration推进分段fMP4一个 segment 是多个 MP4 part 的拼接internal/recorder/format_fmp4_segment.go。首个 part 落盘时会写入含轨道信息的 init 头含mtxi用户数据 box记录 streamID、分段序号、DTS 与 NTPsegment 封口时回填总时长以加速回放服务器MPEG-TSsegment 是 188 字节 TS 包的连续文件按recordPartDuration周期刷盘internal/recorder/format_mpegts_segment.go。若录制实例意外退出Recorder.run会等待约 2 秒后自动重建见 internal/recorder/recorder.go。过期分段自动清理recordDeleteAfter由 internal/recordcleaner/cleaner.go 中的后台清理器执行。它会周期性扫描所有含分段文件的路径删除早于当前时间 −recordDeleteAfter的分段并顺带清掉空目录。清理间隔取所有路径recordDeleteAfter的一半上限 30 分钟见cleanInterval()internal/recordcleaner/cleaner.go。录制生命周期钩子文件级事件MediaMTX 为录制提供两个专用钩子可用于通知外部系统或驱动上传任务pathDefaults: # 分段文件创建时执行文件刚开始写入 runOnRecordSegmentCreate: /path/to/your-script.sh # 分段文件封口完成时执行文件完整可用 runOnRecordSegmentComplete: /path/to/your-script.sh钩子执行时可用的环境变量见 mediamtx.ymlMTX_PATH路径名MTX_SEGMENT_PATH分段文件的完整路径MTX_SEGMENT_DURATION分段时长仅runOnRecordSegmentCompleteRTSP_PORTRTSP 服务器端口G1, G2, ...若路径名是正则表达式则包含其分组捕获。对应底层回调解耦在 internal/recorder/recorder.go 的OnSegmentCreateFunc/OnSegmentCompleteFunc中并由分段 close 时统一触发。runOnRecordSegmentCreate是了解开始写入的时机runOnRecordSegmentComplete则保证脚本运行时文件已完整落盘。远程上传MediaMTX × rclone 归档方案官方推荐用rclone命令行文件同步工具支持 S3、FTP、SMB、Google Drive 等海量存储服务把录制文件同步到远端。完整流程如下安装 rclone并确保rclone命令在系统 PATH 中。配置远程存储rclone config按交互提示创建配置例如命名为myconfig指向你的对象存储 / FTP / 网盘。接入两个钩子放在pathDefaults下pathDefaults: # 启动时全量同步一次用于补传崩溃期间遗留的段。 # 把 myconfig 替换为你的 rclone 配置名。 runOnInit: rclone sync -v ./recordings myconfig:/my-path/recordings # 每封口一个分段就增量同步。 # --min-age1ms 避免与正在写入的文件产生竞态。 runOnRecordSegmentComplete: rclone sync -v --min-age1ms ./recordings myconfig:/my-path/recordings要点说明runOnInit在 MediaMTX 启动、路径初始化时执行保证崩溃恢复后遗留分段也能被补传参考 mediamtx.yml 的runOnInit语义进程关闭时命令会被 SIGINT 终止runOnRecordSegmentComplete在分段封口后执行此时文件已完整配合--min-age1ms可避免把正在写入的 part 误传若希望上传后删除本地文件把rclone sync换成rclone move即可move 会在同步成功后移除源文件。提示若开启了recordDeleteAfter自动清理而你又用rclone move删除本地文件请确认清理器与上传节奏不会互相干扰——建议本地保留策略略长于上传完成时间或依赖远端存储自身的生命周期规则来归档。录完怎么用playback 回放录制不是为了存档而存档——配合 playback 回放服务器录制的分段可以通过 HTTP 直接按时间区间点播。全局配置见 mediamtx.yml包含playback、playbackAddress、playbackEncryption、playbackServerKey/Cert、playbackAllowOrigins等参数。开启前请确保recordPath已包含%f配置校验会强制要求。完整的下载与播放用法见 playback 回放指南。小结MediaMTX 的录制功能以分段文件为核心recordPath决定文件落点与命名、recordPartDuration/recordMaxPartSize控制内存与故障丢帧粒度、recordSegmentDuration决定文件切分节奏、recordDeleteAfter驱动自动清理再叠加runOnRecordSegmentCreate/runOnRecordSegmentComplete钩子即可构建录制 → 上传 → 归档的完整链路。全部可用录制参数以官方配置文件 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/mediamtx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考