feat: add change detection capture mode

- New capture mode that captures frames only when screen content changes

- Configurable threshold, minInterval, maxInterval, sampleRate options

- New CHANGE_DETECTED event for debugging and monitoring

- ChangeDetector.kt with pixel sampling algorithm

- Updated example app with mode selection UI

- Updated documentation (README, configuration, events, usage-examples)

Author: nasyx-rakeeb

CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2025-02-09
+
+### Added
+
+#### Change Detection Capture Mode
+
+- New capture mode that captures frames only when screen content changes
+- Configurable change detection options:
+  - `threshold` - Percentage of pixels that must change to trigger capture (1-100%)
+  - `minInterval` - Minimum milliseconds between captures (100-60000ms)
+  - `maxInterval` - Maximum milliseconds before forced capture (0 = disabled)
+  - `sampleRate` - Pixel sampling rate for performance optimization (1-100)
+  - `detectionRegion` - Optional region to monitor for changes
+- New `CHANGE_DETECTED` event for debugging and monitoring
+- Pixel sampling algorithm for efficient frame comparison
+
+### Example
+
+```typescript
+await FrameCapture.startCapture({
+  capture: {
+    mode: 'change-detection',
+    changeDetection: {
+      threshold: 15, // Capture when 15% of screen changes
+      minInterval: 500, // Poll every 500ms
+      maxInterval: 5000, // Force capture at least every 5s
+    },
+  },
+  image: { quality: 80, format: 'jpeg' },
+});
+```
+
+---
+
 ## [1.0.0] - 2025-11-11
 
 ### Added
@@ -141,4 +175,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 This is the initial stable release of React Native Frame Capture. The library provides production-ready screen capture functionality with a focus on reliability, performance, and developer experience.
 
+[1.1.0]: https://github.com/nasyx-rakeeb/react-native-frame-capture/releases/tag/v1.1.0
 [1.0.0]: https://github.com/nasyx-rakeeb/react-native-frame-capture/releases/tag/v1.0.0

README.md

