How bluenviron/mediamtx works
MediaMTX is a single Go executable that acts as a media router: it accepts media on multiple ingress protocols, normalizes it into an internal stream model, and then serves, records, forwards, proxies, or plays it back through other protocols.
1. Process entrypoint and lifecycle
The runtime starts from main.go, which wires configuration, logging, authentication, protocol servers, recording/playback, metrics, and the control API into one long-running process. The repo is organized so most functionality lives under internal/, with a clear split between orchestration, protocol adapters, and media-state management.
2. Core routing layer
internal/core is the central coordination boundary. It manages paths, path state, source selection, on-demand startup, and client attachment/detachment. This is where publishers and readers are matched to a path, and where the system decides whether a stream is live, always-available, proxied, or sourced from another origin.
3. Internal media model
internal/stream holds the canonical stream representation used across protocols. It tracks media tracks, formats, RTP/unit handling, sub-streams, and offline placeholder media. This layer decouples protocol-specific packet handling from the rest of the system so the same stream can be republished as RTSP, RTMP, HLS, WebRTC, or recorded to disk.
4. Protocol servers as boundaries
The internal/servers tree contains the main network-facing servers for RTSP, RTMP, SRT, WebRTC, and HLS. Each server package handles socket/listener setup, session management, and protocol-specific handshake/authentication, then bridges into the core stream model. These servers are the primary ingress and egress points for live media.
5. Protocol conversion and transport helpers
internal/protocols contains lower-level protocol machinery and conversion helpers: HTTP handling, TLS config, UDP/Unix listeners, RTSP/RTMP/HLS/MPEG-TS/WebRTC/WHIP adapters, and websocket support. These packages handle the wire-level details that sit underneath the higher-level servers.
6. Publish and read flows
Incoming publishers use protocol-specific “from_stream” or server session logic to push media into a path. Readers use “to_stream” logic to pull from the internal stream and repacketize it for the requested output protocol. The architecture is therefore a many-in/many-out router, not a single-protocol server.
7. Static sources, forwarding, and proxying
internal/staticsources provides alternate sources that can feed a path without a live publisher, including RTSP, RTMP, SRT, HLS, RTP, WebRTC, and Raspberry Pi camera sources. Alongside internal/core/source_redirect.go, this supports on-demand publishing, source forwarding, and proxy-like behavior where MediaMTX relays or originates streams from external endpoints.
8. Recording and playback subsystem
Recording is handled by internal/recorder and persisted through internal/recordstore, with cleanup in internal/recordcleaner. Recorded media is stored as fMP4 or MPEG-TS segments, and internal/playback serves those recordings back through HTTP-oriented playback endpoints. This is a separate storage pipeline from live streaming, but it is fed from the same internal stream data.
9. Authentication and access policy
internal/auth and related config types in internal/conf implement internal users, HTTP-based auth, and JWT-based auth. Access control is applied across publish/read/control operations, so authentication sits as a cross-cutting gate in front of the protocol servers and the control API.
10. Configuration and hot reload
internal/conf defines the full configuration schema, including paths, global options, auth, logging, recording, RTSP transport/auth, WebRTC ICE servers, and more. internal/confwatcher supports reloading configuration without dropping existing clients, which is a major operational feature of the system.
11. Control plane and observability
The Control API lives under internal/api and is backed by the OpenAPI definition in api/openapi.yaml. Operational endpoints also include Prometheus-compatible metrics (internal/metrics), pprof (internal/pprof), and structured logging (internal/logger). These expose the state of the router rather than media payloads themselves.
12. Hooks and external command integration
internal/hooks and internal/externalcmd let the server invoke external programs on lifecycle events such as connect, disconnect, read, publish, init, and ready. This is an integration boundary for automation, notifications, or custom side effects around stream events.
13. Platform and deployment shape
The project is designed as a portable standalone binary, with Docker images for standard Linux, Raspberry Pi, and FFmpeg-enabled variants. There is no separate frontend or service mesh; the architecture is centered on one process that embeds all protocol servers and media management logic.
14. Supporting subsystems
Additional packages cover certificate loading, network restriction, resource limits, error/counter dumping, NTP estimation, and test/e2e harnesses. These are supporting concerns around reliability and portability, not separate product tiers, but they matter for understanding deployment and runtime behavior.
Overall, the key architectural diagram should show a central stream-routing core fed by multiple protocol ingress points, with parallel outputs for reading, recording, playback, control, metrics, and hooks, all configured from a hot-reloadable config layer.
Main entry points: main.go Main · core Core · metrics Metrics · auth Auth
Components 23
Runtime
Process entrypoint and orchestration
- Main · Starts the long-running media router and wires subsystems together
main.go
Data Plane
Stream routing and media flow
- Core · Path management, source selection, and client attachment
internal/core - Stream · Canonical in-memory stream, tracks, and remux helpers
internal/stream - Units · Codec payload and RTP/unit definitions used by stream adapters
internal/unit - Static Sources · Alternate live sources and source forwarding integrations
internal/staticsources
Network IO
Protocol servers and wire helpers
- RTSP · RTSP session server for publish and read flows
internal/servers/rtsp - RTMP · RTMP server for ingest and republishing
internal/servers/rtmp - SRT · SRT listener and session server
internal/servers/srt - WebRTC · WebRTC server for browser and peer connections
internal/servers/webrtc - HLS · HTTP HLS server for segmented playback
internal/servers/hls - Protocols · Lower-level transport, HTTP, TLS, websocket, and protocol adapters
internal/protocols
Storage
Recording and playback
- Recorder · Writes live stream data into recording formats
internal/recorder - Record Store · Persistent storage layout and segment metadata
internal/recordstore - Record Cleaner · Removes old recordings according to policy
internal/recordcleaner - Playback · Serves recorded media back through HTTP-oriented endpoints
internal/playback
Control Plane
Admin APIs and observability
- Control API · REST control surface for paths, config, and protocol status
internal/api - Metrics · Prometheus-style runtime and stream metrics
internal/metrics
Support
Config, auth, hooks, and platform helpers
- Config · Configuration model, defaults, and reload support
internal/conf - Config Watcher · Watches configuration changes and reapplies them live
internal/confwatcher - Auth · Internal users, request auth, and JWT-based access checks
internal/auth - Hooks · Lifecycle callbacks for connect, read, publish, and ready events
internal/hooks - External Cmd · Runs external commands triggered by hooks and events
internal/externalcmd - Logger · Structured logging and output destinations
internal/logger
Connections 47
- Main → Config: loads · Reads the configuration schema and runtime settings
- Main → Logger: sets up · Initializes structured logging before subsystem startup
- Main → Auth: wires · Installs access control for publish/read/control operations
- Main → Core: starts · Boots the central routing and path manager
- Main → RTSP: starts · Launches RTSP ingress/egress server
- Main → RTMP: starts · Launches RTMP ingress/egress server
- Main → SRT: starts · Launches SRT listener/server
- Main → WebRTC: starts · Launches WebRTC server
- Main → HLS: starts · Launches HLS server
- Main → Recorder: enables · Connects recording pipeline to live streams
- Main → Playback: enables · Exposes recorded media playback
- Main → Control API: exposes · Starts the control API
- Main → Metrics: exposes · Publishes operational metrics
- Main → Hooks: wires · Installs lifecycle hooks
- Main → Config Watcher: monitors · Supports hot reload of configuration
- Core → Stream: routes to · Attaches publishers and readers to canonical stream state
- Core → Static Sources: falls back to · Selects alternate or on-demand sources when needed
- Core → Hooks: emits · Triggers lifecycle events around paths and clients
- RTSP → Protocols: uses · Relies on protocol helpers and transport primitives
- RTMP → Protocols: uses · Relies on protocol helpers and transport primitives
- SRT → Protocols: uses · Relies on protocol helpers and transport primitives
- WebRTC → Protocols: uses · Relies on protocol helpers and transport primitives
- HLS → Protocols: uses · Relies on protocol helpers and transport primitives
- RTSP → Core: publishes/reads · Bridges RTSP sessions into the core router
- RTMP → Core: publishes/reads · Bridges RTMP sessions into the core router
- SRT → Core: publishes/reads · Bridges SRT sessions into the core router
- WebRTC → Core: publishes/reads · Bridges WebRTC sessions into the core router
- HLS → Core: reads · Serves HLS output from internal stream state
- Static Sources → Core: injects · Provides non-live or forwarded sources into paths
- Recorder → Record Store: persists to · Writes recorded segments and metadata
- Record Cleaner → Record Store: prunes · Deletes expired or obsolete recordings
- Playback → Record Store: reads from · Loads recordings for serving
- Control API → Config: mutates · Reads and updates runtime configuration state
- Control API → Core: inspects · Exposes path and stream status from the router
- Control API → Record Store: inspects · Exposes recording inventory and metadata
- Metrics → Core: observes · Reports router and path state metrics
- Metrics → RTSP: observes · Reports server activity metrics
- Metrics → RTMP: observes · Reports server activity metrics
- Metrics → SRT: observes · Reports server activity metrics
- Metrics → WebRTC: observes · Reports server activity metrics
- Hooks → External Cmd: executes · Runs external processes on lifecycle events
- Auth → RTSP: gates · Authorizes RTSP publish/read operations
- Auth → RTMP: gates · Authorizes RTMP publish/read operations
- Auth → SRT: gates · Authorizes SRT publish/read operations
- Auth → WebRTC: gates · Authorizes WebRTC publish/read operations
- Auth → Control API: gates · Authorizes control API requests
- Stream → Units: encodes · Uses codec and RTP/unit definitions for remuxing