DOCSEARCHbyAlgolia
Submit Docs

MediaMTX

repository·main·Indexed 12 days ago

https://github.com/bluenviron/mediamtx

A high-performance, zero-dependency live media server and proxy that acts as a media router. It supports publishing, reading, proxying, recording, and playback of real-time audio and video streams across protocols including WebRTC, RTSP, RTMP, SRT, Media-over-QUIC (MoQ), HLS, MPEG-TS, and RTP. It features automatic protocol conversion, a Control API, and Prometheus-compatible metrics.

Tokens
49.8K
Snippets
185
Records
229
Agent score
97%

What's inside MediaMTX

  1. Overview of MediaMTX features

    main

    MediaMTX is a zero-dependency live media server and media proxy designed as a 'media router'. It enables the publishing, reading, proxying, recording, and playback of real-time video and audio streams.

    Key capabilities include:

    • Multi-protocol support: Publish and read streams using Media-over-QUIC, SRT, WebRTC, RTSP, RTMP, HLS, MPEG-TS, and RTP.
    • Protocol Conversion: Automatically converts streams between different protocols.
    • Stream Management: Serve multiple streams on separate paths, support always-available streams (even when publishers are offline), and forward or proxy streams to other servers.
    • Recording & Playback: Record streams to disk in fMP4 or MPEG-TS formats and play them back.
    • Security: Authenticate users via internal mechanisms, HTTP, or JWT.
    • Extensibility & Control: Control the server via a Control API, run external commands (hooks) on client events (connect, disconnect, read, publish), and extract Prometheus-compatible metrics.
    • Portability: A single executable compatible with Linux, Windows, and macOS with no external dependencies required.

  2. Supported protocols for publishing live streams

    main

    MediaMTX supports publishing live streams using a wide variety of protocols. You can use these protocols to ingest media from clients, cameras, or servers into the MediaMTX server. Supported protocols include:

    • Media-over-QUIC (MoQ)
    • SRT (Secure Reliable Transport)
    • WebRTC
    • RTSP (Real-Time Streaming Protocol)
    • RTMP (Real-Time Messaging Protocol)
    • HLS (HTTP Live Streaming)
    • MPEG-TS
    • RTP (Real-time Transport Protocol)

  4. Supported protocols for reading live streams

    main

    MediaMTX allows clients to read live streams using several different protocols. Depending on your latency requirements and client capabilities, you can use:

    • Media-over-QUIC (MoQ): High-performance transport over QUIC.
    • SRT: Secure Reliable Transport, ideal for low-latency streaming over unpredictable networks.
    • WebRTC: Low-latency streaming suitable for web browsers and real-time communication.
    • RTSP: Real-Time Streaming Protocol, widely used in IP cameras and local networks.
    • RTMP: Real-Time Messaging Protocol, commonly used for ingest and legacy streaming.
    • HLS: HTTP Live Streaming, best for high-latency, high-scalability delivery over standard HTTP.

  6. How absolute timestamps are routed in HLS

    main

    When useAbsoluteTimestamp is enabled, MediaMTX routes absolute timestamps in HLS by inserting an #EXT-X-PROGRAM-DATE-TIME tag before each segment.

    The value provided in #EXT-X-PROGRAM-DATE-TIME corresponds to the absolute timestamp of the first frame of that segment. To find the absolute timestamp of subsequent frames within the same segment, you must sum the #EXT-X-PROGRAM-DATE-TIME value with the frame's relative timestamp.

    #EXTM3U