@@ -5,11 +5,12 @@
 [![license](https://img.shields.io/npm/l/react-native-frame-capture.svg)](https://github.com/nasyx-rakeeb/react-native-frame-capture/blob/main/LICENSE)
 [![platform](https://img.shields.io/badge/platform-Android-green.svg)](https://www.android.com/)
 
-Reliable screen capture for React Native Android. Capture frames at intervals with customizable overlays and storage options.
+Reliable screen capture for React Native Android. Capture frames at intervals or when screen content changes, with customizable overlays and storage options.
 
 ## Features
 
 - 📸 **Interval-based capture** - Capture frames at configurable intervals (100ms - 60s)
+- 🔍 **Change detection mode** - Capture only when screen content changes (NEW!)
 - 🎨 **Customizable overlays** - Add text and image overlays with template variables
 - 💾 **Flexible storage** - Save to app-specific, public, or custom directories
 - 🔄 **Background capture** - Continues capturing when app is minimized (foreground service)

android/src/main/java/com/framecapture/CaptureManager.kt

@@ -22,8 +22,10 @@ import com.framecapture.models.CaptureState
 import com.framecapture.models.CaptureStatus
 import com.framecapture.models.ErrorCode
 import com.framecapture.models.FrameInfo
+import com.framecapture.models.CaptureMode
 import com.framecapture.capture.CaptureEventEmitter
 import com.framecapture.capture.BitmapProcessor
+import com.framecapture.capture.ChangeDetector
 import java.util.UUID
 import java.util.concurrent.ExecutorService
 import java.util.concurrent.Executors
@@ -88,6 +90,9 @@ class CaptureManager(
     private lateinit var eventEmitterManager: CaptureEventEmitter
     private lateinit var bitmapProcessor: BitmapProcessor
 
+    // Change detection support
+    private var changeDetector: ChangeDetector? = null
+
     companion object {
         private const val TAG = "CaptureManager"
         private const val VIRTUAL_DISPLAY_NAME = "ScreenCapture"
@@ -357,6 +362,158 @@ class CaptureManager(
         }
     }
 
+    /**
+     * Starts change detection capture mode
+     *
+     * Polls for frames at minInterval and compares them to detect changes.
+     * Only captures when change exceeds threshold or maxInterval forces capture.
+     */
+    private fun startChangeDetectionCapture() {
+        try {
+            val changeConfig = captureOptions?.changeDetection
+            val minInterval = changeConfig?.minInterval ?: Constants.DEFAULT_CHANGE_MIN_INTERVAL
+            val maxInterval = changeConfig?.maxInterval ?: Constants.DEFAULT_CHANGE_MAX_INTERVAL
+            val threshold = changeConfig?.threshold ?: Constants.DEFAULT_CHANGE_THRESHOLD
+
+            captureRunnable = object : Runnable {
+                override fun run() {
+                    try {
+                        if (isCapturing && !isPaused) {
+                            val image = imageReader?.acquireLatestImage()
+                            if (image != null) {
+                                processingExecutor.execute {
+                                    try {
+                                        processChangeDetectionFrame(image, threshold, minInterval, maxInterval)
+                                    } catch (e: Exception) {
+                                        Log.e(TAG, "Error processing change detection frame", e)
+                                        handleError(e)
+                                    } finally {
+                                        image.close()
+                                    }
+                                }
+                            }
+                        }
+
+                        // Schedule next check if still capturing
+                        if (isCapturing) {
+                            captureHandler.postDelayed(this, minInterval)
+                        }
+                    } catch (e: Exception) {
+                        Log.e(TAG, "Error in change detection runnable", e)
+                        handleError(e)
+                    }
+                }
+            }
+
+            // Start the change detection polling
+            captureHandler.post(captureRunnable!!)
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start change detection capture", e)
+            throw e
+        }
+    }
+
+    /**
+     * Processes a frame for change detection
+     *
+     * Compares frame with previous, determines if capture should occur,
+     * and emits change detection events.
+     */
+    private fun processChangeDetectionFrame(
+        image: Image,
+        threshold: Float,
+        minInterval: Long,
+        maxInterval: Long
+    ) {
+        var bitmap: Bitmap? = null
+
+        try {
+            // Convert to bitmap for comparison
+            bitmap = bitmapProcessor.imageToBitmap(image, captureOptions)
+
+            val currentTime = System.currentTimeMillis()
+            val timeSinceLastCapture = currentTime - lastCaptureTime
+
+            // Detect change percentage
+            val detector = changeDetector ?: return
+            val changePercent = detector.detectChange(bitmap)
+
+            // Determine if we should capture
+            val shouldCaptureDueToChange = changePercent >= threshold
+            val shouldCaptureDueToMaxInterval = maxInterval > 0 && timeSinceLastCapture >= maxInterval
+            val hasMinIntervalPassed = timeSinceLastCapture >= minInterval
+
+            val shouldDoCapture = hasMinIntervalPassed && (shouldCaptureDueToChange || shouldCaptureDueToMaxInterval)
+
+            // Emit change detected event for debugging/monitoring
+            eventEmitterManager.emitChangeDetected(
+                changePercent = changePercent,
+                threshold = threshold,
+                captured = shouldDoCapture,
+                timeSinceLastCapture = timeSinceLastCapture
+            )
+
+            if (shouldDoCapture) {
+                // Update previous frame for next comparison
+                detector.updatePreviousFrame(bitmap)
+                lastCaptureTime = currentTime
+
+                // Process and save the frame (reuse processImage logic)
+                processImageFromBitmap(bitmap)
+                // Don't recycle - processImageFromBitmap handles it
+                bitmap = null
+            }
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Error in change detection frame processing", e)
+            handleError(e)
+        } finally {
+            bitmap?.recycle()
+        }
+    }
+
+    /**
+     * Processes an already-converted bitmap (for change detection mode)
+     */
+    private fun processImageFromBitmap(bitmap: Bitmap) {
+        try {
+            val currentSessionId = sessionId ?: throw IllegalStateException("No active session")
+            val currentOptions = captureOptions ?: throw IllegalStateException("No capture options")
+
+            frameCount++
+
+            // Render overlays if configured
+            val overlays = currentOptions.overlays
+            if (!overlays.isNullOrEmpty()) {
+                overlayRenderer.renderOverlays(
+                    bitmap = bitmap,
+                    overlays = overlays,
+                    frameNumber = frameCount - 1,
+                    sessionId = currentSessionId
+                )
+            }
+
+            // Check storage space and emit warning if low
+            val threshold = currentOptions.advanced.storage.warningThreshold
+            storageManager.isStorageAvailable(threshold)
+
+            // Save frame (temp or permanent based on saveFrames option)
+            val frameInfo = storageManager.saveFrame(
+                bitmap = bitmap,
+                sessionId = currentSessionId,
+                frameNumber = frameCount - 1,
+                options = currentOptions
+            )
+
+            // Emit frame captured event
+            eventEmitterManager.emitFrameCaptured(frameInfo, frameCount - 1)
+
+        } finally {
+            bitmap.recycle()
+        }
+    }
+
     /**
      * Checks if a frame should be captured based on throttling logic
      *
@@ -475,7 +632,8 @@ class CaptureManager(
     /**
      * Starts the capture session
      *
-     * Sets up VirtualDisplay and ImageReader, then begins interval-based periodic capture.
+     * Sets up VirtualDisplay and ImageReader, then begins capture based on configured mode.
+     * Supports interval-based capture and change-detection capture.
      *
      * @throws IllegalStateException if already capturing or not initialized
      */
@@ -506,8 +664,24 @@ class CaptureManager(
             // Create VirtualDisplay
             createVirtualDisplay(metrics)
 
-            // Start periodic capture (interval mode only)
-            startPeriodicCapture()
+            // Start capture based on mode
+            val options = captureOptions!!
+            when (options.captureMode) {
+                CaptureMode.CHANGE_DETECTION -> {
+                    // Initialize change detector
+                    val changeConfig = options.changeDetection
+                    changeDetector = ChangeDetector(
+                        threshold = changeConfig?.threshold ?: Constants.DEFAULT_CHANGE_THRESHOLD,
+                        sampleRate = changeConfig?.sampleRate ?: Constants.DEFAULT_CHANGE_SAMPLE_RATE,
+                        detectionRegion = changeConfig?.detectionRegion
+                    )
+                    startChangeDetectionCapture()
+                }
+                else -> {
+                    // Default to interval mode
+                    startPeriodicCapture()
+                }
+            }
 
             // Emit capture start event to JavaScript
             val currentSessionId = sessionId ?: throw IllegalStateException("No session ID")
@@ -716,6 +890,14 @@ class CaptureManager(
                 Log.e(TAG, "Error clearing overlay caches", e)
             }
 
+            // Clear change detector
+            try {
+                changeDetector?.clear()
+                changeDetector = null
+            } catch (e: Exception) {
+                Log.e(TAG, "Error clearing change detector", e)
+            }
+
             // Clear all state variables
             captureOptions = null
             sessionId = null

android/src/main/java/com/framecapture/Constants.kt

@@ -28,6 +28,14 @@ object Constants {
 
     // Capture mode strings
     const val CAPTURE_MODE_INTERVAL = "interval"
+    const val CAPTURE_MODE_CHANGE_DETECTION = "change-detection"
+
+    // Change detection defaults
+    const val DEFAULT_CHANGE_THRESHOLD = 5f              // 5% of pixels changed
+    const val DEFAULT_CHANGE_MIN_INTERVAL = 500L         // 500ms minimum between captures
+    const val DEFAULT_CHANGE_MAX_INTERVAL = 0L           // 0 = disabled (no forced captures)
+    const val DEFAULT_CHANGE_SAMPLE_RATE = 16            // Sample every 16th pixel
+    const val CHANGE_PIXEL_TOLERANCE = 10                // RGB difference tolerance for "changed" pixel
 
     // Storage warning threshold (100MB in bytes) - DEFAULT VALUE
     const val DEFAULT_STORAGE_WARNING_THRESHOLD = 100L * 1024L * 1024L
@@ -108,6 +116,7 @@ object Constants {
     const val EVENT_CAPTURE_PAUSE = "onCapturePause"
     const val EVENT_CAPTURE_RESUME = "onCaptureResume"
     const val EVENT_OVERLAY_ERROR = "onOverlayError"
+    const val EVENT_CHANGE_DETECTED = "onChangeDetected"
 
     // Resource cleanup timeout (in milliseconds) - DEFAULT VALUES
     const val DEFAULT_EXECUTOR_SHUTDOWN_TIMEOUT = 5000L

android/src/main/java/com/framecapture/capture/CaptureEventEmitter.kt

@@ -117,4 +117,34 @@ class CaptureEventEmitter(
             // Silently fail - event emission is not critical
         }
     }
+
+    /**
+     * Emits onChangeDetected event to JavaScript for debugging/monitoring
+     *
+     * Contains change detection results even when capture is not triggered.
+     *
+     * @param changePercent Percentage of pixels that changed (0-100)
+     * @param threshold The configured threshold for triggering capture
+     * @param captured Whether a capture was triggered
+     * @param timeSinceLastCapture Milliseconds since last capture
+     */
+    fun emitChangeDetected(
+        changePercent: Float,
+        threshold: Float,
+        captured: Boolean,
+        timeSinceLastCapture: Long
+    ) {
+        try {
+            val params = Arguments.createMap().apply {
+                putDouble("changePercent", changePercent.toDouble())
+                putDouble("threshold", threshold.toDouble())
+                putBoolean("captured", captured)
+                putDouble("timeSinceLastCapture", timeSinceLastCapture.toDouble())
+            }
+            eventEmitter(Constants.EVENT_CHANGE_DETECTED, params)
+        } catch (e: Exception) {
+            // Silently fail - event emission is not critical
+        }
+    }
 }
+