If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/bluenviron/mediamtx shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live bluenviron/mediamtx repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bluenviron/mediamtx.

What it runs against: a local clone of bluenviron/mediamtx — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in bluenviron/mediamtx | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bluenviron/mediamtx. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bluenviron/mediamtx.git
#   cd mediamtx
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of bluenviron/mediamtx and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bluenviron/mediamtx(\\.git)?\\b" \\
  && ok "origin remote is bluenviron/mediamtx" \\
  || miss "origin remote is not bluenviron/mediamtx (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "internal/api/api.go" \\
  && ok "internal/api/api.go" \\
  || miss "missing critical file: internal/api/api.go"
test -f "docs/2-features/02-architecture.md" \\
  && ok "docs/2-features/02-architecture.md" \\
  || miss "missing critical file: docs/2-features/02-architecture.md"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "docs/5-references/1-configuration-file.md" \\
  && ok "docs/5-references/1-configuration-file.md" \\
  || miss "missing critical file: docs/5-references/1-configuration-file.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/bluenviron/mediamtx"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MediaMTX is a zero-dependency real-time media server written in Go that routes live video/audio streams across multiple protocols (SRT, WebRTC, RTSP, RTMP, HLS, MPEG-TS, RTP) with automatic protocol conversion. It solves the problem of needing a single server that can ingest streams from OBS, FFmpeg, or browsers and simultaneously serve them in different formats to diverse clients without transcoding overhead. Monolithic Go application with protocol-specific packages: internal packages for RTSP/RTMP/SRT/WebRTC handlers, cmd/ for CLI entry points, docker/ for Dockerfile variants (standard, Raspberry Pi, FFmpeg). Configuration is YAML-driven (goccy/go-yaml), metrics exposed via Prometheus (docs/2-features/23-metrics.md), and API defined in api/openapi.yaml with Control API endpoints for runtime management.

Live streaming infrastructure engineers and DevOps teams who need to deploy a self-hosted media proxy/router that supports multiple ingest and playback protocols, and developers integrating real-time video into applications (WebRTC broadcasting, RTSP surveillance, HLS playback).

Production-ready and actively maintained. The project has structured CI/CD (test.yml, lint.yml, release.yml, nightly binaries), comprehensive documentation in docs/2-features/, Docker multi-architecture support, and appears to be actively developed based on the release workflow. Code is predominantly Go (1.67M LOC) with high test coverage visibility via CodeCov badges.