#EXT-X-VERSION:9
#EXT-X-MEDIA-SEQUENCE:20
#EXT-X-TARGETDURATION:2
#EXT-X-PROGRAM-DATE-TIME:2015-02-05T01:02:00Z
#EXTINF:2,
segment1.mp4
#EXT-X-PROGRAM-DATE-TIME:2015-02-05T01:04:00Z
#EXTINF:2,
segment2.mp4

  7. Implement horizontal scalability with Read Replicas

    main

    To handle high volumes of readers without degrading performance, you can implement horizontal scalability using Read Replicas.

    In this architecture:

    1. Origin Instance: A single MediaMTX instance where all publishers send their streams.
    2. Read Replicas: Multiple MediaMTX instances that pull streams from the Origin via proxy paths and serve them to end-users.
    3. Load Balancer: Distributes user connections across the available Read Replicas.

    Configuration Requirements

    For Read Replicas:

    • Configure proxy paths to point to the Origin instance.
    • If using WebRTC, you must:
      • Disable webrtcLocalUDPAddress and webrtcLocalTCPAddress.
      • Enable a STUN server (e.g., stun:stun.l.google.com:19302).

    For Load Balancers:

    • RTSP, RTMP, SRT: Use a Layer 4 (L4) Load Balancer.
    • HLS, WebRTC: Use a Layer 7 (L7) Load Balancer with sticky sessions enabled. Sticky sessions are mandatory because a single HLS or WebRTC session consists of multiple HTTP requests that must reach the same replica.

  8. Understand the MediaMTX architecture and network interactions

    main

    MediaMTX operates as a central media server that manages stream ingestion, distribution, and storage. Its network behavior can be categorized into four main interaction types:

    1. Stream Ingestion (Pulling): MediaMTX acts as a client to pull streams from external sources defined in your configuration.
    2. Stream Distribution (Publishing/Reading): It exposes servers supporting multiple protocols (RTSP, RTMP, WebRTC, SRT, HLS) to allow clients to publish to or read from paths.
    3. Playback: It exposes a playback server specifically for reading streams that have been stored on disk.
    4. Administrative Services: It exposes services for monitoring and management, including metrics, pprof, and the Control API.

    Internally, the system is organized around:

    • Path Manager: Handles path management, authentication, and linking clients to specific paths.
    • Paths: The core unit of organization. Each path contains a single stream (provided by one publisher or one external source) which is then broadcast to multiple readers.
    • Recorder: Manages the process of saving streams to disk.

  9. Scale HLS delivery using a CDN

    main

    To reduce the load on your MediaMTX server and handle high viewer counts, you can place a Content Delivery Network (CDN) in front of the HLS server. The CDN caches files and serves requests, freeing the origin server from most user traffic.

    Key Considerations

    • Protocol Support: This method only works for the HLS protocol.
    • Latency: Low-Latency HLS playlists cannot be cached and will always hit the origin. To ensure effective caching, it is recommended to disable the Low-Latency HLS variant.
    • Authentication: Standard MediaMTX authentication is bypassed. The CDN must enforce its own authentication, or streams will be publicly accessible via the CDN URL.
    • Security: To prevent unauthorized access to the origin, MediaMTX requires the CDN to inject a secret token in the Authorization: Bearer header. This token must match the hlsCDNSecret configured in MediaMTX.

  11. How absolute timestamps are routed in RTSP and WebRTC

    main

    In RTSP and WebRTC, absolute timestamps are routed using periodic RTCP sender reports. These reports contain a reference absolute timestamp (NTP timestamp) and a reference relative timestamp (RTP timestamp).

    To calculate the absolute timestamp of a specific frame, use the following formula:

    frame_abs_timestamp = ref_ntp_timestamp + (frame_rtp_timestamp - ref_rtp_timestamp) / clock_rate

    Where:

    • ref_ntp_timestamp: The NTP timestamp from the RTCP sender report.
    • ref_rtp_timestamp: The RTP timestamp from the RTCP sender report.
    • frame_rtp_timestamp: The RTP timestamp shipped with the individual frame.
    • clock_rate: The clock rate of the stream.
    frame_abs_timestamp = ref_ntp_timestamp + (frame_rtp_timestamp - ref_rtp_timestamp) / clock_rate

  12. Use RTSP HTTP tunneling

    main

    In environments with strict firewalls or mandatory API gateways that only allow HTTP, RTSP can be tunneled inside HTTP. MediaMTX handles these connections automatically without extra configuration.

    Supported tunneling variants:

    • RTSP over WebSocket: More efficient; requires WebSocket support from the gateway/firewall.
    • RTSP over HTTP: Older variant; works in more restrictive environments.

    To read a stream from an external RTSP server using HTTP tunneling, use the following URI schemes in your MediaMTX configuration:

    • rtsp+http://...
    • rtsps+http://...
    • rtsp+ws://...
    • rtsps+ws://...
    paths:
  source: rtsp+http://standard-rtsp-url