Channel Watching

Channel Watching alerts fire whenever someone starts watching a live TV channel on your Channels DVR. You get a notification the moment a new viewing session begins, with as much or as little detail as you want.

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)

The alert does not fire repeatedly while the same device stays on the same channel. Once a session is active, ChannelWatch waits for a channel change or session end before sending another notification for that device.

Options

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

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).

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

Sample notification

With all options enabled, a Channel Watching alert looks like this:

📺 ABC
Channel: 7
Program: Good Morning America
Device: Living Room
IP: 192.168.1.101
Source: HDHR

The notification title is the channel name prefixed with 📺. The body lines appear in the order shown above, and any disabled option is simply omitted.

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

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. If the Stream Counting alert type is also enabled, the total number of active streams across your system is appended to the log output. This count does not appear in the push notification itself.

Testing

Send a test Channel Watching notification from the web UI at Diagnostics > Alert Tests > Channel Watching. The test notification uses the same format as a real alert and is delivered through your configured notification providers.

From the command line:

docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_CHANNEL_WATCHING

VOD Watching — alerts for recorded content and DVR library playback
Notification Examples — full gallery of sample notification formats
Notification Providers — configure where alerts are delivered