react-native-frame-capture 1.0.1

package/android/src/main/java/com/framecapture/ScreenCaptureService.kt

@@ -0,0 +1,366 @@
+package com.framecapture
+
+import android.app.Service
+import android.content.Intent
+import android.os.IBinder
+import android.util.Log
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.framecapture.models.CaptureOptions
+import com.framecapture.models.NotificationOptions
+import com.framecapture.service.CaptureNotificationManager
+
+/**
+ * Foreground service for reliable background screen capture
+ *
+ * This service ensures screen capture continues even when the app is minimized,
+ * backgrounded, or the screen is off. It displays a persistent notification
+ * (required for foreground services) and manages the CaptureManager lifecycle.
+ *
+ * Key responsibilities:
+ * - Manages CaptureManager lifecycle (start/stop/pause/resume)
+ * - Displays and updates foreground notification
+ * - Bridges events between CaptureManager and FrameCaptureModule
+ * - Handles notification button actions (pause/resume/stop)
+ */
+class ScreenCaptureService : Service() {
+
+    companion object {
+        private const val TAG = "ScreenCaptureService"
+
+        // Notification constants
+        const val CHANNEL_ID = Constants.CHANNEL_ID
+        const val NOTIFICATION_ID = Constants.NOTIFICATION_ID
+
+        // Service actions
+        const val ACTION_START = Constants.ACTION_START_CAPTURE
+        const val ACTION_STOP = Constants.ACTION_STOP_CAPTURE
+        const val ACTION_PAUSE = Constants.ACTION_PAUSE_CAPTURE
+        const val ACTION_RESUME = Constants.ACTION_RESUME_CAPTURE
+
+        // Intent extras
+        const val EXTRA_OPTIONS = Constants.EXTRA_CAPTURE_OPTIONS
+        const val EXTRA_PROJECTION_DATA = Constants.EXTRA_PROJECTION_DATA
+
+        // Static reference to FrameCaptureModule for event emission
+        @Volatile
+        private var FrameCaptureModule: FrameCaptureModule? = null
+
+        // Static frame count shared between service and module
+        @Volatile
+        var currentFrameCount: Int = 0
+            private set
+
+        /**
+         * Sets the FrameCaptureModule reference for event emission
+         *
+         * Must be called from FrameCaptureModule before starting the service.
+         * This allows the service to emit events to JavaScript.
+         */
+        fun setFrameCaptureModule(module: FrameCaptureModule?) {
+            FrameCaptureModule = module
+        }
+
+        /**
+         * Updates the frame count
+         * Called from the service to keep the count synchronized with the module
+         */
+        fun updateFrameCount(count: Int) {
+            currentFrameCount = count
+        }
+
+        /**
+         * Resets the frame count to zero
+         * Called when a capture session starts or stops
+         */
+        fun resetFrameCount() {
+            currentFrameCount = 0
+        }
+    }
+
+    // CaptureManager instance for handling screen capture
+    private var captureManager: CaptureManager? = null
+
+    // StorageManager for saving frames
+    private var storageManager: StorageManager? = null
+
+    // Notification manager for handling notifications
+    private var notificationManager: CaptureNotificationManager? = null
+
+    // Frame counter for notification updates
+    private var frameCounter: Int = 0
+
+    // Paused state for notification updates
+    private var isPaused: Boolean = false
+
+    override fun onCreate() {
+        super.onCreate()
+
+        // Notification channel is created in onStartCommand after parsing options
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        when (intent?.action) {
+            ACTION_START -> {
+                // Extract options and projection data from intent
+                val options = intent.getParcelableExtra<android.os.Bundle>(EXTRA_OPTIONS)
+                val projectionData = intent.getParcelableExtra<Intent>(EXTRA_PROJECTION_DATA)
+
+                if (options != null && projectionData != null) {
+                    try {
+                        // Parse notification options before creating notifications
+                        val optionsMap = Arguments.fromBundle(options)
+                        val captureOptions = CaptureOptions.fromReadableMap(optionsMap)
+
+                        val notificationOptions = captureOptions.notification ?: NotificationOptions()
+
+                        // Create notification manager with custom options
+                        notificationManager = CaptureNotificationManager(this, notificationOptions)
+
+                        // Create notification channel (Android 8.0+)
+                        notificationManager?.createNotificationChannel()
+
+                        // Start as foreground service (required for background capture)
+                        startForeground(NOTIFICATION_ID, notificationManager?.createNotification())
+
+                        // Initialize and start capture
+                        startCapture(options, projectionData, notificationOptions)
+                    } catch (e: Exception) {
+                        Log.e(TAG, "Failed to start capture service", e)
+                        stopSelf()
+                    }
+                } else {
+                    stopSelf()
+                }
+            }
+
+            ACTION_STOP -> {
+                stopCapture()
+                stopSelf()
+            }
+
+            ACTION_PAUSE -> {
+                pauseCapture()
+            }
+
+            ACTION_RESUME -> {
+                resumeCapture()
+            }
+
+            else -> {
+                stopSelf()
+            }
+        }
+
+        // START_STICKY: System will restart service if killed
+        return START_STICKY
+    }
+
+    override fun onBind(intent: Intent?): IBinder? {
+        // This is not a bound service
+        return null
+    }
+
+    override fun onDestroy() {
+        // Ensure capture is stopped and resources are released
+        try {
+            stopCapture()
+        } catch (e: Exception) {
+            Log.e(TAG, "Error stopping capture in onDestroy", e)
+        }
+
+        super.onDestroy()
+    }
+
+    // ========== Capture Management ==========
+
+    /**
+     * Starts screen capture with the specified options
+     *
+     * Creates and initializes CaptureManager and StorageManager, sets up event
+     * handlers for frame capture and notification updates, then starts capture.
+     *
+     * @param optionsBundle Capture options as Android Bundle
+     * @param projectionData MediaProjection permission data
+     * @param notificationOptions Notification customization options
+     */
+    private fun startCapture(optionsBundle: android.os.Bundle, projectionData: Intent, notificationOptions: NotificationOptions) {
+        try {
+            // Convert Bundle to CaptureOptions
+            val optionsMap = Arguments.fromBundle(optionsBundle)
+            val captureOptions = CaptureOptions.fromReadableMap(optionsMap)
+
+            // Create StorageManager if needed
+            if (storageManager == null) {
+                // Event emitter for StorageManager (handles storage warnings)
+                val eventEmitter: (String, WritableMap?) -> Unit = { eventName, params ->
+                    // Handle frame captured events for notification updates
+                    if (eventName == Constants.EVENT_FRAME_CAPTURED) {
+                        params?.let {
+                            if (it.hasKey("frameNumber")) {
+                                frameCounter = it.getInt("frameNumber") + 1
+
+                                // Update notification based on configured interval
+                                if (notificationOptions.showFrameCount &&
+                                    notificationOptions.updateInterval > 0 &&
+                                    frameCounter % notificationOptions.updateInterval == 0) {
+                                    notificationManager?.updateNotification(frameCounter)
+                                }
+                            }
+                        }
+                    }
+
+                    // Forward storage warnings to JavaScript
+                    if (eventName == Constants.EVENT_STORAGE_WARNING) {
+                        try {
+                            val module = FrameCaptureModule
+                            if (module != null && params != null) {
+                                module.emitOnStorageWarning(params)
+                            }
+                        } catch (e: Exception) {
+                            Log.e(TAG, "Failed to emit storage warning: ${e.message}", e)
+                        }
+                    }
+                }
+
+                // Initialize StorageManager for frame persistence
+                storageManager = StorageManager(
+                    applicationContext,
+                    eventEmitter
+                )
+            }
+
+            // Initialize CaptureManager with event handlers
+            captureManager = CaptureManager(
+                applicationContext,
+                storageManager!!,
+                { eventName, params ->
+                    // Handle frame captured events
+                    if (eventName == Constants.EVENT_FRAME_CAPTURED) {
+                        frameCounter++
+                        // Sync frame count with module
+                        updateFrameCount(frameCounter)
+
+                        // Update notification based on configuration
+                        if (!isPaused &&
+                            notificationOptions.showFrameCount &&
+                            notificationOptions.updateInterval > 0 &&
+                            frameCounter % notificationOptions.updateInterval == 0) {
+                            notificationManager?.updateNotification(frameCounter)
+                        }
+                    }
+
+                    // Forward events to JavaScript via FrameCaptureModule
+                    try {
+                        val module = FrameCaptureModule
+                        if (module != null && params != null) {
+                            when (eventName) {
+                                Constants.EVENT_FRAME_CAPTURED -> module.emitOnFrameCaptured(params)
+                                Constants.EVENT_CAPTURE_ERROR -> module.emitOnCaptureError(params)
+                                Constants.EVENT_CAPTURE_STOP -> module.emitOnCaptureStop(params)
+                                Constants.EVENT_CAPTURE_START -> module.emitOnCaptureStart(params)
+                                Constants.EVENT_STORAGE_WARNING -> module.emitOnStorageWarning(params)
+                                Constants.EVENT_OVERLAY_ERROR -> module.emitOnOverlayError(params)
+                            }
+                        }
+                    } catch (e: Exception) {
+                        Log.e(TAG, "Failed to send event: $eventName", e)
+                    }
+                }
+            )
+
+            // Initialize with MediaProjection permission and options
+            captureManager?.initialize(projectionData, captureOptions)
+
+            // Start capture
+            captureManager?.start()
+
+            // Reset counters and state for new session
+            frameCounter = 0
+            resetFrameCount()
+            isPaused = false
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start capture in service", e)
+            throw e
+        }
+    }
+
+    /**
+     * Stops screen capture and cleans up all resources
+     *
+     * Notifies the module, stops capture, releases CaptureManager,
+     * and resets all state variables.
+     */
+    private fun stopCapture() {
+        try {
+            // Notify module first to update state
+            FrameCaptureModule?.updateStateFromService(isStopped = true)
+
+            // Stop capture (emits onCaptureStop event)
+            captureManager?.stop()
+
+            // Cleanup resources
+            captureManager?.cleanup()
+            captureManager = null
+
+            // Reset counters and state
+            frameCounter = 0
+            resetFrameCount()
+            isPaused = false
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Error stopping capture in service", e)
+        }
+    }
+
+    /**
+     * Pauses screen capture
+     *
+     * Stops capturing frames but keeps the service and notification active.
+     * Updates notification to show paused state with resume button.
+     */
+    private fun pauseCapture() {
+        try {
+            // Pause capture
+            captureManager?.pause()
+
+            // Update paused state
+            isPaused = true
+
+            // Update notification to show paused state
+            notificationManager?.updateNotificationPaused(frameCounter)
+
+            // Notify module about pause
+            FrameCaptureModule?.updateStateFromService(isPaused = true)
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Error pausing capture in service", e)
+        }
+    }
+
+    /**
+     * Resumes screen capture from paused state
+     *
+     * Restarts frame capture and updates notification to show active state
+     * with pause button.
+     */
+    private fun resumeCapture() {
+        try {
+            // Resume capture
+            captureManager?.resume()
+
+            // Update paused state
+            isPaused = false
+
+            // Update notification to show active state
+            notificationManager?.updateNotification(frameCounter)
+
+            // Notify module about resume
+            FrameCaptureModule?.updateStateFromService(isPaused = false)
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Error resuming capture in service", e)
+        }
+    }
+}

