SPEC · MediaMTX

Identidad del Componente

Campo	Valor
Repo	github.com/bluenviron/mediamtx
Nombre anterior	rtsp-simple-server
Lenguaje	Go (basado en Pion/webrtc)
Licencia	MIT
GitHub ★	~13k
Binario	~20 MB (estático, ARM pre-compilado)
RAM típica	~15–30 MB
Install	wget + chmod (binario Go pre-compilado ARM)
Killer feature	Auto-conversión entre protocolos + rpicam nativo CSI

Key Concept

MediaMTX es un router de protocolos: cualquier fuente publicada (RTSP, RTMP, WebRTC, rpicam) se auto-convierte a todos los demás formatos sin configuración adicional. Publicas un stream → sale en HLS, WebRTC, RTSP, RTMP, SRT automáticamente. Esto simplifica enormemente la arquitectura frente a pipelines manuales con ffmpeg.

Puertos & Protocolos

Puerto	Protocolo	Uso	Browser sin JS
:8554	RTSP	Protocolo base. Entrada y salida.	✘
:8888	HLS	`<video src="…/stream.m3u8">`	✔ Safari nativo
:8889	WebRTC	Peer remoto con JS (WHEP)	✘ (requiere JS)
:1935	RTMP	Re-stream a YouTube/Twitch	✘
:8890	SRT	Link low-latency (Haivision)	✘
:9997	API HTTP	Control, status, configuración	N/A

Configuración Completa — CSI (rpicam nativo)

# /etc/mediamtx/mediamtx.yml # ── Puertos ── rtspAddress: 127.0.0.1:8554 hlsAddress: 127.0.0.1:8888 webrtcAddress: 127.0.0.1:8889 rtmpAddress: "" # desactivar si no se necesita srtAddress: "" # desactivar si no se necesita apiAddress: 127.0.0.1:9997 # ── HLS config ── hlsVariant: lowLatency # fMP4 low-latency (vs mpegts) hlsSegmentCount: 3 hlsSegmentDuration: 1s hlsPartDuration: 200ms # ── Auth (opcional) ── authMethod: internal authInternalUsers: - user: oasis pass: "${MEDIAMTX_PASSWORD}" permissions: - action: read path: solar-cam # ── Paths ── paths: solar-cam: source: rpiCamera rpiCameraWidth: 1280 rpiCameraHeight: 720 rpiCameraFPS: 25 rpiCameraCodec: h264 rpiCameraProfile: baseline rpiCameraLevel: "3.1" rpiCameraBitrate: 1000000 rpiCameraIDRPeriod: 50 # IDR cada 2s (25fps×2) # Hooks runOnReady: curl -s http://localhost:3000/hook/stream-ready runOnNotReady: curl -s http://localhost:3000/hook/stream-stopped

Configuración — USB (ffmpeg exec)

# mediamtx.yml — paths para cámara USB paths: solar-cam: # USB: ffmpeg captura V4L2, transcodifica, publica RTSP local runOnInit: > ffmpeg -f v4l2 -input_format mjpeg -video_size 1280x720 -framerate 25 -i /dev/video0 -c:v h264_v4l2m2m -b:v 1M -f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH runOnInitRestart: yes # Si la webcam tiene H.264 HW nativo: # runOnInit: > # ffmpeg -f v4l2 -input_format h264 # -video_size 1280x720 -i /dev/video0 # -c:v copy -f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH

Con USB, MediaMTX pierde su ventaja sobre go2rtc: ambos necesitan ffmpeg. go2rtc captura V4L2 directo sin ffmpeg intermediario.

Audio: ffmpeg → RTSP

MediaMTX no captura ALSA directamente. El audio necesita un proceso ffmpeg aparte publicando en otro path RTSP.

# mediamtx.yml — audio path paths: solar-mic: runOnInit: > ffmpeg -f alsa -i default -c:a aac -b:a 64k -f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH runOnInitRestart: yes

Alternativa: usar Mumble para audio (ya instalado, bidireccional, Tor-compatible). Ver Arq. 3 para el bridge Mumble→HTTP.

API HTTP (:9997)

Endpoint	Método	Función
/v3/paths/list	GET	Listar paths activos + estado
/v3/paths/get/{name}	GET	Detalle de un path (readers, source)
/v3/config/global/patch	PATCH	Modificar config en caliente
/v3/config/paths/add/{name}	POST	Añadir path en caliente
/v3/config/paths/remove/{name}	DELETE	Eliminar path en caliente
/v3/hlsmuxers/list	GET	Listar muxers HLS activos
/v3/webrtcsessions/list	GET	Listar sesiones WebRTC activas

Útil para que Oasis (Node.js) consulte estado de streams y gestione paths dinámicamente sin reiniciar MediaMTX.

Integración con Oasis

Ruta Oasis	Origen	Content-Type	HTML
GET /video.m3u8	Proxy → MediaMTX :8888/solar-cam/	application/vnd.apple.mpegurl	`<video src="/video.m3u8">`
GET /snapshot	ffmpeg grab de RTSP → JPEG (on demand)	image/jpeg	`<img src="/snapshot">`
GET /audio	Mumble bridge (recomendado) o ffmpeg RTSP→OGG	audio/ogg	`<audio src="/audio">`

MJPEG continuo no está disponible nativamente en MediaMTX. Para browsers LAN sin JS que no soportan HLS nativo (Firefox/Chrome), usar snapshot + <meta http-equiv="refresh" content="2"> o proxy ffmpeg RTSP→MJPEG.

Troubleshooting

Síntoma	Causa	Fix
rpiCamera: not found	libcamera no disponible en el sistema	apt install libcamera-apps. Verificar dtoverlay en config.txt
HLS no arranca (404)	No hay viewer → stream no se activa	MediaMTX es on-demand. El stream arranca con el primer viewer.
Latencia HLS alta (>5s)	Segmentos HLS grandes	Usar `hlsVariant: lowLatency` + `hlsPartDuration: 200ms`
ffmpeg runOnInit falla	Variables $RTSP_PORT/$MTX_PATH no expandidas	Verificar que se usa YAML multiline (`>`). MediaMTX inyecta las variables.
Alta CPU con USB	ffmpeg transcoding software	Usar `h264_v4l2m2m` para encode HW. Reducir resolución.
Auth rechaza conexión	authMethod activo, credenciales incorrectas	Verificar MEDIAMTX_PASSWORD env var. O poner `authMethod: ""` para deshabilitar.

MediaMTX RTSP HLS rpiCamera auto-conversión hooks Pion mediamtx.yml lowLatency API v3