ChannelWatch: Real-Time Alerts for Your Channels DVR

Playground Hacks
#1

Introducing ChannelWatch: Real-Time Alerts for Your Channels DVR

Hey everyone!

Just wanted to share my project called ChannelWatch that has now reached version 0.5 with exciting new features! ChannelWatch monitors your Channels DVR in real-time and sends notifications whenever viewing activity occurs, recordings change status, or system conditions change.

What It Does

ChannelWatch provides real-time monitoring with detailed notifications for:

  • Live TV viewing with channel and program details
  • VOD/recorded content playback tracking
  • NEW: Complete recording lifecycle tracking (scheduled, started, completed, cancelled, stopped)
  • Disk space monitoring with customizable thresholds
  • Multi-device awareness and session tracking

Perfect for keeping tabs on household viewing habits, monitoring kids' TV time, tracking DVR recording activity, or just being notified when someone's using your Channels DVR.

Key Features

  • Multiple Alert Types:
    • Channel-Watching for live TV
    • VOD-Watching for recorded content
    • Recording-Events for DVR activity
    • Disk-Space for storage monitoring
  • Rich Notifications:
    • Program information with titles and descriptions
    • Channel information with logos
    • Device and stream details
    • Playback progress for recorded content
    • Recording status with timing information
  • System Features:
    • Real-time event monitoring with minimal resource usage
    • Multiple notification options: Pushover, Discord, Slack, Telegram, Email and more!
    • Runs as a Docker container with multi-platform support (amd64, arm64, arm/v7)
    • Comprehensive configuration options
    • Open source and free to use

Example Notifications

Channel Watching Alert

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

VOD Watching Alert

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

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

Disk Space Alert

⚠️ Low Disk Space Warning
Free Space: 200.59 GB / 1.82 TB (10.8%)
Used Space: 1.62 TB
DVR Path: /shares/DVR

Recording Events Alerts

Scheduled Recording Alert

📺 ACTION NETWORK
Channel: 137
Status: 📅 Scheduled
Program: Batman (1989)
-----------------------
Scheduled: Today at 8:54 AM EDT
Duration:  2 hours 16 minutes

Caped Crusader (Michael Keaton) saves Gotham City from the Joker (Jack Nicholson).

Recording Started Alert

📺 MOVIE CHANNEL
Channel: 129
Status: 🔴 Recording (Manual)
Program: Crank: High Voltage (2009)
-----------------------
Recording: 8:49 AM EDT
Program:   8:48 AM EDT
Duration:  1 hour 42 minutes
Total Streams: 1

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

Recording Completed Alert

📺 MOVIE CHANNEL 
Channel: 129
Status: ✅ Completed
Program: Pet Sematary (1989)
-----------------------
Duration: 1 hour 54 minutes
Total Streams: 1

A doctor (Dale Midkiff) and his family move to a town near an ancient Indian burial ground.

How to Install

Installation is simple with Docker. Here's a complete setup:

version: '3.0'
services:
  ChannelWatch:
    image: coderluii/channelwatch:latest
    container_name: channelwatch
    network_mode: host
    volumes:
      # Path to store configuration and logs
      - /your/local/path:/config
    environment:
      # ========== CORE SETTINGS ==========
      # Required: IP address of your Channels DVR server
      CHANNELS_DVR_HOST: x.x.x.x
      
      # Optional: Port for your Channels DVR server (default: 8089)
      # Only change if you've modified the default Channels DVR port
      CHANNELS_DVR_PORT: 8089
      
      # Optional: Timezone for logs and timestamps
      TZ: Your/Timezone
      
      # ========== LOGGING CONFIGURATION ==========
      # Optional: Log verbosity level (1=Standard, 2=Verbose)
      LOG_LEVEL: 1
      
      # Optional: Number of days to keep log files
      LOG_RETENTION_DAYS: 7
      
      # ========== ALERT CONFIGURATION ==========
      # Enable/disable specific alert types
      # Set to TRUE to enable, FALSE to disable (or remove the line)
      Alerts_Channel-Watching: TRUE   # Live TV watching alerts
      Alerts_VOD-Watching: TRUE       # DVR/recorded content alerts
      Alerts_Disk-Space: TRUE         # Monitor and alert on low disk space
      Alerts_Recording-Events: TRUE   # NEW: Recording lifecycle alerts
      
      # ========== STREAM COUNTING ==========
      # Affects BOTH channel watching AND recording alerts
      # Set TRUE to count all streams together, FALSE to disable count
      STREAM_COUNT: TRUE

      # ========== RECORDING EVENTS ALERT SETTINGS ==========
      # Optional: Fine-tune which recording events trigger alerts
      # Default is TRUE if Recording-Events is enabled
      RD_ALERT_SCHEDULED: TRUE  # Alert when recordings are scheduled
      RD_ALERT_STARTED: TRUE    # Alert when recordings start
      RD_ALERT_COMPLETED: TRUE  # Alert when recordings complete
      RD_ALERT_CANCELLED: TRUE  # Alert when scheduled recordings are cancelled
      
      # ========== CHANNEL-WATCHING ALERT SETTINGS ==========
      # Control what appears in channel watching notifications
      # Set to TRUE to show, FALSE to hide
      CW_CHANNEL_NAME: TRUE       # Show channel name in notifications
      CW_CHANNEL_NUMBER: TRUE     # Show channel number in notifications
      CW_PROGRAM_NAME: TRUE       # Show program name in notifications
      CW_DEVICE_NAME: TRUE        # Show device name in notifications
      CW_DEVICE_IP_ADDRESS: TRUE  # Show device IP address in notifications
      CW_STREAM_SOURCE: TRUE      # Show stream source in notifications
      CW_IMAGE_SOURCE: PROGRAM    # Which image to use (CHANNEL or PROGRAM)
      
      # ========== VOD-WATCHING ALERT SETTINGS ==========
      # Control what appears in VOD/DVR content notifications
      VOD_TITLE: TRUE          # Show content title
      VOD_EPISODE_TITLE: TRUE  # Show episode title (for TV shows)
      VOD_SUMMARY: TRUE        # Show content summary
      VOD_DURATION: TRUE       # Show content duration
      VOD_PROGRESS: TRUE       # Show current playback progress
      VOD_IMAGE: TRUE          # Show content image
      VOD_RATING: TRUE         # Show content rating
      VOD_GENRES: TRUE         # Show content genres
      VOD_CAST: TRUE           # Show cast members
      VOD_DEVICE_NAME: TRUE    # Show device name
      VOD_DEVICE_IP: TRUE      # Show device IP
      
      # ========== DISK SPACE SETTINGS ==========
      # Configure disk space monitoring thresholds
      DS_THRESHOLD_PERCENT: 10   # Alert when free space falls below 10%
      DS_THRESHOLD_GB: 50        # Alert when free space falls below 50GB
      
      # ========== CACHE SETTINGS ==========
      # How long to cache data (in seconds)
      CHANNEL_CACHE_TTL: 86400     # Refresh channel data every 24 hours
      PROGRAM_CACHE_TTL: 86400     # Refresh program data every 24 hours
      VOD_CACHE_TTL: 86400         # Refresh VOD metadata every 24 hours
      JOB_CACHE_TTL: 3600          # Refresh recording job data every hour
      
      # ========== NOTIFICATION PROVIDERS ==========
      # Configure at least one provider below to receive alerts
      # Feel free to leave empty or completely remove any services you don't use
      
      # ----- Pushover Configuration -----
      # Get credentials at https://pushover.net
      PUSHOVER_USER_KEY: ""       # Your Pushover user key
      PUSHOVER_API_TOKEN: ""      # Your Pushover application token
      
      # ----- Apprise Configuration -----
      # Configure any services you want to use
      
      # Discord Webhooks - Format: webhook_id/webhook_token
      APPRISE_DISCORD: ""
      
      # Email - Format: user:password@gmail.com
      APPRISE_EMAIL: ""
      APPRISE_EMAIL_TO: ""        # Recipient email (optional)
      
      # Telegram - Format: bottoken/ChatID
      APPRISE_TELEGRAM: ""
      
      # Slack - Format: tokenA/tokenB/tokenC
      APPRISE_SLACK: ""
      
      # Additional providers available (Gotify, Matrix, MQTT, etc.)
    restart: unless-stopped

Requirements

  • Docker and Docker Compose
  • Channels DVR server
  • At least one notification service configured (Pushover, Discord, Telegram, etc.)

What's New in v0.5

  • Recording-Events Alert: Monitor the complete lifecycle of your DVR recordings
    • :date: Scheduled: Be notified when new recordings are added to your schedule
    • :red_circle: Started: Know exactly when recordings begin capturing content
    • :white_check_mark: Completed: Get alerts when recordings finish successfully
    • :no_entry_sign: Cancelled: Be informed if scheduled recordings are removed
    • :stop_button: Stopped: Get alerts when recordings are manually stopped
  • Enhanced Stream Counting: Recording activity now integrated with stream count
  • Improved Time Formatting: User-friendly "Today/Tomorrow" labels in notifications
  • Fine-Grained Control: Enable/disable specific recording event types

Get It Now

I'd love to hear your feedback and suggestions for future features!

7 Likes
Pushover Notification Setup? / Real-Time Alerts
#2

Excellent work!

One thing that would be nice, if possible, is to swap the notification engine to Apprise rather than Pushover, as Apprise supports dozens of notification endpoints (including Pushover) but could be Discord, email etc.

1 Like
#3

Works great and looking forward to more notification choices

It would be nice to get the device in the notification also

#4

The other thing i've noticed is if the channel is in the TVE range (the 6000's) it doesn't say the name of the channel but only the number

#5

Thanks to everyone who's trying out ChannelWatch! I appreciate all the feedback so far. :grinning:

Apprise Integration

@zerodayz - Thanks for suggesting Apprise! While my initial focus is on expanding alert types, I'll explore adding Apprise support to provide more notification options beyond Pushover. I can't promise it for the immediate next release since I'm currently focused on core improvements for version 0.3.

TVE Channel Issues

@Matthew_Crommert - Regarding the TVE channels in the 6000 range:

I can see regular channels display their names in my development logs:

[TNR] Opened connection to Source1 for ch6 UNIVISION NEW YORK

Since I don't have a TVE setup myself, I'd need to see how those 6000-range channels appear in your logs. Would you be able to share a small snippet showing a TVE channel example? This would help me understand the exact pattern to update the regex correctly.

Device Information Feature

For adding device information to notifications - I'm exploring the Channels DVR API as a potential solution. The current log monitoring doesn't capture device details in real-time, so I'm researching whether the API offers a practical way to retrieve this data alongside other improvements.

I'll keep everyone updated as version 0.3 development progresses. :man_technologist:Thanks again for your valuable feedback!

2 Likes
#6

Couple questions. For the path to config directory, would this be a config file specific to ChannelWatch? Am I just essentially setting whatever location I’d like for the config file to go?

Next question…I have docker on an Ubuntu Linux Server but my Channels DVR server is running on a separate PC on Windows 10. Can I still point to the path of my Channels DVR server log and if so, what would that path format be? (like C:\path\to\……\channels-dvr.log)

#7

First, many thanks to @CoderLuii for creating this tool!

I know a lot of you remember back to when there were dozens of user-created CDVR-related scripts, all with different installation methods, often different by operating system.

OliveTin-for-Channels was created to consolidate these tools in one place, with a common menu system. This allows for leveraging a relatively complete set of the values needed for scripts and tricks like this to work. Continuing that tradition, I've added ChannelWatch to OliveTin, complete with support for multiple DVRs.

Also, for anybody that hasn't seen it: I've also launched a new OliveTin EZ-Start process, that allows you to spin-up OliveTin with just 2 env vars. Then OliveTin itself will step you through the other values you need to take advantage of all of the Actions and Project One-Click spin-ups.

screencapture-htpc6-2025-03-21-21_40_41-edit
screencapture-htpc6-2025-03-21-21_40_41-edit1920×1252 169 KB

screencapture-htpc6-2025-03-21-21_15_27-edit
screencapture-htpc6-2025-03-21-21_15_27-edit2148×844 188 KB

For those with more than one DVR, you can start ChannelWatch for each, and to kill ChannelWatch for any DVR simply select it and enter 0 for a log_check_interval. If there are any active instances of ChannelWatch running the icon will be green rather purple.

Like all of the background Actions in OliveTin, be sure to refresh your browser after making changes to the Action. If you have everything in Organizr like I do (all CDVR-related WebUi's are accessible from the icons on the left side in the screenshot), there's a little local refresh button that's quite handy.

Again, all credit to @CoderLuii for this great script, and hopefully having it in OliveTin will do nothing but make it more useful to more people. :slight_smile:

1 Like
OliveTin for Channels: An Interface for Misc Channels DVR Scripts & Tricks
#8

Yes.

No matter how you attack this, you'll need to configure C:\ProgramData\ChannelsDVR on your Windows system as a Samba share. Then if you use the ChannelWatch container, you'll need to mount that Samba share to your Linux filesystem, so that is has a path you can use for ChannelWatch.

If you go the OliveTin-for-Channels route, you can easily mount the Samba share as a Docker Volume, and use that in OliveTin. There's some very recent detail on how to do that in the new OliveTin EZ-Start thread, as I stepped someone through that process in the last couple of days.

#9

If you cross-reference with the client logs, you can get what device it is coming from. There are several drawbacks as you'd have to poll all of them, and you can only see local ones. However, if you are interested in going down that path, this is how I handled getting clients dynamically in Streaming Library Manager:

https://github.com/babsonnexus/stream-link-manager-for-channels/blob/main/slm.py#L4967

EDIT:
Here's a description of the front-end and functionality:

#10

For those looking to use ChannelWatch as a standalone container, I've given the Docker Compose the Portainer treatment, and added it to A docker-compose for every Channels-related extension -- suitable for Portainer-Stacks!:

screenshot-community_getchannels_com-2025_03_22-07_42_07
screenshot-community_getchannels_com-2025_03_22-07_42_071920×1048 84.8 KB

#11

Looks pretty dope. Hopefully apprise support comes pretty soon as I don't have a pushover account and I would rather use this with discord but looks pretty good so far

#12

Quick Update - v0.3 Coming Soon!

Just wanted to drop a quick update on ChannelWatch! I've been in a brutal 18-hour coding marathon completely rewriting the core architecture for v0.3. My eyes are barely staying open, but the results will be worth it - a completely restructured codebase that's more maintainable and ready for all the features you've been asking for.

What's coming in v0.3:

Rich Visual Notifications - Channel logos now appear directly in your alerts for instant visual recognition of what's being watched

image
image914×414 39.3 KB

Completely Revamped Alert System - Rebuilt from the ground up with a new formatting engine that allows for more detailed and customizable notifications

Full Device Tracking - See exactly which device is watching what, giving you complete visibility into your Channels ecosystem

Advanced Session Management - Behind-the-scenes improvements that make the system more reliable and responsive than ever

This is just the beginning - the architectural overhaul I've been hammering away at lays the groundwork for some seriously exciting features down the road. The technical debt payment wasn't fun, but it's going to make future development much smoother!

I'll respond to all your comments and suggestions very soon! The foundation work may not be visible on the surface, but it'll make everything you've requested possible.

I'm putting the finishing touches on v0.3 now and expect to release it within the next 1-2 hours. Stay tuned!

More details soon!
CoderLuii
203967356

2 Likes
#13

ChannelWatch v0.3.0 Released! :rocket:

I'm excited to announce a major update to ChannelWatch with v0.3.0!

This release completely reimagines how ChannelWatch works with a new architecture focused on reliability and expandability.

What's New:

  • Real-time event monitoring: Connects directly to Channels DVR's event stream (no log file needed!)
  • Multi-service notifications: Added support for Discord, Slack, Telegram, Email and more through Apprise integration
  • Channel logos in notifications: Visual identification of channels
  • Session tracking: Better handling of viewing sessions with automatic cleanup
  • Enhanced error handling: Automatic reconnection and improved stability
  • Diagnostic tools: Built-in troubleshooting capabilities

Migration Guide for Existing Users

Due to the architectural changes, existing users will need to update their docker-compose configuration:

1. Remove Log File Mapping

The old configuration required mapping the Channels DVR log file:

volumes:
  - /path/to/channels-dvr.log:/channels-dvr.log:ro

This is no longer needed and should be removed.

2. Add Required Host Information

Add the CHANNELS_DVR_HOST environment variable:

environment:
  CHANNELS_DVR_HOST: 192.168.1.xxx  # Replace with your Channels DVR IP

3. Update Network Configuration

Change network mode to "host" for simplest setup:

network_mode: host

4. Consider Additional Notification Options

You can now use multiple notification services via Apprise:

# Discord example
APPRISE_DISCORD: "webhook_id/webhook_token"

# Telegram example
APPRISE_TELEGRAM: "bottoken/ChatID"

5. Example Migration

Old Configuration:

version: '3.0'
services:
  ChannelWatch:
    image: coderluii/channelwatch:latest
    container_name: channelwatch
    network_mode: bridge
    volumes:
      - /path/to/config:/config
      - /path/to/channels-dvr.log:/channels-dvr.log:ro
    environment:
      LOG_CHECK_INTERVAL: 10
      Alerts_Channel-Watching: TRUE 
      PUSHOVER_USER_KEY: your_key
      PUSHOVER_API_TOKEN: your_token
      
    restart: unless-stopped

New Configuration:

version: '3.0'
services:
  ChannelWatch:
    image: coderluii/channelwatch:latest
    container_name: channelwatch
    network_mode: host
    volumes:
      - /path/to/config:/config
    environment:
      CHANNELS_DVR_HOST: x.x.x.x
      CHANNELS_DVR_PORT: 8089
      TZ: Your/Timezone
      LOG_LEVEL: 1
      LOG_RETENTION_DAYS: 7
      Alerts_Channel-Watching: TRUE
      CHANNEL_IMAGES: TRUE
      PUSHOVER_USER_KEY: your_key
      PUSHOVER_API_TOKEN: your_token
      
    restart: unless-stopped

For the full configuration guide, detailed examples, and troubleshooting tips, check out the complete documentation on GitHub.

The README includes many more configuration options to customize ChannelWatch to your needs.

Let me know if you have any questions or feedback!

Cheers,
CoderLuii
203967356

2 Likes
#14

Config Directory & Windows/Linux Setup

@Accustiver Two quick answers:

  1. The config directory is where ChannelWatch stores its container logs - pick any location you prefer within your Linux docker machine!
  2. With the new v0.3.0 release, you don't need to access Channels DVR log file anymore. Just set CHANNELS_DVR_HOST to your Windows PC's IP and you're set! Much simpler now! :raised_hands:

Device Information

@babsonnexus Thanks for sharing your approach to client detection!

Great news - v0.3.0 now features full device information in notifications! I built a streamlined custom implementation using the Channels DVR event stream API that delivers real-time data with minimal overhead. Your method gave me some additional perspectives to consider for future enhancements! Always enjoy seeing different approaches to these challenges!

New Features Are Live!

Hey everyone! All the features you've been asking for are now available! :tada:

@zerodayz / @Jean0987654321 Apprise integration is here! Now supporting Discord, Slack, Telegram, Email and dozens more notification services!

@Matthew_Crommert Both your requests are in - device information now appears in notifications, and the channel name detection works for all ranges including those TVE channels in the 6000s!

The biggest change? ChannelWatch now connects directly to the Channels DVR event stream instead of reading log files - making setup way easier and much more reliable!

Thanks to everyone for the amazing feedback and suggestions that helped shape this release! If you run into any issues or have ideas for improvement, please check out the GitHub Repository or Docker Hub

I'm already thinking about what's next - any other alert types or features you'd like to see in future updates?

Let me know what would make ChannelWatch even more useful for your setup!

Cheers,
CoderLuii
203967356

2 Likes
#15

Neat....hopefully @bnhf will update olivetin with the new version of this so I could start using it :heart_eyes:

1 Like
#16

Great work, @CoderLuii !! :clap:

I'm thinking one alert that could be useful if when the available disk space for recordings gets lower than a specified threshold.

Speaking from experience here because I don't check as often as I should. :grimacing:

1 Like
#17

Instead of (or in addition to) this, since you're now using apprise, use the apprise approach
pover://{user_key}@{token}
pover://{user_key}@{token}/{device_id}
pover://{user_key}@{token}/{device_id1}/{device_id2}/{device_idN}
pover://{user_key}@{token}?priority={priority}
pover://{user_key}@{token}?priority=emergency&expire={expire}&retry={retry}
...
https://github.com/caronc/apprise/wiki/Notify_pushover

1 Like
#18

Disk Space Alert Feature

@mjitkop - Thank you for this excellent suggestion! :tada: I am thrilled to confirm that I will be implementing this feature for release version 0.4!

The feature will monitor available disk space for your recordings and send proactive alerts when storage drops below your specified threshold. You'll be able to configure thresholds by either percentage or absolute GBs, ensuring you never run out of space unexpectedly. :floppy_disk:

Custom Apprise Configuration for Pushover

@chDVRuser - Thank you for highlighting this alternative configuration approach! :raised_hands: The Apprise method is indeed fully supported in the current release, providing users with flexibility in how they set up their notifications.

While the direct Pushover API implementation remains the recommended approach for most users due to its reliability and optimized handling, the Apprise method offers a valid alternative for those who prefer a unified configuration style.

Here's an example of how users can leverage Apprise for Pushover notifications:

name: channelwatch
version: '3.0'
services:
  channelwatch:
    image: coderluii/channelwatch:latest
    container_name: channelwatch
    network_mode: host
    volumes:
      - /your/local/path:/config
    environment:
      # Core settings
      CHANNELS_DVR_HOST: X.X.X.X
      CHANNELS_DVR_PORT: 8089
      TZ: Your/Timezone
      
      # Logging and alerts
      LOG_LEVEL: 1
      LOG_RETENTION_DAYS: 7
      Alerts_Channel-Watching: TRUE
      CHANNEL_IMAGES: TRUE
      
      # Apprise configuration alternative for Pushover
      APPRISE_CUSTOM: pover://your_user_key@your_token
    restart: unless-stopped

I appreciate you sharing this approach as it provides users with additional configuration options while maintaining full Pushover functionality!

Cheers,
CoderLuii
203967356

1 Like
#19

@CoderLuii Are you still meaning for this project to be open source? Both the main.py on your GitHub home for the project, and in the attached source code zip files, are binaries.

#20

This is absolutely great! It definitely fulfills all my needs at this point

I saw one issue that i had missed before - it wont parse hdhomerun/broadcast channels - pretty sure its because its chopping off the .x number at the end of each one - i had one person streaming 13.1 and it said they were streaming 13 and i actually have a virtual channel there

So when i stream 13.1 it looks like this in channels logs
image

And in channels admin
image

And in your notifications

IMG_9792
IMG_97921290×1847 95.8 KB

Thanks for all the great work