Feat/ffmpeg motion detection #1536
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Improve snapshot performance by intelligently choosing between direct HTTP/HTTPS fetching and FFmpeg-based extraction. Changes: - Add direct HTTP/HTTPS fetch for plain URL sources - Automatically detect URL vs FFmpeg-style sources using regex - Use native Node http/https modules for direct URLs (much faster) - Maintain FFmpeg fallback for RTSP streams and complex sources - Add 10-second timeout for HTTP requests with proper error handling - Update CLAUDE.md with snapshot fetching documentation Benefits: - Significantly faster snapshot retrieval for HTTP/HTTPS URLs - Reduced system resource usage (no FFmpeg process spawn) - Backward compatible with all existing configurations - Better error messages for debugging Example configurations: - Direct URL: "http://192.168.1.100/snapshot.jpg" (uses HTTP fetch) - RTSP: "-i rtsp://192.168.1.100:554/stream" (uses FFmpeg) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Update the configuration validation to accept direct HTTP/HTTPS URLs in stillImageSource without requiring the "-i" FFmpeg flag. Changes: - Check if stillImageSource is a direct URL using regex - Skip "-i" validation for HTTP/HTTPS URLs - Maintain validation for FFmpeg-style sources This prevents false warnings when using direct snapshot URLs like: "stillImageSource": "http://192.168.1.100/snapshot.jpg" Related to the snapshot fetching optimization that now supports direct HTTP fetching for better performance. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add documentation for the improved configuration validation that correctly handles HTTP/HTTPS URLs in stillImageSource. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Implements automatic motion detection by analyzing video streams using FFmpeg's scene change detection filter. This enables cameras to automatically trigger motion events without external sensors or scripts. Features: - Analyzes lower-resolution subSource stream to reduce CPU usage - Configurable sensitivity threshold (0.01-0.1, default 0.03) - Auto-restart on process failure with 10-second delay - Integrates with existing motion sensor and automation system - Reuses motionTimeout for cooldown period Configuration: - ffmpegMotionDetection: Enable/disable automatic detection - ffmpegMotionSensitivity: Scene change threshold - videoConfig.subSource: Lower resolution stream URL for analysis Requires motion sensor to be enabled (motion: true) and subSource to be configured. Process runs independently from streaming and logs scene scores when motion is detected. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Changed subSource to accept full FFmpeg arguments instead of just the URL, making it consistent with the source field syntax. This provides better flexibility and a more intuitive configuration. Before: "subSource": "rtsp://camera.local:554/sub" After: "subSource": "-rtsp_transport tcp -i rtsp://camera.local:554/sub" Also cleaned up unused motion detection methods from ffmpeg.ts since the implementation is now entirely in platform.ts. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Added a comprehensive configuration example showing how to properly configure FFmpeg motion detection with all required fields. Clarified that subSource uses the same syntax as source (full FFmpeg arguments). Also updated component descriptions to reflect that motion detection logic is now entirely in platform.ts. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive documentation for the new FFmpeg motion detection feature including configuration options, requirements, and complete usage example. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
- Move subSource to "Most Important Parameters" section with clear emphasis that it's required for ffmpegMotionDetection - Document two snapshot formats: direct HTTP/HTTPS URLs (faster) vs FFmpeg sources - Update config example to show subSource usage and HTTP snapshot URL - Remove duplicate subSource documentation from videoConfig section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
♻️ Current situation
Currently, the plugin requires external motion detection systems (MQTT, HTTP triggers, or
camera motion events) to trigger the HomeKit motion sensor. Many IP cameras support motion
detection but don't expose it via MQTT or HTTP, requiring users to set up additional
automation systems.
Additionally, the snapshot fetching always used FFmpeg even for simple HTTP URLs, adding
unnecessary overhead.
💡 Proposed solution
This PR adds FFmpeg-based motion detection using scene change analysis, allowing the
plugin to automatically detect motion by analyzing the camera's video stream without external
dependencies.
Key changes:
ffmpegMotionDetectionoption to enable automatic motion detectionffmpegMotionSensitivityto control detection threshold (0.01-0.1)videoConfig.subSourceto specify a lower-resolution stream for motion analysis(reduces CPU usage)
stillImageSourceis aplain URL (faster than FFmpeg)
The motion detection process runs independently from streaming, auto-restarts on failure, and
integrates seamlessly with existing motion handlers.
⚙️ Release Notes
New Features:
ffmpegMotionDetectionto automatically detectmotion using FFmpeg scene analysis
videoConfig.subSourceto use a lower-resolution streamfor motion detection (reduces CPU usage)
performance
Configuration:
{ "name": "Front Camera", "motion": true, "ffmpegMotionDetection": true, "ffmpegMotionSensitivity": 0.04, "videoConfig": { "source": "-i rtsp://camera.local:554/stream0", "subSource": "-i rtsp://camera.local:554/stream1", "stillImageSource": "http://camera.local/snapshot.jpg" } }Breaking Changes: None - all new features are opt-in.
➕ Additional Information
Testing
Edge cases not yet covered: Very high-FPS streams, cameras with unusual scene change
patterns.
Reviewer Nudging
Start with platform.ts:startMotionDetection() (line ~720) to see the motion detection
implementation, then check streamingDelegate.ts:fetchSnapshot() for the snapshot
optimization. Configuration validation is in platform.ts constructor.