Skip to content
ChannelWatch

VOD Watching

VOD Watching alerts fire when someone starts playing recorded content or a DVR library item on your Channels DVR. You get a single notification per viewing session, with rich metadata pulled directly from your DVR library.

What triggers the alert

Section titled “What triggers the alert”

ChannelWatch monitors the Channels DVR activity stream for activities.set events whose name matches the file-based session pattern (6-file-* or 7-file-*). These events carry a "Watching ... at <timestamp>" value that identifies the content being played and the playback position.

A notification fires when:

  • A new viewing session starts for a file that has not been seen before, or
  • An existing session resumes after the cooldown period has elapsed

The alert fires once per session by default. ChannelWatch does not send repeated notifications while the same content keeps playing. This prevents alert fatigue during long movies or binge-watching sessions.

Options

Section titled “Options”

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

OptionDescription
Show TitleInclude the content title (movie name or TV show name) in the notification.
Show Episode TitleFor TV episodes, include the episode title alongside the show name.
Show SummaryInclude the content’s synopsis or description. Pulled from your DVR library metadata.
Show Content ImageAttach the content’s thumbnail or poster art to the notification.
Show DurationShow playback progress as current position / total duration (e.g. 58m 46s / 1h 42m 11s).
Show ProgressDisplay the current playback timestamp. Used together with Show Duration to form the progress line.
Show RatingInclude the content rating (e.g. R, TV-14).
Show GenresInclude the genre list (e.g. Action, Thriller).
Show CastInclude the top three cast members.
Show Device NameInclude the name of the device or client that started playback.
Show Device IPInclude the IP address of the device.

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, a VOD Watching alert looks like this:

🎬 Crank: High Voltage (2009)
Duration: 58m 46s / 1h 42m 11s
Device Name: Living Room
Device IP: 192.168.1.100


Chev Chelios (Jason Statham) seeks revenge after someone steals his nearly indestructible heart.


Rating: R · Genres: Action, Thriller
Cast: Jason Statham, Amy Smart, Dwight Yoakam

The notification title is the content title (plus release year for movies) prefixed with 🎬. For TV episodes, the episode title is appended after a dash: 🎬 Show Name - Episode Title. The body sections appear in the order shown above, and any disabled option is omitted.

Session tracking and cooldown

Section titled “Session tracking and cooldown”

ChannelWatch tracks each viewing session by a combination of the file ID and a session identifier derived from the event name. When a session is active, subsequent playback events for the same file update the internal timestamp but do not trigger additional notifications until the cooldown period expires.

If playback jumps significantly (for example, a user scrubs far forward or backward), ChannelWatch can detect the large position change and send an updated notification even before the cooldown expires. This behavior is controlled by the Significant Threshold setting in the advanced VOD options.

When a session ends (the activity event value becomes empty), ChannelWatch removes the session from its tracking state. Starting the same content again later creates a fresh session and sends a new notification.

Metadata source

Section titled “Metadata source”

All content metadata (title, summary, cast, genres, rating, duration, artwork) is fetched from your Channels DVR server’s library API. ChannelWatch caches this data at startup and refreshes it periodically. If metadata is unavailable for a particular file, the corresponding fields are omitted from the notification rather than showing placeholders.

Edge cases

Section titled “Edge cases”

Device identification. The device name is extracted from the "Watching ... from <device>" portion of the event value. If the device name is not present, ChannelWatch falls back to the IP address. If neither is available, the session is still tracked but the device fields show Unknown Device / Unknown IP.

VOD switch mid-session. If a device switches from one piece of content to another without a clean session end event, ChannelWatch detects the file ID change and closes the old session automatically before opening a new one.

Recurring sessions. Watching the same content multiple times creates separate sessions each time, so you receive a notification for each new viewing. The cooldown only suppresses repeated notifications within a single continuous session.

TV episodes. For TV show episodes, the notification title includes both the show name and the episode title. Season and episode numbers are available as template variables if you use a custom notification template.

Testing

Section titled “Testing”

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

From the command line:

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