package/android/src/main/java/com/framecapture/StorageManager.kt

@@ -0,0 +1,221 @@
+package com.framecapture
+
+import android.graphics.Bitmap
+import android.os.Build
+import android.os.StatFs
+import android.util.Log
+import com.framecapture.models.CaptureOptions
+import com.framecapture.models.FrameInfo
+import com.framecapture.storage.StorageStrategies
+import java.io.File
+import java.text.SimpleDateFormat
+import java.util.*
+
+/**
+ * Manages storage operations for captured frames
+ *
+ * Coordinates frame storage across different Android versions and storage locations.
+ * Delegates actual storage operations to StorageStrategies for different scenarios:
+ * - Temporary storage (when saveFrames is false)
+ * - App-specific storage (default, no permissions needed)
+ * - Public storage via MediaStore (Android 10+)
+ * - Custom directory storage
+ *
+ * Also handles storage space monitoring and warning events.
+ */
+class StorageManager(
+    private val context: android.content.Context,
+    private val eventEmitter: ((String, com.facebook.react.bridge.WritableMap?) -> Unit)? = null
+) {
+
+    // Storage strategies handler
+    private val storageStrategies = StorageStrategies(context)
+
+    init {
+        // Clean up temp files from previous sessions on startup
+        cleanupAllTempFiles()
+    }
+
+    /**
+     * Returns the app-specific pictures directory
+     *
+     * This directory doesn't require storage permissions and is automatically
+     * cleaned when the app is uninstalled.
+     *
+     * @return File pointing to app-specific pictures directory
+     */
+    fun getAppSpecificDirectory(): File {
+        return storageStrategies.getAppSpecificDirectory()
+    }
+
+    /**
+     * Cleans up all temporary frame files
+     *
+     * Automatically called on app startup to remove temp files from previous sessions.
+     * Can also be called manually via cleanupTempFrames() API.
+     */
+    fun cleanupAllTempFiles() {
+        storageStrategies.cleanupAllTempFiles()
+    }
+
+    /**
+     * Generates a unique filename for a captured frame
+     *
+     * Format: <prefix><sessionId>_<frameNumber>_<timestamp>.<format>
+     * Example: capture_abc123_00042_20231215_143022_456.jpg
+     *
+     * @param sessionId Unique session identifier
+     * @param frameNumber Frame number (zero-padded based on config)
+     * @param format Image format ("png" or "jpg")
+     * @param fileNamingConfig File naming configuration
+     * @return Generated filename
+     */
+    fun generateFilename(
+        sessionId: String,
+        frameNumber: Int,
+        format: String,
+        fileNamingConfig: com.framecapture.models.FileNamingConfig = com.framecapture.models.FileNamingConfig()
+    ): String {
+        val timestamp = SimpleDateFormat(fileNamingConfig.dateFormat, Locale.US).format(Date())
+        val extension = when (format.lowercase()) {
+            Constants.FORMAT_EXTENSION_PNG -> Constants.FORMAT_EXTENSION_PNG
+            else -> Constants.FORMAT_EXTENSION_JPEG
+        }
+        val paddingFormat = "%0${fileNamingConfig.framePadding}d"
+        return "${fileNamingConfig.prefix}${sessionId}_${String.format(paddingFormat, frameNumber)}_${timestamp}.${extension}"
+    }
+
+
+
+    /**
+     * Saves a captured frame to storage
+     *
+     * Storage location is determined by options in this priority order:
+     * 1. Temporary storage (if saveFrames is false)
+     * 2. Custom directory (if outputDirectory is specified)
+     * 3. Public storage via MediaStore (if storageLocation is "public" and Android 10+)
+     * 4. App-specific directory (default)
+     *
+     * @param bitmap The captured frame as a Bitmap
+     * @param sessionId Unique session identifier
+     * @param frameNumber Frame number in the session
+     * @param options Capture options (format, quality, storage location)
+     * @return FrameInfo containing file path, size, and timestamp
+     * @throws IOException if the save operation fails
+     */
+    fun saveFrame(
+        bitmap: Bitmap,
+        sessionId: String,
+        frameNumber: Int,
+        options: CaptureOptions
+    ): FrameInfo {
+        val filename = generateFilename(sessionId, frameNumber, options.format, options.advanced.fileNaming)
+        val format = storageStrategies.getCompressFormat(options.format)
+        val quality = options.quality
+
+        // If saveFrames is false, save to temp directory
+        if (!options.saveFrames) {
+            return storageStrategies.saveToTempDirectory(bitmap, sessionId, filename, format, quality)
+        }
+
+        return when {
+            // 1. Custom directory takes precedence
+            options.outputDirectory != null -> {
+                storageStrategies.saveToCustomDirectory(bitmap, options.outputDirectory, filename, format, quality)
+            }
+
+            // 2. Public storage request
+            options.storageLocation == Constants.STORAGE_LOCATION_PUBLIC -> {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+                    // Android 10+: Use MediaStore for public Pictures folder
+                    storageStrategies.saveToMediaStore(bitmap, sessionId, filename, options.format, quality)
+                } else {
+                    // Android 9 and below: Fall back to app-specific storage
+                    storageStrategies.saveToAppSpecificDirectory(bitmap, sessionId, filename, format, quality)
+                }
+            }
+
+            // 3. Default: App-specific directory (no permissions needed)
+            else -> {
+                storageStrategies.saveToAppSpecificDirectory(bitmap, sessionId, filename, format, quality)
+            }
+        }
+    }
+
+    /**
+     * Checks available storage space in bytes
+     *
+     * Uses the app-specific directory to determine available space.
+     * Handles API level differences for StatFs methods.
+     *
+     * @return Available storage space in bytes, or 0 if check fails
+     */
+    fun checkStorageSpace(): Long {
+        return try {
+            val directory = getAppSpecificDirectory()
+            val stat = StatFs(directory.path)
+
+            // Use API level-appropriate method
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN_MR2) {
+                stat.availableBlocksLong * stat.blockSizeLong
+            } else {
+                @Suppress("DEPRECATION")
+                stat.availableBlocks.toLong() * stat.blockSize.toLong()
+            }
+        } catch (e: Exception) {
+            Log.e(Constants.MODULE_NAME, "Failed to check storage space: ${e.message}", e)
+            0L
+        }
+    }
+
+    /**
+     * Checks if sufficient storage is available
+     *
+     * Compares available space against the configured warning threshold.
+     * Emits a warning event to JavaScript if below threshold.
+     *
+     * @param threshold Storage warning threshold in bytes (0 to disable warnings)
+     * @return true if storage is sufficient, false if below threshold
+     */
+    fun isStorageAvailable(threshold: Long = Constants.DEFAULT_STORAGE_WARNING_THRESHOLD): Boolean {
+        // If threshold is 0, warnings are disabled
+        if (threshold == 0L) {
+            return true
+        }
+
+        val availableSpace = checkStorageSpace()
+        val isAvailable = availableSpace >= threshold
+
+        // Debug logging
+
+        // Emit warning if below threshold
+        if (!isAvailable && eventEmitter != null) {
+            emitStorageWarning(availableSpace, threshold)
+        } else if (!isAvailable) {
+            Log.w(Constants.MODULE_NAME, "Storage below threshold but eventEmitter is null!")
+        }
+
+        return isAvailable
+    }
+
+    /**
+     * Emits a storage warning event to JavaScript
+     *
+     * Sends available space and threshold values to allow the app to
+     * handle low storage situations (e.g., stop capture, notify user).
+     *
+     * @param availableSpace Current available storage in bytes
+     * @param threshold The configured warning threshold
+     */
+    private fun emitStorageWarning(availableSpace: Long, threshold: Long) {
+        try {
+            val params = com.facebook.react.bridge.Arguments.createMap().apply {
+                putDouble(Constants.EVENT_KEY_AVAILABLE_SPACE, availableSpace.toDouble())
+                putDouble(Constants.EVENT_KEY_THRESHOLD, threshold.toDouble())
+            }
+            eventEmitter?.invoke(Constants.EVENT_STORAGE_WARNING, params)
+        } catch (e: Exception) {
+            // Silently fail - event emission is not critical
+        }
+    }
+}