Moderate risk: 43 direct dependencies in go.mod including complex WebRTC (pion/*), RTSP (gortsplib), and cryptography libs (golang-jwt, crypto). No obvious single-maintainer risk visible (bluenviron organization suggests team ownership). Breaking changes possible across major versions given active development, but semantic versioning and release workflow suggest disciplined change management.

Active development evident from CI workflows and semantic versioning. Recent additions likely include WebRTC/SRT optimizations (docs/2-features/25-srt-specific-features.md, 26-webrtc-specific-features.md), scalability improvements (docs/2-features/20-scalability.md), and API expansion (api/openapi.yaml). Nightly binary builds indicate continuous release cadence.

git clone https://github.com/bluenviron/mediamtx.git
cd mediamtx
make
./bin/mediamtx

The Makefile in the root orchestrates the build. Default config will bind to localhost:8554 (RTSP), 8001 (HLS), and other protocol ports per docs/2-features/05-configuration.md.

Daily commands:

make  # Compiles to ./bin/mediamtx
./bin/mediamtx  # Runs with default config
./bin/mediamtx mediamtx.yml  # With custom config

For Docker: docker run bluenviron/mediamtx. Development: Go test suite runs via CI (test.yml), lint via golangci-lint (.golangci.yml).

• go.mod — Defines all external dependencies including gortsplib, gortmplib, mediacommon, and gohlslib—essential for understanding what protocols and libraries this media server relies on.
• internal/api/api.go — Entry point for the REST API that exposes the control plane; must understand this to work with server management, stream queries, and metrics.
• docs/2-features/02-architecture.md — Comprehensive architectural overview explaining the streaming pipeline, protocol support, and internal component interactions.
• README.md — High-level introduction to MediaMTX capabilities, supported protocols (SRT, WebRTC, RTSP, RTMP, HLS), and typical deployment patterns.
• docs/5-references/1-configuration-file.md — Complete reference for all configuration options; critical for understanding how to enable/disable features and tune the server.
• Makefile — Build and test orchestration; reveals build targets, test suites, and development workflow conventions used across the project.
• api/openapi.yaml — OpenAPI specification for the control API; definitive reference for all programmatic control endpoints and their request/response schemas.

Add Support for a New Streaming Protocol

1. Add the protocol library as a dependency in go.mod (e.g., grtsplib, gortmplib pattern) (go.mod)
2. Create protocol-specific configuration section in docs/5-references/1-configuration-file.md with parameter examples (docs/5-references/1-configuration-file.md)
3. Document publishing support in docs/3-publish/ with a new markdown file following naming convention (e.g., docs/3-publish/XX-protocol-name.md) (docs/3-publish/index.md)
4. Document reading/playback support in docs/4-read/ with corresponding client examples (docs/4-read/index.md)
5. Add protocol-specific tuning guide at docs/2-features/2X-protocol-name-specific-features.md (docs/2-features/index.md)
6. Update api/openapi.yaml to expose protocol endpoints if applicable (api/openapi.yaml)

Add a New Control API Endpoint

1. Define the endpoint schema in api/openapi.yaml with request/response models (api/openapi.yaml)
2. Implement the handler in internal/api/api.go following the existing gin-gonic patterns (internal/api/api.go)
3. Document the endpoint usage and examples in docs/2-features/22-control-api.md (docs/2-features/22-control-api.md)
4. Add integration test cases in the test suite (referenced in Makefile) (Makefile)

Add a New Stream Recording Format

1. Add format library dependency to go.mod if required (go.mod)
2. Document recording format support in docs/2-features/09-record.md with codec and container details (docs/2-features/09-record.md)
3. Update configuration reference docs/5-references/1-configuration-file.md with recording format options (docs/5-references/1-configuration-file.md)
4. Add format-specific examples in the recording feature guide (docs/2-features/09-record.md)

Add a New Authentication Method

1. Add auth library dependency to go.mod (e.g., keyfunc, jwkset for JWT are already present) (go.mod)
2. Document the authentication method in docs/2-features/06-authentication.md with configuration examples (docs/2-features/06-authentication.md)
3. Update configuration reference in docs/5-references/1-configuration-file.md with auth parameters (docs/5-references/1-configuration-file.md)
4. Implement auth handler in internal/api/api.go (internal/api/api.go)

• Go 1.26.0 — High concurrency, fast compilation, single binary deployment; ideal for a media server handling thousands of concurrent streams.
• gortsplib, gortmplib, datarhei/gosrt, gohlslib — Purpose-built, battle-tested libraries for each protocol; avoids reimplementing complex codec and stream parsing logic.
• Gin web framework + pprof — Fast HTTP server for REST control API; pprof integration enables runtime profiling for performance diagnosis.
• FFmpeg integration — Enables on-the-fly remuxing, re-encoding, and transcoding without reimplementing audio/video processing.
• JWT + JWKS — Standard, stateless authentication mechanism for scalable, distributed authentication without maintaining session state.
• Docker multi-stage builds — Reduces final image size and attack surface; supports multiple architectures (standard, RPi) with single build pipeline.

• Single monolithic binary instead of microservices

  • Why: Simplifies deployment and eliminates inter-process latency; MediaMTX is often deployed as a standalone appliance.
  • Consequence: Vertical scaling only; horizontal scaling requires multiple independent instances with external load balancing.

• In-memory stream buffering rather than persistent queue

  • Why: Minimizes latency for live streaming; suitable for real-time use cases (sports, surveillance, monitoring).
  • Consequence: No built-in stream recovery on server restart; clients must reconnect. Not suitable for zero-loss archive scenarios.

• No built-in authentication DB; relies on JWT/JWKS or external auth

  • Why: Avoids credential management complexity; delegates to existing identity providers (Keycloak, Auth0, etc.).
  • Consequence: Requires external auth infrastructure; not suitable for standalone installs without IdP.

• Hook system is synchronous (POST wait for response)

  • Why: Allows hooks to validate and control stream lifecycle (reject, modify); predictable ordering of events.
  • Consequence: undefined

Config reload: Hot reloading (fsnotify) does not disconnect existing clients—new clients see new config. RTSP password hashing: Uses Argon2 (matthewhartstonge/argon2); plaintext passwords in config are auto-hashed on first run. WebRTC ICE: Requires STUN/TURN configuration for NAT traversal (api/openapi.yaml has webRTC.iceServers field). Recording format: fMP4 vs MPEG-TS recording format selection affects compatibility (docs/2-features/09-record.md). Prometheus metrics endpoint: Defaults to :9998/metrics; ensure firewall allows if using remotely. Path-based auth: Authentication is per-path, not per-user—admin path different from public stream path. FFmpeg/GStreamer: Examples assume these are installed on the system for on-demand publishing (docs/2-features/14-on-demand-publishing.md).

• Stream routing / protocol multiplexing — MediaMTX's core value is transparent protocol conversion—a single internal stream representation flows to multiple output formats simultaneously, reducing duplicate stream handling and storage
• SRT (Secure Reliable Transport) — SRT is a key ingest protocol for live streaming with built-in encryption and recovery; mediamtx's SRT support is documented separately (docs/2-features/25-srt-specific-features.md)
• WebRTC ICE (Interactive Connectivity Establishment) — WebRTC streams in mediamtx need ICE servers (STUN/TURN) to traverse NAT; this is configured per-stream and impacts browser-to-server connectivity
• HLS (HTTP Live Streaming) segmentation — MediaMTX generates HLS playlists and .ts segments on-demand; understanding segment duration, playlist refresh, and discontinuity handling is essential for smooth playback
• Hot configuration reload — MediaMTX watches config files (fsnotify) and applies changes without disconnecting clients; this architectural choice affects state management and path lifecycle
• JWT authentication and authorization — Per-path auth in mediamtx uses JWT tokens (golang-jwt/jwt); understanding token validation and scope binding is critical for securing stream access
• RTSP (Real Time Streaming Protocol) stateful connections — Unlike HTTP-based protocols, RTSP maintains persistent TCP/UDP connections; mediamtx's RTSP handler must manage teardown, session reuse, and timeout carefully

• bluenviron/gortsplib — RTSP protocol library that mediamtx depends on directly; understanding this is key to RTSP stream handling
• pion/webrtc — WebRTC implementation library (pion/webrtc/v4 in go.mod); mediamtx uses this for browser-based stream publishing/playback
• bluenviron/gohlslib — HLS protocol library (gohlslib/v2 in go.mod); handles HTTP Live Streaming ingest and segment generation
• datarhei/gosrt — SRT (Secure Reliable Transport) implementation; mediamtx wraps this for SRT protocol support
• aler9/rtsp-simple-server — Historical predecessor/inspiration; simpler RTSP-only server that mediamtx evolved from to support multiple protocols

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for WebRTC-specific features

The repo has extensive WebRTC functionality (pion/webrtc v4 dependency, docs/2-features/26-webrtc-specific-features.md exists) but the test coverage likely lacks specific WebRTC scenario testing. New contributors could add integration tests covering WebRTC publishing, receiving, ICE candidate handling, and codec negotiation against the actual MediaMTX server.

• [ ] Review existing tests in the codebase to understand test structure and patterns
• [ ] Create new test file for WebRTC integration scenarios (e.g., internal/webrtc_integration_test.go)
• [ ] Add tests for: basic WebRTC publish/read, multiple simultaneous connections, ICE candidate gathering, SDP negotiation failures
• [ ] Add tests for WebRTC-specific features documented in docs/2-features/26-webrtc-specific-features.md
• [ ] Ensure tests use the pion/webrtc package appropriately
• [ ] Run against CI in .github/workflows/test.yml

Add missing protocol-specific documentation gaps for SRT features

The repo supports SRT with gosrt dependency and has docs/2-features/25-srt-specific-features.md, but docs/3-publish/01-srt-clients.md and docs/3-publish/02-srt-cameras-and-servers.md lack specific examples for advanced SRT features like packet loss handling, latency settings, and encryption. Contributors should add concrete configuration examples and troubleshooting guides.

• [ ] Review docs/2-features/25-srt-specific-features.md to identify features not covered in publish docs
• [ ] Review docs/2-features/29-decrease-packet-loss.md for SRT-specific content
• [ ] Expand docs/3-publish/01-srt-clients.md with: ffmpeg SRT publish examples, latency/timeout parameter explanations, bitrate control examples
• [ ] Expand docs/3-publish/02-srt-cameras-and-servers.md with: SRT camera configuration examples, encryption setup, performance tuning
• [ ] Add a troubleshooting section for common SRT connection issues
• [ ] Include code examples showing mediamtx configuration for SRT streams

Add OpenAPI schema validation and SDK generation workflow

The repo has api/openapi.yaml and api/.redocly.yaml but lacks automated validation and client SDK generation in CI. This is valuable infrastructure: contributors can add a GitHub Action that validates the OpenAPI spec against the actual Control API implementation, and optionally generates documentation or client SDKs, improving API maintainability.

• [ ] Add a new GitHub workflow file .github/workflows/openapi_validate.yml
• [ ] Integrate Redocly CLI or Swagger validation to verify api/openapi.yaml syntax
• [ ] Add validation that OpenAPI spec matches actual endpoints in the codebase (grep internal/ for API handlers)
• [ ] Optionally integrate openapi-generator or similar to generate client SDKs and validate against actual responses
• [ ] Document the workflow in docs/2-features/22-control-api.md
• [ ] Ensure workflow runs on PRs that modify api/openapi.yaml or API-related code
• [ ] Add pre-commit hook documentation for local validation

• Add integration tests for protocol cross-conversion (e.g., RTSP input → HLS output verification). Current test.yml runs unit tests but visible test coverage gaps exist for full protocol chains in internal/protocols/*/
• Expand api/openapi.yaml with webhook/hook management endpoints that match the hooks system documented in docs/2-features/21-hooks.md but currently only partially exposed via API
• Create example FFmpeg ingest scripts in a new examples/ directory for common setups (camera ingest to RTSP, OBS to WebRTC, screen capture to SRT) with corresponding doc snippets in docs/2-features/03-publish.md

• High · Outdated Go Version — go.mod. The project specifies Go 1.26.0, which appears to be a future/unreleased version. This is suspicious and may indicate version inconsistency or misconfiguration. Production builds should use stable, widely-tested Go versions. Fix: Use a stable Go version (e.g., 1.23.x or 1.24.x). Verify the actual intended Go version and update go.mod accordingly.
• High · Cryptographic Dependencies with Known Vulnerabilities — go.mod - golang.org/x/crypto. golang.org/x/crypto v0.50.0 is outdated. Cryptographic libraries frequently receive security patches. Using older versions may expose the application to known vulnerabilities in encryption/decryption operations. Fix: Update to the latest version of golang.org/x/crypto (currently 0.56.0+). Review the changelog for security fixes and compatibility.
• High · Outdated Network Libraries — go.mod - golang.org/x/net, golang.org/x/sys. golang.org/x/net v0.53.0 and golang.org/x/sys v0.43.0 are outdated. These libraries handle critical network operations and system interactions. Older versions may contain security flaws in protocol handling. Fix: Update to the latest stable versions (net v0.57.0+, sys v0.48.0+). Verify compatibility with dependent packages before updating.
• Medium · JWT Library Using Outdated keyfunc — go.mod - github.com/MicahParks/keyfunc/v3. github.com/MicahParks/keyfunc/v3 v3.8.0 is used for JWT key management. Version 3.8.0 may have security patches available in newer releases. Fix: Review the latest version of keyfunc/v3 and update if newer patch versions contain security fixes.
• Medium · WebRTC Library Version Lag — go.mod - github.com/pion/webrtc/v4. github.com/pion/webrtc/v4 v4.2.12 is used. WebRTC implementations frequently receive security updates. Check if newer versions are available with security patches. Fix: Regularly check for and apply WebRTC library updates. Monitor security advisories from Pion project.
• Medium · Missing SECURITY.md Content — SECURITY.md. The SECURITY.md file exists but contains minimal information, only referencing an external security page. There's no guidance on reporting vulnerabilities, security policies, or supported versions. Fix: Expand SECURITY.md with: vulnerability reporting process, PGP keys for security contacts, supported versions, security update frequency, and responsible disclosure policy.
• Medium · Self-Update Functionality Risk — go.mod - github.com/minio/selfupdate. The project includes github.com/minio/selfupdate v0.6.0, which enables automatic updates. If the update mechanism isn't properly validated, it could be exploited for unauthorized binary replacement. Fix: Ensure self-update mechanism: validates cryptographic signatures, verifies source integrity, uses HTTPS only, implements rollback capabilities, and logs all updates.
• Medium · Git Integration Library — go.mod - github.com/go-git/go-git/v5. github.com/go-git/go-git/v5 v5.18.0 is used, which could potentially clone or fetch malicious repositories. Input validation on git URLs is critical. Fix: Validate all git URLs and repository sources. Implement URL schema whitelist, disable potentially dangerous git features, and run git operations in isolated environments.
• Low · Incomplete Transitive Dependency Visibility — go.mod. The go.mod file is truncated (ends with 'git'). Complete dependency chain cannot be analyzed for indirect vulnerabilities. Fix: Provide complete go.mod file. Run 'go mod graph' and 'go mod verify' to audit full dependency tree for vulner

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.