MediaMTX Docs

Context: $ARGUMENTS

Quick start

• Find a config key / API endpoint / feature: -> Step 2 (search --query <term>)
• Read a how-to in full: -> Step 4 (fetch --page <publish/X or read/X>)
• Read one section: -> Step 3 (section --page <page> --id <anchor>)
• Prime cache for offline: -> Step 5 (index)

When to use

• User asks "how do I push RTSP to MediaMTX?" or "how do I configure JWT auth?" or "what control-api endpoints exist?"
• Need to verify a MediaMTX config key or CLI flag before recommending it.
• Need the canonical mediamtx.org URL to cite.
• Before wiring up a publisher/reader, confirm the protocol endpoint and default port (RTSP 8554, RTMP 1935, HLS 8888, WebRTC 8889, SRT 8890, API 9997, Metrics 9998, pprof 9999).
• For the running-server wrapper + API calls, see the mediamtx-server skill.

Step 1 — Know the page catalog

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py list-pages

Top-level families:

Read references/pages.md for the full catalog.

Step 2 — Search first

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py search --query "recordFormat" --limit 5
uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py search --query "jwt" --page features/authentication
uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py search --query "/v3/paths" --page references/control-api

Use --regex for anchored patterns. Each hit prints page:line, nearest heading, canonical URL, and ±3 lines of context.

Step 3 — Read one section

When a hit surfaces [§anchor]:

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py section --page features/authentication --id internal-users
uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py section --page references/configuration-file --id paths

--id also accepts a heading keyword as fallback.

Step 4 — Fetch a whole page

Use sparingly — howto pages are compact enough to fetch whole when you actually need the full recipe:

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py fetch --page publish/ffmpeg
uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py fetch --page read/web-browsers
uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py fetch --page github-mediamtx.yml   # raw upstream YAML

--format json for structured handoff.

Step 5 — Prime cache

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py index

Fetches every known page (~70 URLs) at 0.3s each. Override cache dir via MEDIAMTX_DOCS_CACHE. Clear with clear-cache.

Gotchas

• MediaMTX does NOT transcode — it remuxes only. If a publisher pushes HEVC into a path and a reader asks for WebRTC in the browser, the reader will FAIL (browsers don't universally support HEVC in WebRTC). The docs page features/remuxing-reencoding-compression is explicit: for transcoding, chain an external ffmpeg publisher. When in doubt, publish as H.264 + Opus.
• The binary is now mediamtx (was rtsp-simple-server). Repo moved from aler9/rtsp-simple-server -> bluenviron/mediamtx. Old Docker tags and install scripts still float around the internet; ignore them.
• Default ports you'll see quoted in docs: RTSP 8554, RTSPS 8322, RTMP 1935, RTMPS 1936, HLS 8888, WebRTC 8889, SRT 8890, Control API 9997, Metrics 9998, pprof 9999, Playback 9996. Each is a separate listener; disable any you don't need in mediamtx.yml.
• Three auth backends, exclusive. internal (users in YAML under authInternalUsers), http (POST to an external endpoint), jwt (verify a bearer token via JWK URL or static secret). You can't mix them globally — but per-path permissions still apply. See features/authentication.
• Auth actions: publish, read, playback, api, metrics, pprof. Default allowed users have all which is shorthand for the union. Lock down production before exposing port 9997.
• Hooks fire on path events, not on connection events. runOnInit runs when the path is first registered, not when a client connects. runOnDemand is what you want for lazy pipelines. Read features/hooks.
• always-available vs on-demand-publishing. Set sourceOnDemand: true to start source: only when readers appear (saves bandwidth). sourceOnDemandStartTimeout + sourceOnDemandCloseAfter control how long MediaMTX waits / keeps source alive after the last reader.
• Control API lives at /v3/*, NOT /v2/* or /v1/*. Older tutorials reference v2; the v3 namespace is the current stable. Full endpoint list is on references/control-api.
• HLS has two variants: "HLS" (standard, .ts segments, ~6s latency) and "Low-Latency HLS" (LL-HLS, fMP4 partial segments, ~2s latency). Configurable per path via hlsVariant.
• WebRTC signalling is WHIP/WHEP over HTTP at http://<host>:8889/<path>/whip (publish) and .../whep (read). Default ICE servers + STUN config live at the global level; per-path overrides are NOT supported.
• SRT uses the "stream ID" trick for path routing. srt://host:8890?streamid=publish:<path>:<user>:<pass> to publish; srt://host:8890?streamid=read:<path>:<user>:<pass> to read. Quotes required in most shells.
• recordFormat: fmp4 is the default and what you want. MPEG-TS recording is deprecated for most cases because it can't seek.
• Config file hot-reloads on SIGHUP, but some settings (listening ports, TLS certs) require a full restart. If a change "doesn't seem to take", restart the process.
• Docs site pagination is Next.js SSR; anchors are Markdown-slugified headings (#internal-users, #authentication-methods). The section --id command accepts either the raw slug or a heading keyword.
• Raw upstream YAML is the final authority. github-mediamtx.yml page returns the exact mediamtx.yml shipped in main with every default documented inline. When mediamtx.org lags a release, this is the ground truth.

Examples

Example 1 — "What do I put in mediamtx.yml to enable JWT auth?"

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py search --query "jwt" --page features/authentication --limit 5
uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py section --page features/authentication --id jwt

Example 2 — "How do I publish with ffmpeg?"

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py fetch --page publish/ffmpeg

Example 3 — "What's the full list of control-api endpoints?"

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py fetch --page references/control-api

Example 4 — "What does runOnDemandCloseAfter default to?"

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py search --query "runOnDemandCloseAfter" --page github-mediamtx.yml --limit 3

(Upstream YAML has inline defaults — faster than the HTML docs here.)

Example 5 — "Record to disk, rotate every 15 min, keep 4 hours"

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py search --query "recordSegmentDuration" --page features/record
uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py search --query "recordDeleteAfter" --page features/record

Example 6 — "WebRTC publish from a browser — what's the WHIP URL?"

uv run ${CLAUDE_SKILL_DIR}/scripts/mtxdocs.py fetch --page publish/web-browsers

Troubleshooting

Error: unknown page: foo

Cause: The name isn't in the catalog. Solution: Run list-pages. Common mistakes: using record instead of features/record; api instead of references/control-api.

Error: urlopen error [SSL: CERTIFICATE_VERIFY_FAILED]

Cause: System certificate store is out of date (usually macOS Python). Solution: Run /Applications/Python\ 3.x/Install\ Certificates.command or set SSL_CERT_FILE. Don't patch SSL verification off.

Search returns zero hits for a config key

Cause: Key might be new in main but not yet in the published docs. Solution: Search against the upstream YAML — search --query "<key>" --page github-mediamtx.yml. The upstream file is the source of truth.

Results look like broken-up tables

Cause: The HTML extractor flattens cell borders into pipes but can't reconstruct multi-line cells. Solution: The search-hit header prints the canonical URL. Open it directly in a browser for the authoritative view.

Cache stale after MediaMTX release

Solution: clear-cache then index. The GitHub fallback pages already track main — if you want a specific release tag, edit the github-* URLs in the script's PAGES dict (or fetch directly with urllib).

Reference docs

• Full page catalog with protocol-to-page cross reference -> references/pages.md

Source: damionrashford/media-os — distributed by TomeVault.