Monitoring MediaMTX with Vigilmon

MediaMTX (formerly rtsp-simple-server) is a ready-to-use, zero-dependency media server written in Go that can ingest, proxy, transcode, and re-stream video from IP cameras, OBS Studio, hardware encoders, and other sources across RTSP, RTMP, HLS, WebRTC, and SRT simultaneously. Home labs, CCTV setups, live event production teams, and IoT deployments rely on it as a single server to handle their entire streaming pipeline. But when a publisher disconnects or the HLS segment generator stalls, there's no built-in alert — viewers just see a spinning wheel. Vigilmon fills that gap with REST API health checks, stream-path availability monitors, and SSL certificate alerts for HTTPS/WSS deployments.

What You'll Set Up

• HTTP monitor for the MediaMTX REST API (port 9997)
• Stream-path availability monitor for a specific camera or encoder path
• HLS endpoint availability monitor (port 8888)
• SSL certificate alerts for HTTPS/WebRTC deployments
• Cron heartbeat to detect publisher disconnections before viewers do

Prerequisites

• MediaMTX running and accessible (Docker, binary, or systemd)
• REST API enabled on port 9997 (enabled by default)
• HLS enabled on port 8888 (enabled by default)
• A free Vigilmon account

Step 1: Monitor the MediaMTX REST API

MediaMTX exposes a REST API on port 9997 that provides full management access including health status. The GET /v3/paths/list endpoint returns a list of all configured media paths and their current status — a 200 response confirms the server is running and the API is accessible.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://your-server:9997/v3/paths/list
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter ready — the response JSON contains "ready":true for active paths.
7. Click Save.

A successful response from this endpoint looks like:

{
  "items": [
    {
      "name": "camera1",
      "ready": true,
      "readyTime": "2026-01-15T10:00:00Z",
      "tracks": ["H264", "MPEG-4 Audio"]
    }
  ]
}

If the MediaMTX process crashes or the API port becomes unreachable, Vigilmon alerts you immediately.

Step 2: Monitor a Specific Stream Path

The API health check in Step 1 confirms the MediaMTX server is running, but it doesn't confirm that your IP camera or encoder is still actively publishing. Use GET /v3/paths/get/{pathName} to monitor a specific stream path.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: http://your-server:9997/v3/paths/get/camera1 (replace camera1 with your path name).
3. Set Check interval to 1 minute.
4. Set Expected HTTP status to 200.
5. Under Keyword check, enter "ready":true — this confirms a publisher is connected and actively streaming.
6. Click Save.

When "ready" is false, it means the publisher (IP camera, OBS, hardware encoder) has disconnected. MediaMTX stays up but is serving no content on that path. Vigilmon catches this and alerts before your viewers notice.

To find your path names, list them with:

curl http://localhost:9997/v3/paths/list | jq '.items[].name'

Add one monitor per critical stream path.

Step 3: Monitor HLS Endpoint Availability

MediaMTX generates HLS segments on port 8888 for browser and mobile players that can't use RTSP or WebRTC directly. The HLS playlist file /{pathName}/index.m3u8 is only generated when an active publisher is connected.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: http://your-server:8888/camera1/index.m3u8
3. Set Check interval to 2 minutes (HLS segment generation has a startup delay).
4. Set Expected HTTP status to 200.
5. Under Keyword check, enter #EXTM3U — valid HLS playlists always start with this header.
6. Click Save.

Response status meanings:

• 200 with #EXTM3U — HLS is active and serving segments
• 404 — no publisher is connected on this path
• 5xx — HLS generation failure; check MediaMTX logs for FFmpeg errors

If you use a different HLS port via hlsAddress in mediamtx.yml, update the URL accordingly.

Step 4: SSL Certificate Alerts for HTTPS/WebRTC Deployments

MediaMTX supports native TLS on all protocols — RTSPS, RTMPS, HTTPS (HLS/WebRTC), and WSS. WebRTC in particular requires HTTPS in all modern browsers; an expired certificate silently breaks every browser-based WebRTC viewer.

If you serve MediaMTX behind a reverse proxy (nginx, Caddy) or with its built-in TLS:

1. Open the HTTP monitor for your HLS or API endpoint.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

For MediaMTX deployments with multiple TLS endpoints, add SSL monitoring to each:

| Endpoint | Protocol | Port | |---|---|---| | https://stream.domain.com:8888 | HTTPS (HLS) | 8888 | | https://stream.domain.com:8889 | HTTPS (WebRTC) | 8889 | | https://stream.domain.com:9997 | HTTPS (API) | 9997 |

A 21-day alert window gives you time to renew before WebRTC viewers experience broken streams.

Step 5: Heartbeat Monitoring for Publisher Connectivity

IP cameras and hardware encoders are the most common failure points in a MediaMTX pipeline — power loss, network interruption, or a camera reboot stops the RTSP push. A Vigilmon cron heartbeat can verify that the expected number of active publishers stays above zero during streaming hours.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 5 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Create a script that checks the MediaMTX API and pings the heartbeat only when publishers are active:

#!/bin/bash
# /usr/local/bin/check-mediamtx-publishers.sh

READY_COUNT=$(curl -sf http://localhost:9997/v3/paths/list \
  | jq '[.items[] | select(.ready == true)] | length')

if [ "${READY_COUNT:-0}" -gt 0 ]; then
  curl -sf https://vigilmon.online/heartbeat/abc123
fi

5. Schedule it with cron:

crontab -e
# Add:
*/5 * * * * /usr/local/bin/check-mediamtx-publishers.sh

If all cameras disconnect and the ready count drops to zero during expected streaming hours, the heartbeat stops pinging and Vigilmon alerts you after the interval expires.

For end-to-end pipeline monitoring, pair this with a TCP probe to your camera's RTSP port:

1. Click Add Monitor → TCP Port.
2. Enter the camera IP and port: 192.168.1.50:554
3. Set Check interval to 2 minutes.
4. Click Save.

A failed TCP probe to the camera itself identifies whether the problem is the camera (network/power) or the MediaMTX server.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. For stream monitors, set Consecutive failures before alert to 2 — HLS segment generation can take a few seconds after a publisher reconnects, causing a single transient failure.
3. Use Maintenance windows during planned MediaMTX restarts or firmware updates on cameras:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 10}'

Summary

| Monitor | Target | What It Catches | |---|---|---| | REST API health | http://server:9997/v3/paths/list | MediaMTX process down | | Stream path | http://server:9997/v3/paths/get/camera1 | Publisher disconnected | | HLS playlist | http://server:8888/camera1/index.m3u8 | HLS generation failure | | SSL certificate | https://stream.domain.com | Expired cert breaks WebRTC | | Cron heartbeat | Heartbeat URL | Zero publishers during stream hours | | TCP probe | camera-ip:554 | Camera network/power failure |

MediaMTX gives you a single server for every streaming protocol — but it can't alert you when a camera goes dark or HLS segments stop generating. Vigilmon watches the REST API, individual stream paths, and HLS endpoints so you know the moment your streaming pipeline breaks, not when viewers start complaining.