tutorial

Monitoring ErsatzTV with Vigilmon

ErsatzTV is your self-hosted virtual TV channel server — but channel outages and transcoding failures happen silently. Here's how to monitor your ErsatzTV web UI, FFmpeg pipeline, IPTV endpoints, and media scan jobs with Vigilmon.

ErsatzTV turns your media library into software-defined virtual TV channels you control entirely. Running on C#/.NET with its web interface at port 8409, it orchestrates FFmpeg transcoding, IPTV stream delivery, EPG scheduling, and media library scanning — all without a cloud dependency. When any of those subsystems quietly fails, your channels go dark with no built-in alert. Vigilmon gives you the uptime monitoring layer ErsatzTV doesn't ship with, so you know the moment your virtual TV server needs attention.

What You'll Set Up

  • Web UI availability monitor (port 8409)
  • Channel scheduling engine health check
  • FFmpeg transcoding pipeline probe
  • IPTV m3u and XMLTV EPG endpoint monitoring
  • Media library scan job heartbeat
  • Stream delivery health check

Prerequisites

  • ErsatzTV running and accessible on port 8409
  • At least one channel configured and active
  • A free Vigilmon account

Step 1: Monitor the ErsatzTV Web UI

The web UI is the primary signal that ErsatzTV's .NET host is alive and its internal services have initialized:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your ErsatzTV URL: http://YOUR_SERVER_IP:8409.
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

If ErsatzTV is behind a reverse proxy (nginx, Caddy, Traefik), monitor the proxied URL instead. The root path returns the React SPA shell — a 200 here confirms the .NET host is running and serving traffic.

Step 2: Monitor the Channel Scheduling Engine

ErsatzTV exposes a health endpoint you can probe to verify the scheduling engine is active. Check the API endpoint for a specific channel's current schedule:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the API URL: http://YOUR_SERVER_IP:8409/api/channels.
  3. Set Expected HTTP status to 200.
  4. Under Response body contains, enter "name" to confirm a valid JSON channel list is returned.
  5. Set Check interval to 2 minutes.
  6. Click Save.

A successful response from /api/channels confirms the scheduling engine has loaded your channel configurations and is serving the internal planner. If ErsatzTV is still initializing or the database connection has failed, this endpoint returns an error or an empty payload.

Step 3: Monitor the IPTV m3u Playlist Endpoint

Client devices (Plex, Emby, Jellyfin, Channels DVR) pull your channel list from ErsatzTV's m3u output. If this endpoint goes stale or returns an error, clients can't discover or tune to your channels:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the m3u URL: http://YOUR_SERVER_IP:8409/iptv/channels.m3u.
  3. Set Expected HTTP status to 200.
  4. Under Response body contains, enter #EXTM3U — the mandatory first line of any valid m3u playlist.
  5. Set Check interval to 5 minutes.
  6. Click Save.

Also monitor the XMLTV EPG endpoint so clients receive guide data:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter: http://YOUR_SERVER_IP:8409/iptv/xmltv.xml.
  3. Set Expected HTTP status to 200.
  4. Under Response body contains, enter <tv to confirm a valid XMLTV document is returned.
  5. Set Check interval to 5 minutes.
  6. Click Save.

Both endpoints are generated on-the-fly from the channel database. A failure here often indicates a database connectivity issue or a corrupted channel configuration.

Step 4: Monitor Stream Delivery Health

ErsatzTV streams channels via HLS or MPEG-TS. You can probe the stream manifest for an active channel to verify the FFmpeg transcoding pipeline is producing output:

  1. In ErsatzTV, note the channel number of an always-on channel (e.g., channel 1).
  2. Click Add Monitor → HTTP / HTTPS.
  3. Enter the HLS manifest URL: http://YOUR_SERVER_IP:8409/iptv/channel/1.m3u8.
  4. Set Expected HTTP status to 200.
  5. Under Response body contains, enter #EXTM3U.
  6. Set Check interval to 5 minutes.
  7. Click Save.

This probe requests a stream manifest. ErsatzTV launches an FFmpeg process to begin transcoding if one isn't already running. A 200 with a valid HLS manifest confirms the transcoding pipeline is functional. A timeout or 5xx error indicates FFmpeg is failing to start — check available disk space for the transcode cache and verify FFmpeg is installed and accessible at the path ErsatzTV expects.

Note: The first probe may be slow (3–10 seconds) while FFmpeg initializes. Set Timeout to 30 seconds on this monitor to avoid false alerts during cold starts.

Step 5: Heartbeat for Media Library Scan Jobs

ErsatzTV periodically scans your media library to pick up new files and update metadata. These background jobs run on a schedule and produce no outward HTTP signal when they complete. Use a Vigilmon cron heartbeat to detect when scans stop running:

Add a script or systemd timer that calls ErsatzTV's scan API and then pings Vigilmon on success:

#!/bin/bash
# Trigger a library scan via the ErsatzTV API
SCAN_RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://YOUR_SERVER_IP:8409/api/libraries/1/scan)

if [ "$SCAN_RESPONSE" -eq 200 ] || [ "$SCAN_RESPONSE" -eq 204 ]; then
  # Ping Vigilmon heartbeat to signal success
  curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID
fi

Set up the heartbeat monitor in Vigilmon:

  1. Click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to match your scan schedule (e.g., 360 minutes for a 6-hour scan cycle).
  3. Copy the heartbeat URL and paste it into your script above.
  4. Click Save.

If the scan job crashes or ErsatzTV's scheduler stops queueing library refreshes, Vigilmon alerts after the expected interval without a ping.

Step 6: Configure Alerts and Maintenance Windows

  1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook endpoint.
  2. For stream delivery monitors, set Consecutive failures before alert to 2 — a single FFmpeg startup delay can cause one missed probe.
  3. For web UI and IPTV endpoint monitors, set to 1 for immediate notification.
  4. Use Maintenance windows when updating ErsatzTV to suppress alerts during the restart:
# Open a 10-minute maintenance window before updating
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "YOUR_MONITOR_ID", "duration_minutes": 10}'

# Pull the latest ErsatzTV image and restart
docker pull jasongdove/ersatztv:latest
docker compose up -d ersatztv

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | http://HOST:8409 | .NET host crash, port unavailable | | Channel API | /api/channels | Scheduler failure, DB connectivity loss | | m3u playlist | /iptv/channels.m3u | Channel config failure, missing output | | XMLTV EPG | /iptv/xmltv.xml | Guide data generation failure | | HLS stream | /iptv/channel/1.m3u8 | FFmpeg transcoding pipeline failure | | Scan heartbeat | Heartbeat URL | Library scan job not running |

ErsatzTV gives you the power to build a personal broadcast network from your own media — but that power runs entirely on your own infrastructure. With Vigilmon watching the scheduling engine, IPTV output, and transcoding pipeline, you get early warning before your virtual channels go dark and your clients start buffering on an empty playlist.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles