- 📈 Version History
- 🌟 Overview
- 🏛 Architecture
- 📋 Key Features
- ⚡ Performance
- 💡 Support This Project
- 🔧 Prerequisites
- 💻 Platform Support
- 🚀 Quick Setup
- 🔨 Configuration Options
- 📱 Notification Examples
- 🔍 Troubleshooting
- 🔄 Upgrading
- 📁 Project Structure
- 📜 License
- 🙏 Acknowledgments
- 🗺 Future Roadmap
- 💬 Get Help
- v0.8.1 - Documents the release workflow, version-only release commit rule, and public maintainer-copy requirements
- v0.8 - Dependency refresh for the UI, backend, and Docker build with current supported package baselines
- v0.7 - Notification enhancements with improved email and Discord integration, UI documentation improvements, and bug fixes for image selection
- v0.6 - Complete project restructuring with modern web UI, simplified configuration (no environment variables), responsive dashboard, and enhanced error recovery
- v0.5 - Added Recording-Events alerts for monitoring the entire recording lifecycle (scheduled, started, completed, cancelled, stopped), enhanced stream count integration, improved time formatting
- v0.4 - Expanded alert types with VOD-Watching and Disk-Space monitoring, enhanced Channel-Watching with program details and images, improved session tracking
- v0.3 - Complete architecture overhaul with real-time event monitoring, multi-provider notifications, session tracking, and enhanced stability
- v0.2 - Security updates addressing Python dependency vulnerabilities and adding Docker supply chain attestations
- v0.1 - Initial release with core monitoring and notification features
ChannelWatch is a comprehensive monitoring solution with a modern web interface that tracks Channels DVR activity and sends real-time notifications. The system features:
- 🌐 Modern Web Dashboard - Responsive UI with system status monitoring and configuration
- 📱 Real-time viewing alerts - Get instant notifications when channels are being watched
- 📺 Content monitoring - See exactly what's being played on your Channels DVR
- 🎬 VOD tracking - Know when recorded content or DVR libraries are accessed
- 🔴 Recording lifecycle alerts - Track when recordings are scheduled, start, complete, or are cancelled
- 💾 System monitoring - Track disk space usage and receive alerts when space runs low
- 🔔 Multi-device awareness - Track viewing across all your connected devices and clients
- 🏠 Home automation integration - Use alerts as triggers for smart home routines
The system provides comprehensive information with a simple setup process:
- Web-based configuration with no environment variables needed
- Rich media notifications with detailed metadata
- Device identification and stream tracking
- Technical details with beautiful visuals
- Fully customizable notification content
ChannelWatch follows a modern, component-based architecture:
- Core Backend: Monitors the Channels DVR event stream and processes alerts
- Web UI: Provides a responsive dashboard for configuration and monitoring
- Alert System: Processes events to determine when to send notifications
- Notification System: Handles sending notifications through various providers
- Configuration System: Web-based settings management with persistent storage
- Extension Framework: Makes it easy to add new alert types and notification providers
- 🌐 Modern Web Interface with:
- Responsive dashboard for desktop and mobile
- Real-time system status monitoring
- Visual disk space and stream tracking
- Upcoming recordings display
- Quick access diagnostic tools
- ⚙️ Web-based Configuration with:
- Intuitive settings management
- No environment variables required
- Persistent configuration storage
- Real-time validation and feedback
- 🔍 Real-time monitoring of Channels DVR event stream
- 📲 Multi-provider notifications via:
- Pushover for simple push notifications
- Apprise for Discord, Slack, Email, Telegram, and more
- 📺 Live TV alerts with:
- Channel name and number (including decimal subchannels like 13.1)
- Program title and description
- Device name and IP address
- Stream source and quality information
- Total stream count across your system
- 🎬 VOD/Recording Playback alerts with:
- Title, episode, and duration information
- Playback progress tracking
- Cast, rating, and genres
- Smart device detection
- Single notification per viewing session (prevents alert fatigue)
- Support for both standard and newer file patterns
- 🔴 Recording Event alerts with:
- Lifecycle tracking (scheduled, started, completed, cancelled)
- Detailed program information (title, description, duration, channel)
- Status indicators (📅, 🔴, ✅, ⏹️)
- 🖼️ Rich visual alerts with:
- Configurable image source (channel logo or program image)
- High-quality thumbnails for instant recognition
- 💾 System monitoring with:
- Disk space alerts when recording space runs low
- Configurable thresholds (percentage and absolute GB)
- Visual dashboard representation of system status
- 🧹 Automatic session tracking and management
ChannelWatch continues to be lightweight and efficient despite the addition of a full web UI:
- Minimal CPU usage (<2% on most systems)
- Modest memory footprint (~50MB RAM)
- Compact Docker image size (~150MB)
- Quick startup time (<5 seconds)
- Responsive web interface even on low-powered devices
- Efficient background processing with minimal resource contention
If you find ChannelWatch helpful, consider supporting its development:
Follow me on X:
- Docker and Docker Compose
- Channels DVR server with accessible API
- Pushover and/or Apprise account/configuration (Requires at least one provider configured for notifications)
ChannelWatch is available as a multi-platform Docker image, supporting:
linux/amd64: Standard 64-bit x86 servers and PCslinux/arm64: Modern ARM devices (Raspberry Pi 4, Apple M1/M2 Macs)
The correct image will be automatically selected for your hardware when using docker pull coderluii/channelwatch:latest.
Create a docker-compose.yml file:
version: '3.0'
services:
ChannelWatch:
image: coderluii/channelwatch:latest
container_name: channelwatch
network_mode: host
volumes:
# Path to store configuration, logs, and settings
- /your/local/path:/config
restart: unless-stoppedNote:
- All configuration is now done through the web UI at
http://your-server-ip:8501- For bridge networking, replace
network_mode: hostwith:network_mode: bridge ports: - "8501:8501" # Or replace 8501 on the left with your desired port
docker-compose up -ddocker logs -f channelwatchConfiguration is managed through the web UI at http://your-server-ip:8501
| Setting | Description |
|---|---|
| Channels DVR Host | Server IP or hostname |
| Channels DVR Port | Server port (default: 8089) |
| Timezone | Local timezone for timestamps |
| Log Level | Standard or Verbose logging |
| Log Retention | Auto-cleanup period in days |
| Alert | Description |
|---|---|
| Channel Watching | Live TV viewing notifications |
| VOD Watching | Recorded content playback alerts |
| Recording Events | Track recording lifecycle |
| Stream Counting | Show total active streams |
| Option | Description |
|---|---|
| Image Source | Channel Logo or Program Image |
| Show Channel Name | Display channel name |
| Show Channel Number | Display channel number |
| Show Program Name | Display program title |
| Show Device Name | Display device name |
| Show Device IP | Display device IP address |
| Show Stream Source | Display stream source |
| Option | Description |
|---|---|
| Show Title | Display content title |
| Show Episode Title | Display episode title for TV shows |
| Show Summary | Display content summary/description |
| Show Content Image | Display thumbnail image |
| Show Duration | Display content duration |
| Show Progress | Display playback progress |
| Show Rating | Display content rating |
| Show Genres | Display content genres |
| Show Cast | Display cast members |
| Show Device Name | Display device name |
| Show Device IP | Display device IP address |
| Option | Description |
|---|---|
| Scheduled Events | Show alerts for scheduled recordings |
| Started Events | Show alerts when recordings start |
| Completed Events | Show alerts when recordings complete |
| Cancelled Events | Show alerts when recordings are cancelled |
| Show Program Name | Display program name |
| Show Description | Display program description |
| Show Duration | Display recording duration |
| Show Channel Name | Display channel name |
| Show Channel Number | Display channel number |
| Show Recording Type | Display if recording is scheduled or manual |
| Provider | Description | Config Needed |
|---|---|---|
| Pushover | Mobile/Desktop notifications | User Key, API Token |
| Discord | Chat channel notifications | Webhook URL |
| Telegram | Chat messaging | Bot Token/Chat ID |
| Standard email | SMTP Settings | |
| Slack | Chat messaging | Webhook URL (token format) |
| Gotify | Self-hosted notifications | Server URL & Token |
| Matrix | Decentralized chat | Room/User credentials |
| Custom | Any Apprise-supported service | URL |
📺 ABC
Channel: 7
Program: Good Morning America
Device: Living Room
IP: 192.168.1.101
Source: HDHR
🎬 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
⚠️ Low Disk Space Warning
Free Space: 200.59 GB / 1.82 TB (10.8%)
Used Space: 1.62 TB
DVR Path: /shares/DVR
📺 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).
📺 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.
📺 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.
📺 SCI-FI CHANNEL
Channel: 152
Status: ⏹️ Stopped
Program: Pandorum (2009)
-----------------------
Duration: 20 minutes
Total Streams: 1
Astronauts awake to a terrifying reality aboard a seemingly abandoned spaceship.
Access diagnostics tools at http://your-server-ip:8501 and navigate to the "Diagnostics" tab:
- System Status - Overview of service health and connectivity
- Connection Tests - Verify connectivity to Channels DVR
- API Tests - Check endpoint functionality
- Alert Tests - Send test notifications for each alert type
For automation or headless troubleshooting:
# Test connectivity
docker exec -it channelwatch python -m channelwatch.main --test-connectivity
# Test API endpoints
docker exec -it channelwatch python -m channelwatch.main --test-api
# Test individual alert types
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_CHANNEL_WATCHING
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_VOD_WATCHING
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_DISK_SPACE
docker exec -it channelwatch python -m channelwatch.main --test-alert ALERT_RECORDING_EVENTS
# Monitor event stream for 60 seconds
docker exec -it channelwatch python -m channelwatch.main --monitor-events 60- Check logs:
docker logs channelwatch - Verify notification provider credentials are correct
- Ensure Channels DVR server is accessible (test connection)
- Check if notification service is operational (test with diagnostic panel)
- Confirm alerts are properly configured and enabled
To upgrade to the latest version:
docker-compose pull
docker-compose up -dMaintainer release rules are documented in RELEASE.md. Release changes should land as one commit on main, with the commit subject exactly matching the release tag, such as v0.8.1. The matching git tag and GitHub Release should be created in the same release flow, and public release text should read as maintainer-authored copy without tool attribution.
ChannelWatch/
├── core/ # Core backend logic (Python)
│ ├── docker-entrypoint.sh # Container startup script
│ ├── alerts/ # Alert handling modules (one per alert type)
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── channel_watching.py
│ │ ├── disk_space.py
│ │ ├── recording_events.py
│ │ ├── vod_watching.py
│ │ └── common/ # Shared alert utilities (formatting, sessions)
│ │ ├── __init__.py
│ │ ├── alert_formatter.py
│ │ ├── cleanup_mixin.py
│ │ ├── session_manager.py
│ │ └── stream_tracker.py
│ ├── engine/ # Event processing engine & orchestration
│ │ ├── __init__.py
│ │ ├── alert_manager.py
│ │ └── event_monitor.py
│ ├── helpers/ # Backend utilities & data providers (config, logging, API interactions)
│ │ ├── __init__.py
│ │ ├── activity_recorder.py
│ │ ├── channel_info.py
│ │ ├── config.py
│ │ ├── initialize.py
│ │ ├── job_info.py
│ │ ├── logging.py
│ │ ├── parsing.py
│ │ ├── program_info.py
│ │ ├── recording_info.py
│ │ ├── tools.py
│ │ ├── type_utils.py
│ │ └── vod_info.py
│ ├── notifications/ # Notification sending system
│ │ ├── __init__.py
│ │ ├── notification.py
│ │ └── providers/ # Specific notification services (Pushover, Apprise)
│ │ ├── __init__.py
│ │ ├── apprise.py
│ │ ├── base.py
│ │ └── pushover.py
│ ├── test/ # Backend test framework & simulations
│ │ ├── __init__.py
│ │ ├── alerts/ # Alert simulation tests
│ │ │ ├── __init__.py
│ │ │ ├── test_channel_watching.py
│ │ │ ├── test_disk_space.py
│ │ │ ├── test_recording_events.py
│ │ │ └── test_vod_watching.py
│ │ ├── connectivity/ # Server connection tests
│ │ │ ├── __init__.py
│ │ │ └── test_server.py
│ │ └── utils/ # Test helper utilities
│ │ ├── __init__.py
│ │ └── test_utils.py
│ ├── main.py # Backend entry point (CLI/testing)
│ └── __init__.py # Backend package marker & version info
├── ui/ # Web Interface (Next.js/React frontend, FastAPI backend)
│ ├── app/ # Next.js frontend application root
│ │ ├── layout.tsx
│ │ ├── page.tsx
│ │ └── globals.css
│ ├── backend/ # FastAPI backend serving the UI API
│ │ ├── main.py
│ │ ├── config.py
│ │ └── schemas.py
│ ├── components/ # React UI components
│ │ ├── base/ # shadcn/ui base components
│ │ │ ├── alert.tsx
│ │ │ ├── badge.tsx
│ │ │ ├── button.tsx
│ │ │ ├── card.tsx
│ │ │ ├── checkbox.tsx
│ │ │ ├── command.tsx
│ │ │ ├── dialog.tsx
│ │ │ ├── dropdown-menu.tsx
│ │ │ ├── form.tsx
│ │ │ ├── input.tsx
│ │ │ ├── label.tsx
│ │ │ ├── popover.tsx
│ │ │ ├── progress.tsx
│ │ │ ├── select.tsx
│ │ │ ├── separator.tsx
│ │ │ ├── switch.tsx
│ │ │ ├── tabs.tsx
│ │ │ ├── toast.tsx
│ │ │ ├── toaster.tsx
│ │ │ └── tooltip.tsx
│ │ ├── dashboard.tsx
│ │ ├── header.tsx
│ │ ├── settings-form.tsx
│ │ ├── sidebar.tsx
│ │ ├── diagnostics-panel.tsx
│ │ ├── about-section.tsx
│ │ ├── mode-toggle.tsx
│ │ ├── status-overview.tsx
│ │ └── theme-provider.tsx
│ ├── hooks/ # Custom React hooks
│ │ └── use-toast.ts
│ ├── lib/ # Frontend helper libraries & utilities
│ │ ├── api.ts
│ │ ├── types.ts
│ │ └── utils.ts
│ ├── public/ # Static assets (images, favicon)
│ │ ├── images/ # Image assets
│ │ │ ├── channelwatch-logo.png
│ │ │ ├── background-bio.webp
│ │ │ └── coder-luii.png
│ │ ├── favicon.png
│ │ └── og-image.png
│ ├── types/ # Custom TypeScript definitions
│ │ └── global.d.ts
│ ├── components.json
│ ├── next-env.d.ts
│ ├── next.config.mjs
│ ├── package.json
│ ├── pnpm-lock.yaml
│ ├── postcss.config.mjs
│ ├── tailwind.config.ts
│ └── tsconfig.json
├── Dockerfile # Docker container build instructions
├── docker-compose.yml # Example Docker deployment file
├── supervisord.conf # Process manager (supervisor) configuration
├── requirements.txt # Python dependency list (backend)
└── README.md
MIT License - see the LICENSE file for details.
- Channels DVR for exceptional DVR software
- Pushover and Apprise for powering the notification capabilities
- Shadcn/ui for the beautiful and responsive UI components
ChannelWatch will continue to evolve with these planned enhancements:
- Custom notification templates with variable support
- Error alerting for system and connection issues
- Live container log feed in diagnostic page
Contributions, issues, and feature requests are welcome!
