Skip to content
ChannelWatch

Channel Watching

Channel Watching alerts notify you when a device starts live TV or changes channels. Choose the fields you want to include, then route the alert to your preferred destinations.

Enable Channel Watching

Section titled “Enable Channel Watching”
  1. Open Settings > Alerts > Channel Watching and expand the card.
  2. Choose Global or a DVR, then turn Channel Watching on.
  3. Choose the image source and message fields, then select Save.
  4. In Settings > Routing, allow the destinations for that DVR’s Channel Watching alerts.

Fresh v1.6.5 installs start with Important Only, so routine viewing alerts are off until you enable them.

What triggers the alert

Section titled “What triggers the alert”

ChannelWatch monitors the Channels DVR activity stream for activities.set events that contain "Watching ch" in the event value. Each unique combination of channel and device is tracked as a session. A notification fires when:

  • A device starts watching a channel it was not already watching, or
  • A device switches to a different channel (the old session ends, a new one begins)

Repeated events for the same active session are suppressed. The channel notification cooldown also prevents rapid duplicate notifications; its default is 300 seconds.

Options

Section titled “Options”

Configure these in the web UI under Settings > Alerts > Channel Watching.

Expanded ChannelWatch Channel Watching settings with Program Image selected and switches for channel, program, device and stream-source fields
Channel Watching settingsExpand Channel Watching, check the active DVR scope, and choose the image source and message fields. Captured from ChannelWatch v1.6.0 with safe demo data.View full-size screenshot
Option Description
Image Source Which image to attach to the notification: Channel Logo (the channel’s broadcast logo) or Program Image (the current program’s artwork). If the preferred source has no image, ChannelWatch falls back to the other automatically.
Show Channel Name Include the channel’s name (e.g. ABC) in the notification body.
Show Channel Number Include the channel number (e.g. 7 or 13.1) in the notification body.
Show Program Name Include the title of the program currently airing on that channel. Requires a successful lookup against the Channels DVR guide data.
Show Device Name Include the name of the device or client that started watching.
Show Device IP Include the IP address of the device.
Show Stream Source Include the stream source identifier (e.g. HDHR for a HDHomeRun tuner).
Stream Count Include the current active-stream total in the alert payload and internal log output.

All options are enabled by default. Disable any you don’t need to keep notifications concise.

Sample notification

Section titled “Sample notification”

With all options enabled and metadata available, a Channel Watching alert uses this default title and body:

Title: Channels DVR - Watching TV


📺 ABC
Channel: 7
Program: Good Morning America
Resolution: 720p
Device: Living Room
Device IP: 192.168.1.101
Source: HDHR
Total Streams: 2

This is a synthetic text example. Body lines appear in the order shown above; disabled or unavailable fields are omitted. Resolution is included when the DVR supplies it. Use Notification Templates to change the wording.

Image source behavior

Section titled “Image source behavior”

When Image Source is set to Channel Logo, ChannelWatch uses the channel’s logo from your Channels DVR server. If no logo is available, it falls back to the current program’s artwork. When set to Program Image, the order reverses: program artwork first, channel logo as fallback. If neither is available, the notification is sent without an image.

Edge cases

Section titled “Edge cases”

Subchannel numbers. Channels DVR reports subchannels as decimal numbers (13.1, 7.2). ChannelWatch preserves the full decimal in the notification so you can distinguish between subchannels of the same broadcast network.

Unknown device. If the event does not include a recognizable device name, ChannelWatch falls back to the device’s IP address as the identifier. If neither is available, the session is still tracked but the device field shows Unknown device.

Program name unavailable. Guide data lookups can fail if Channels DVR has not yet populated the EPG for a channel. When that happens, the program name line is omitted from the notification rather than showing a placeholder.

Stream count. See Stream Counting below. When enabled, the current count is passed into the alert formatter and appears as Total Streams in the notification.

Stream Counting

Section titled “Stream Counting”

Stream Counting is a sub-feature of Channel Watching, not a separate alert module. It is controlled by the shared Stream Count toggle in the Channel Watching settings (stream_count).

When enabled, the active-stream total is included in the alert data and internal logs each time a Channel Watching event fires. The notification formatter adds a Total Streams line when the count is available.

A few things to know:

  • Disabling the toggle removes stream-count tracking and the Total Streams notification line.
  • The toggle does not decide whether Channel Watching alerts fire.
  • Stream Counting does not generate its own notifications and has no separate alert type.

Testing

Section titled “Testing”

ChannelWatch v1.6.5 has a Diagnostics test-name limitation. Use the command-line fallback below for a sample Channel Watching alert.

The test sends real messages. Check the received notification and the Delivery Log; a delivery test does not replace checking the real alert’s enable switch and route.

From the command line:

Terminal window
docker exec -it channelwatch python -m core.main --test-alert ALERT_CHANNEL_WATCHING
Section titled “Related pages”