# bluenviron/mediamtx architecture

> Architecture diagram of the GitHub repository bluenviron/mediamtx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bluenviron/mediamtx
- Repository: https://github.com/bluenviron/mediamtx

## Overview

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`](https://github.com/bluenviron/mediamtx/blob/main/main.go) (Main), [`internal/core`](https://github.com/bluenviron/mediamtx/tree/main/internal/core) (Core), [`internal/metrics`](https://github.com/bluenviron/mediamtx/tree/main/internal/metrics) (Metrics), [`internal/auth`](https://github.com/bluenviron/mediamtx/tree/main/internal/auth) (Auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.go]"]
end

subgraph group_dataplane["Data Plane"]
  node_core{{"Core<br/>router"}}
  node_stream{{"Stream<br/>media model"}}
  node_unit["Units<br/>payload codecs"]
  node_staticsources["Static Sources<br/>source adapters"]
end

subgraph group_network["Network IO"]
  node_servers_rtsp["RTSP<br/>server"]
  node_servers_rtmp["RTMP<br/>server"]
  node_servers_srt["SRT<br/>server"]
  node_servers_webrtc["WebRTC<br/>server"]
  node_servers_hls["HLS<br/>server"]
  node_protocols["Protocols<br/>wire helpers"]
end

subgraph group_storage["Storage"]
  node_recorder["Recorder<br/>capture pipeline"]
  node_recordstore[("Record Store<br/>segment store")]
  node_recordcleaner(("Record Cleaner<br/>retention"))
  node_playback["Playback<br/>serve recordings"]
end

subgraph group_control["Control Plane"]
  node_api["Control API<br/>admin api"]
  node_metrics(("Metrics<br/>telemetry"))
end

subgraph group_support["Support"]
  node_conf["Config<br/>schema"]
  node_confwatcher(("Config Watcher<br/>reload"))
  node_auth(("Auth<br/>access policy"))
  node_hooks(("Hooks<br/>events"))
  node_externalcmd(("External Cmd<br/>process runner"))
  node_logger(("Logger<br/>logging"))
end

node_main -->|"loads"| node_conf
node_main -->|"sets up"| node_logger
node_main -->|"wires"| node_auth
node_main -->|"starts"| node_core
node_main -->|"starts"| node_servers_rtsp
node_main -->|"starts"| node_servers_rtmp
node_main -->|"starts"| node_servers_srt
node_main -->|"starts"| node_servers_webrtc
node_main -->|"starts"| node_servers_hls
node_main -->|"enables"| node_recorder
node_main -->|"enables"| node_playback
node_main -->|"exposes"| node_api
node_main -->|"exposes"| node_metrics
node_main -->|"wires"| node_hooks
node_main -->|"monitors"| node_confwatcher
node_core -->|"routes to"| node_stream
node_core -->|"falls back to"| node_staticsources
node_core -->|"emits"| node_hooks
node_servers_rtsp -->|"uses"| node_protocols
node_servers_rtmp -->|"uses"| node_protocols
node_servers_srt -->|"uses"| node_protocols
node_servers_webrtc -->|"uses"| node_protocols
node_servers_hls -->|"uses"| node_protocols
node_servers_rtsp -->|"publishes/reads"| node_core
node_servers_rtmp -->|"publishes/reads"| node_core
node_servers_srt -->|"publishes/reads"| node_core
node_servers_webrtc -->|"publishes/reads"| node_core
node_servers_hls -->|"reads"| node_core
node_staticsources -->|"injects"| node_core
node_recorder -->|"persists to"| node_recordstore
node_recordcleaner -->|"prunes"| node_recordstore
node_playback -->|"reads from"| node_recordstore
node_api -->|"mutates"| node_conf
node_api -->|"inspects"| node_core
node_api -->|"inspects"| node_recordstore
node_metrics -->|"observes"| node_core
node_metrics -->|"observes"| node_servers_rtsp
node_metrics -->|"observes"| node_servers_rtmp
node_metrics -->|"observes"| node_servers_srt
node_metrics -->|"observes"| node_servers_webrtc
node_hooks -->|"executes"| node_externalcmd
node_auth -->|"gates"| node_servers_rtsp
node_auth -->|"gates"| node_servers_rtmp
node_auth -->|"gates"| node_servers_srt
node_auth -->|"gates"| node_servers_webrtc
node_auth -->|"gates"| node_api
node_stream -->|"encodes"| node_unit

click node_main "https://github.com/bluenviron/mediamtx/blob/main/main.go"
click node_conf "https://github.com/bluenviron/mediamtx/tree/main/internal/conf"
click node_confwatcher "https://github.com/bluenviron/mediamtx/tree/main/internal/confwatcher"
click node_auth "https://github.com/bluenviron/mediamtx/tree/main/internal/auth"
click node_core "https://github.com/bluenviron/mediamtx/tree/main/internal/core"
click node_stream "https://github.com/bluenviron/mediamtx/tree/main/internal/stream"
click node_unit "https://github.com/bluenviron/mediamtx/tree/main/internal/unit"
click node_servers_rtsp "https://github.com/bluenviron/mediamtx/tree/main/internal/servers/rtsp"
click node_servers_rtmp "https://github.com/bluenviron/mediamtx/tree/main/internal/servers/rtmp"
click node_servers_srt "https://github.com/bluenviron/mediamtx/tree/main/internal/servers/srt"
click node_servers_webrtc "https://github.com/bluenviron/mediamtx/tree/main/internal/servers/webrtc"
click node_servers_hls "https://github.com/bluenviron/mediamtx/tree/main/internal/servers/hls"
click node_protocols "https://github.com/bluenviron/mediamtx/tree/main/internal/protocols"
click node_staticsources "https://github.com/bluenviron/mediamtx/tree/main/internal/staticsources"
click node_recorder "https://github.com/bluenviron/mediamtx/tree/main/internal/recorder"
click node_recordstore "https://github.com/bluenviron/mediamtx/tree/main/internal/recordstore"
click node_recordcleaner "https://github.com/bluenviron/mediamtx/tree/main/internal/recordcleaner"
click node_playback "https://github.com/bluenviron/mediamtx/tree/main/internal/playback"
click node_api "https://github.com/bluenviron/mediamtx/tree/main/internal/api"
click node_metrics "https://github.com/bluenviron/mediamtx/tree/main/internal/metrics"
click node_hooks "https://github.com/bluenviron/mediamtx/tree/main/internal/hooks"
click node_externalcmd "https://github.com/bluenviron/mediamtx/tree/main/internal/externalcmd"
click node_logger "https://github.com/bluenviron/mediamtx/tree/main/internal/logger"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main toneBlue
class node_core,node_stream,node_unit,node_staticsources toneAmber
class node_servers_rtsp,node_servers_rtmp,node_servers_srt,node_servers_webrtc,node_servers_hls,node_protocols toneMint
class node_recorder,node_recordstore,node_recordcleaner,node_playback toneRose
class node_api,node_metrics toneIndigo
class node_conf,node_confwatcher,node_auth,node_hooks,node_externalcmd,node_logger toneTeal
```

## Components

### Runtime

Process entrypoint and orchestration

- [Main](https://github.com/bluenviron/mediamtx/blob/main/main.go): entrypoint · Starts the long-running media router and wires subsystems together · `main.go`

### Data Plane

Stream routing and media flow

- [Core](https://github.com/bluenviron/mediamtx/tree/main/internal/core): router · Path management, source selection, and client attachment · `internal/core`
- [Stream](https://github.com/bluenviron/mediamtx/tree/main/internal/stream): media model · Canonical in-memory stream, tracks, and remux helpers · `internal/stream`
- [Units](https://github.com/bluenviron/mediamtx/tree/main/internal/unit): payload codecs · Codec payload and RTP/unit definitions used by stream adapters · `internal/unit`
- [Static Sources](https://github.com/bluenviron/mediamtx/tree/main/internal/staticsources): source adapters · Alternate live sources and source forwarding integrations · `internal/staticsources`

### Network IO

Protocol servers and wire helpers

- [RTSP](https://github.com/bluenviron/mediamtx/tree/main/internal/servers/rtsp): server · RTSP session server for publish and read flows · `internal/servers/rtsp`
- [RTMP](https://github.com/bluenviron/mediamtx/tree/main/internal/servers/rtmp): server · RTMP server for ingest and republishing · `internal/servers/rtmp`
- [SRT](https://github.com/bluenviron/mediamtx/tree/main/internal/servers/srt): server · SRT listener and session server · `internal/servers/srt`
- [WebRTC](https://github.com/bluenviron/mediamtx/tree/main/internal/servers/webrtc): server · WebRTC server for browser and peer connections · `internal/servers/webrtc`
- [HLS](https://github.com/bluenviron/mediamtx/tree/main/internal/servers/hls): server · HTTP HLS server for segmented playback · `internal/servers/hls`
- [Protocols](https://github.com/bluenviron/mediamtx/tree/main/internal/protocols): wire helpers · Lower-level transport, HTTP, TLS, websocket, and protocol adapters · `internal/protocols`

### Storage

Recording and playback

- [Recorder](https://github.com/bluenviron/mediamtx/tree/main/internal/recorder): capture pipeline · Writes live stream data into recording formats · `internal/recorder`
- [Record Store](https://github.com/bluenviron/mediamtx/tree/main/internal/recordstore): segment store · Persistent storage layout and segment metadata · `internal/recordstore`
- [Record Cleaner](https://github.com/bluenviron/mediamtx/tree/main/internal/recordcleaner): retention · Removes old recordings according to policy · `internal/recordcleaner`
- [Playback](https://github.com/bluenviron/mediamtx/tree/main/internal/playback): serve recordings · Serves recorded media back through HTTP-oriented endpoints · `internal/playback`

### Control Plane

Admin APIs and observability

- [Control API](https://github.com/bluenviron/mediamtx/tree/main/internal/api): admin api · REST control surface for paths, config, and protocol status · `internal/api`
- [Metrics](https://github.com/bluenviron/mediamtx/tree/main/internal/metrics): telemetry · Prometheus-style runtime and stream metrics · `internal/metrics`

### Support

Config, auth, hooks, and platform helpers

- [Config](https://github.com/bluenviron/mediamtx/tree/main/internal/conf): schema · Configuration model, defaults, and reload support · `internal/conf`
- [Config Watcher](https://github.com/bluenviron/mediamtx/tree/main/internal/confwatcher): reload · Watches configuration changes and reapplies them live · `internal/confwatcher`
- [Auth](https://github.com/bluenviron/mediamtx/tree/main/internal/auth): access policy · Internal users, request auth, and JWT-based access checks · `internal/auth`
- [Hooks](https://github.com/bluenviron/mediamtx/tree/main/internal/hooks): events · Lifecycle callbacks for connect, read, publish, and ready events · `internal/hooks`
- [External Cmd](https://github.com/bluenviron/mediamtx/tree/main/internal/externalcmd): process runner · Runs external commands triggered by hooks and events · `internal/externalcmd`
- [Logger](https://github.com/bluenviron/mediamtx/tree/main/internal/logger): logging · Structured logging and output destinations · `internal/logger`

## Connections

- 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
