@capgo/capacitor-screen-recorder 8.3.17 → 8.4.0

package/README.md

@@ -1,11 +1,27 @@
 # Capacitor-screen-recorder
-<a href="https://capgo.app/"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-screen-recorder" alt="Capgo - Instant updates for Capacitor" /></a>
+
+Record the device screen from your Capacitor app, with optional audio, for bug reports, tutorials and demos.
+
+<a href="https://capgo.app/?ref=plugin_screen_recorder"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-screen-recorder" alt="Capgo - Instant updates for Capacitor" /></a>
 
 <div align="center">
-  <h2><a href="https://capgo.app/?ref=plugin_screen_recorder"> ➡️ Get Instant updates for your App with Capgo</a></h2>
-  <h2><a href="https://capgo.app/consulting/?ref=plugin_screen_recorder"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
+  <p><b>Capgo</b>: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.</p>
+  <h2><a href="https://capgo.app/register/?ref=plugin_screen_recorder">➡️ Get started for free</a></h2>
+  <p>14-day unlimited free trial. No credit card required</p>
+  <p><a href="https://capgo.app/consulting/?ref=plugin_screen_recorder">Missing a feature? We'll build the plugin for you 💪</a></p>
 </div>
-Record device's screen
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Cap-go/capacitor-screen-recorder/main/assets/github-social-preview.png" alt="@capgo/capacitor-screen-recorder for Capacitor apps" width="300" />
+</p>
+
+## Key features
+
+- **Start**: `start()` begins recording after the system consent prompt.
+- **Stop**: `stop()` ends the recording.
+- **Audio**: set `recordAudio` to capture sound with the video.
+- **Native capture**: ReplayKit on iOS, saved to the Photos library, and MediaProjection on Android.
+- **Platforms**: iOS and Android. Not available on web.
 
 ## Documentation
 
@@ -103,6 +119,8 @@ No configuration required for this plugin.
 
 * [`start(...)`](#start)
 * [`stop()`](#stop)
+* [`addListener('onStopped', ...)`](#addlisteneronstopped-)
+* [`removeAllListeners()`](#removealllisteners)
 * [`getPluginVersion()`](#getpluginversion)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
@@ -154,6 +172,39 @@ recording. On Android, the video is saved directly to the gallery.
 --------------------
 
 
+### addListener('onStopped', ...)
+
+```typescript
+addListener(eventName: 'onStopped', listenerFunc: (event: ScreenRecorderStoppedEvent) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for recordings that ended without {@link stop} being called.
+
+| Param              | Type                                                                                                  | Description                                                                                                          |
+| ------------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'onStopped'</code>                                                                              | - `onStopped`                                                                                                        |
+| **`listenerFunc`** | <code>(event: <a href="#screenrecorderstoppedevent">ScreenRecorderStoppedEvent</a>) =&gt; void</code> | - Called with a `ScreenRecorderStoppedEvent` (`url` and optional `error`) when the recording ended outside `stop()`. |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.4.0
+
+--------------------
+
+
+### removeAllListeners()
+
+```typescript
+removeAllListeners() => Promise<void>
+```
+
+Remove all listeners registered with {@link addListener}.
+
+**Since:** 8.4.0
+
+--------------------
+
+
 ### getPluginVersion()
 
 ```typescript
@@ -182,6 +233,28 @@ Options for {@link ScreenRecorderPlugin.start}.
 | **`format`**      | <code><a href="#screenrecordervideoformat">ScreenRecorderVideoFormat</a> \| 'video/mp4' \| 'video/quicktime'</code> | Video container format for the saved recording. Accepts `mp4`, `mov`, or MIME types `video/mp4` and `video/quicktime`. iOS supports both `mp4` and `mov`. Android records MPEG-4 (`.mp4`) regardless of this value. | <code>'mp4'</code> | 8.3.0 |
 
 
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### ScreenRecorderStoppedEvent
+
+Payload for the `onStopped` event.
+
+Fired when a recording ends without {@link ScreenRecorderPlugin.stop} being
+called: the user stopped capture from the system UI (Android "Stop sharing"),
+the recorder hit a limit (max duration or max file size), or the system
+interrupted capture (iOS, for example an incoming call).
+
+| Prop        | Type                | Description                                                                                                        | Since |
+| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`url`**   | <code>string</code> | Local URI of the finished recording (`file://` on Android). Empty string when the file path could not be resolved. | 8.4.0 |
+| **`error`** | <code>string</code> | Error message when the recording ended with a failure.                                                             | 8.4.0 |
+
+
 ### Type Aliases
 
 

package/android/src/main/java/ee/forgr/plugin/screenrecorder/CapgoScrCast.kt

@@ -38,6 +38,13 @@ class CapgoScrCast private constructor(
     private var serviceBinder: CapgoRecorderService? = null
     private var outputFile: File? = null
     private var startListener: StartListener? = null
+    private var stopRequested = false
+    private var sessionGeneration = 0L
+
+    /**
+     * Invoked when a recording ends without {@link #stopRecording()} having been called.
+     */
+    var externalStopListener: ExternalStopListener? = null
     private var receiverRegistered = false
 
     private val metrics by lazy {
@@ -68,11 +75,30 @@ class CapgoScrCast private constructor(
         override fun onReceive(context: Context?, intent: Intent?) {
             when (intent?.action) {
                 STATE_RECORDING -> {
+                    val broadcastGeneration =
+                        intent?.getLongExtra(EXTRA_SESSION_GENERATION, -1L) ?: -1L
+                    if (broadcastGeneration != sessionGeneration) {
+                        return
+                    }
+                    if (stopRequested) {
+                        startListener?.onFailed(
+                            IllegalStateException("Recording stopped before it started"),
+                        )
+                        startListener = null
+                        broadcaster.sendBroadcast(Intent(Action.Stop.name))
+                        return
+                    }
                     startListener?.onStarted()
                     startListener = null
                 }
                 STATE_IDLE -> {
+                    val broadcastGeneration =
+                        intent?.getLongExtra(EXTRA_SESSION_GENERATION, -1L) ?: -1L
+                    if (broadcastGeneration != sessionGeneration) {
+                        return
+                    }
                     val startPending = startListener != null
+                    val sessionActive = recordingSession != null
                     val error = intent.getSerializableExtra(EXTRA_ERROR) as? Throwable
                     if (error != null) {
                         startListener?.onFailed(error)
@@ -81,7 +107,11 @@ class CapgoScrCast private constructor(
                             IllegalStateException("Recording stopped before it started"),
                         )
                     }
-                    cleanupSession(deleteEmptyOutput = startPending || error != null)
+                    val savedPath = cleanupSession(deleteEmptyOutput = startPending || error != null)
+                    if (!startPending && sessionActive && !stopRequested) {
+                        externalStopListener?.onExternalStop(savedPath, error?.message)
+                    }
+                    stopRequested = false
                 }
             }
         }
@@ -90,6 +120,10 @@ class CapgoScrCast private constructor(
     private val requestRuntimePermissions = activity.registerForActivityResult(
         ActivityResultContracts.RequestMultiplePermissions(),
     ) { _ ->
+        if (startListener == null || stopRequested) {
+            abandonCanceledPendingStart()
+            return@registerForActivityResult
+        }
         if (requiredRuntimePermissions().all { isPermissionGranted(it) }) {
             startProjection.launch(Unit)
         } else {
@@ -98,6 +132,10 @@ class CapgoScrCast private constructor(
     }
 
     private val startProjection = activity.registerForActivityResult(CapgoRecordScreen()) { result ->
+        if (startListener == null || stopRequested) {
+            abandonCanceledPendingStart()
+            return@registerForActivityResult
+        }
         if (result.resultCode != Activity.RESULT_OK) {
             notifyStartFailed(IllegalStateException("Screen capture permission denied"))
             return@registerForActivityResult
@@ -155,9 +193,23 @@ class CapgoScrCast private constructor(
     }
 
     fun stopRecording() {
+        stopRequested = true
+        if (recordingSession == null && startListener != null) {
+            abandonCanceledPendingStart()
+            return
+        }
         broadcaster.sendBroadcast(Intent(Action.Stop.name))
     }
 
+    private fun abandonCanceledPendingStart() {
+        if (startListener == null) {
+            stopRequested = false
+            return
+        }
+        notifyStartFailed(IllegalStateException("Recording stopped before it started"))
+        stopRequested = false
+    }
+
     private fun resolveVideoSize(options: Options): Options {
         return VideoSizeResolver.applyTo(options, metrics.widthPixels, metrics.heightPixels)
     }
@@ -168,6 +220,11 @@ class CapgoScrCast private constructor(
     }
 
     private fun startService(result: ActivityResult, file: File) {
+        if (startListener == null || stopRequested) {
+            abandonCanceledPendingStart()
+            return
+        }
+        sessionGeneration += 1
         outputFile = file
         val session = Intent(activity, CapgoRecorderService::class.java).apply {
             putExtra("code", result.resultCode)
@@ -177,6 +234,7 @@ class CapgoScrCast private constructor(
             putExtra("dpi", dpi)
             putExtra("rotation", activity.windowManager.defaultDisplay.rotation)
             putExtra("recordAudio", recordAudio)
+            putExtra(EXTRA_SESSION_GENERATION, sessionGeneration)
         }
         recordingSession = session
 
@@ -201,6 +259,7 @@ class CapgoScrCast private constructor(
         unregisterRecordingReceiver()
         recordingSession = null
         outputFile = null
+        stopRequested = false
         notifyStartFailed(error)
     }
 
@@ -216,7 +275,7 @@ class CapgoScrCast private constructor(
         receiverRegistered = false
     }
 
-    private fun cleanupSession(deleteEmptyOutput: Boolean = false) {
+    private fun cleanupSession(deleteEmptyOutput: Boolean = false): String? {
         startListener = null
         unregisterRecordingReceiver()
 
@@ -229,17 +288,24 @@ class CapgoScrCast private constructor(
         recordingSession?.let { activity.stopService(it) }
         recordingSession = null
 
-        outputFile?.let { file ->
+        val savedPath = outputFile?.absolutePath
+        val deliverablePath = savedPath?.let { path ->
+            val file = File(path)
             if (file.isFile && file.length() > 0L) {
-                MediaScannerConnection.scanFile(activity, arrayOf(file.absolutePath), null) { path, uri ->
-                    Log.i("CapgoScreenRecorder", "Saved recording: $path uri=$uri")
+                MediaScannerConnection.scanFile(activity, arrayOf(path), null) { scanPath, uri ->
+                    Log.i("CapgoScreenRecorder", "Saved recording: $scanPath uri=$uri")
+                }
+                path
+            } else {
+                if (deleteEmptyOutput && file.exists()) {
+                    runCatching { file.delete() }
                 }
-            } else if (deleteEmptyOutput && file.exists()) {
-                runCatching { file.delete() }
+                null
             }
         }
         outputFile = null
         CapgoRecordingCoordinator.release()
+        return deliverablePath
     }
 
     interface StartListener {
@@ -247,7 +313,13 @@ class CapgoScrCast private constructor(
         fun onFailed(error: Throwable)
     }
 
+    fun interface ExternalStopListener {
+        fun onExternalStop(path: String?, error: String?)
+    }
+
     companion object {
+        const val EXTRA_SESSION_GENERATION = "capgoSessionGeneration"
+
         @JvmStatic
         fun use(activity: ComponentActivity, recordAudio: Boolean): CapgoScrCast {
             return CapgoScrCast(activity, recordAudio)

package/android/src/main/java/ee/forgr/plugin/screenrecorder/ScreenRecorderPlugin.java

@@ -1,20 +1,23 @@
 package ee.forgr.plugin.screenrecorder;
 
+import android.net.Uri;
 import com.getcapacitor.JSObject;
 import com.getcapacitor.Plugin;
 import com.getcapacitor.PluginCall;
 import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 import dev.bmcreations.scrcast.config.Options;
+import java.io.File;
 
 @CapacitorPlugin(name = "ScreenRecorder")
 public class ScreenRecorderPlugin extends Plugin {
 
-    private final String pluginVersion = "8.3.17";
+    private final String pluginVersion = "8.4.0";
 
     private CapgoScrCast videoRecorder;
     private CapgoScrCast audioRecorder;
-    private boolean recordingWithAudio = false;
+    private CapgoScrCast pendingRecorder = null;
+    private CapgoScrCast activeRecorder = null;
 
     @Override
     public void load() {
@@ -23,17 +26,35 @@ public class ScreenRecorderPlugin extends Plugin {
         final Options options = new Options();
         videoRecorder.updateOptions(options);
         audioRecorder.updateOptions(options);
+
+        final CapgoScrCast.ExternalStopListener externalStopListener = new CapgoScrCast.ExternalStopListener() {
+            @Override
+            public void onExternalStop(final String path, final String error) {
+                if (activeRecorder == null) {
+                    return;
+                }
+                activeRecorder = null;
+                final JSObject ret = new JSObject();
+                ret.put("url", path != null ? Uri.fromFile(new File(path)).toString() : "");
+                if (error != null) {
+                    ret.put("error", error);
+                }
+                notifyListeners("onStopped", ret);
+            }
+        };
+        videoRecorder.setExternalStopListener(externalStopListener);
+        audioRecorder.setExternalStopListener(externalStopListener);
     }
 
     @PluginMethod
     public void start(final PluginCall call) {
         boolean keptAlive = false;
+        CapgoScrCast startRecorder = null;
         try {
             final boolean recordAudio = call.getBoolean("recordAudio", false);
             final String format = call.getString("format");
-            recordingWithAudio = recordAudio;
-
-            final CapgoScrCast recorder = recordAudio ? audioRecorder : videoRecorder;
+            startRecorder = recordAudio ? audioRecorder : videoRecorder;
+            final CapgoScrCast recorder = startRecorder;
             final Options configuredOptions = VideoFormatResolver.INSTANCE.applyTo(recorder.getOptions(), format);
             recorder.updateOptions(configuredOptions);
             recorder.updateVideoFormat(format);
@@ -44,13 +65,22 @@ public class ScreenRecorderPlugin extends Plugin {
                 new CapgoScrCast.StartListener() {
                     @Override
                     public void onStarted() {
+                        if (pendingRecorder == recorder) {
+                            pendingRecorder = null;
+                        }
+                        activeRecorder = recorder;
                         call.resolve();
                         call.release(bridge);
                     }
 
                     @Override
                     public void onFailed(final Throwable error) {
-                        recordingWithAudio = false;
+                        if (pendingRecorder == recorder) {
+                            pendingRecorder = null;
+                        }
+                        if (activeRecorder == recorder) {
+                            activeRecorder = null;
+                        }
                         final Exception exception = error instanceof Exception ? (Exception) error : new Exception(error);
                         call.reject("Could not start screen recording", exception);
                         call.release(bridge);
@@ -58,12 +88,15 @@ public class ScreenRecorderPlugin extends Plugin {
                 }
             );
             if (!started) {
-                recordingWithAudio = false;
                 call.reject("Could not start screen recording", new IllegalStateException("A screen recording is already in progress"));
                 call.release(bridge);
+            } else {
+                pendingRecorder = recorder;
             }
         } catch (final Exception e) {
-            recordingWithAudio = false;
+            if (startRecorder != null && pendingRecorder == startRecorder) {
+                pendingRecorder = null;
+            }
             call.reject("Could not start screen recording", e);
             if (keptAlive) {
                 call.release(bridge);
@@ -74,12 +107,12 @@ public class ScreenRecorderPlugin extends Plugin {
     @PluginMethod
     public void stop(PluginCall call) {
         try {
-            if (recordingWithAudio) {
-                audioRecorder.stopRecording();
-            } else {
-                videoRecorder.stopRecording();
+            final CapgoScrCast recorder = activeRecorder != null ? activeRecorder : pendingRecorder;
+            if (recorder != null) {
+                recorder.stopRecording();
             }
-            recordingWithAudio = false;
+            pendingRecorder = null;
+            activeRecorder = null;
             call.resolve();
         } catch (final Exception e) {
             call.reject("Could not stop screen recording", e);

package/android/src/main/java/ee/forgr/plugin/screenrecorder/service/CapgoRecorderService.kt

@@ -23,6 +23,7 @@ import dev.bmcreations.scrcast.internal.recorder.*
 import dev.bmcreations.scrcast.internal.recorder.service.orientations
 import dev.bmcreations.scrcast.recorder.*
 import dev.bmcreations.scrcast.recorder.notification.NotificationProvider
+import ee.forgr.plugin.screenrecorder.CapgoScrCast
 import ee.forgr.plugin.screenrecorder.MediaRecorderPrepare
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.GlobalScope
@@ -66,10 +67,13 @@ class CapgoRecorderService : Service() {
         }
     }
 
+    private var sessionGeneration: Long = 0L
+
     private var state: RecordingState = RecordingState.Idle()
         set(value) {
             field = value
             broadcaster.sendBroadcast(Intent(value.stateString()).apply {
+                putExtra(CapgoScrCast.EXTRA_SESSION_GENERATION, sessionGeneration)
                 if (value is RecordingState.Delay) {
                     putExtra(EXTRA_DELAY_REMAINING, value.remainingSeconds)
                 } else if (value is RecordingState.Idle) {
@@ -112,7 +116,8 @@ class CapgoRecorderService : Service() {
         }
 
     private var mediaRecorder: MediaRecorder? = null
-
+    private var recordingStarted = false
+    private var prepareInProgress = false
 
     private fun createMediaRecorder(): MediaRecorder {
         return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
@@ -238,6 +243,7 @@ class CapgoRecorderService : Service() {
 
     private fun recordInternal(code: Int, data: Intent) {
         GlobalScope.launch(Dispatchers.Main) {
+            prepareInProgress = true
             startForeground(
                 notificationProvider.getNotificationId(),
                 notificationProvider.get(state)
@@ -259,44 +265,73 @@ class CapgoRecorderService : Service() {
 
             mediaProjection?.registerCallback(mediaProjectionCallback, Handler())
             if (!createRecorder()) {
+                prepareInProgress = false
                 stopRecording(IOException("MediaRecorder prepare failed"))
                 return@launch
             }
             virtualDisplay // touch
             try {
                 mediaRecorder?.start()
+                recordingStarted = true
                 state = RecordingState.Recording
                 notificationProvider.update(state)
             } catch (e: Exception) {
                 stopRecording(e)
+            } finally {
+                prepareInProgress = false
             }
         }
     }
 
     private fun stopRecording(error: Throwable? = null) {
+        finalizeRecorder()
         mediaProjection?.stop()
-
+        mediaProjection = null
         state = RecordingState.Idle(error)
         stopForeground(true)
     }
 
-    private fun cleanupProjection() {
+    private fun finalizeRecorder() {
         mediaProjection?.unregisterCallback(mediaProjectionCallback)
-        mediaProjection = null
-
         _virtualDisplay?.release()
         _virtualDisplay = null
-
         runCatching {
             mediaRecorder?.stop()
         }
         releaseRecorder()
+        recordingStarted = false
+        prepareInProgress = false
+    }
+
+    private fun cleanupProjection() {
+        finalizeRecorder()
+        mediaProjection = null
     }
 
     private inner class MediaProjectionCallback : MediaProjection.Callback() {
         override fun onStop() {
             Log.d("scrcast", "projection on stop")
+            val hadStarted = recordingStarted
+            val preparing = prepareInProgress
             cleanupProjection()
+            when {
+                state is RecordingState.Idle && (state as RecordingState.Idle).error != null -> {
+                    // stopRecording() already published Idle with an error.
+                }
+                state is RecordingState.Idle && hadStarted -> {
+                    // stopRecording() already published Idle for an active recording.
+                }
+                !hadStarted || preparing -> {
+                    state = RecordingState.Idle(
+                        IllegalStateException("Recording stopped before it started"),
+                    )
+                    stopForeground(true)
+                }
+                else -> {
+                    state = RecordingState.Idle()
+                    stopForeground(true)
+                }
+            }
         }
     }
 
@@ -307,6 +342,7 @@ class CapgoRecorderService : Service() {
             dpi = it.getFloatExtra("dpi", 0f)
             outputFile = it.getStringExtra("outputFile") ?: ""
             recordAudio = it.getBooleanExtra("recordAudio", false)
+            sessionGeneration = it.getLongExtra(CapgoScrCast.EXTRA_SESSION_GENERATION, 0L)
 
             startRecording(
                 code = it.getIntExtra("code", -1),

package/dist/docs.json

@@ -84,6 +84,58 @@
         "complexTypes": [],
         "slug": "stop"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'onStopped', listenerFunc: (event: ScreenRecorderStoppedEvent) => void) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "- `onStopped`",
+            "type": "'onStopped'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "- Called with a `ScreenRecorderStoppedEvent`\n(`url` and optional `error`) when the recording ended outside `stop()`.",
+            "type": "(event: ScreenRecorderStoppedEvent) => void"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "eventName - `onStopped`"
+          },
+          {
+            "name": "param",
+            "text": "listenerFunc - Called with a `ScreenRecorderStoppedEvent`\n(`url` and optional `error`) when the recording ended outside `stop()`."
+          },
+          {
+            "name": "since",
+            "text": "8.4.0"
+          }
+        ],
+        "docs": "Listen for recordings that ended without {@link stop} being called.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "ScreenRecorderStoppedEvent"
+        ],
+        "slug": "addlisteneronstopped-"
+      },
+      {
+        "name": "removeAllListeners",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.4.0"
+          }
+        ],
+        "docs": "Remove all listeners registered with {@link addListener}.",
+        "complexTypes": [],
+        "slug": "removealllisteners"
+      },
       {
         "name": "getPluginVersion",
         "signature": "() => Promise<{ version: string; }>",
@@ -166,6 +218,60 @@
           "type": "ScreenRecorderVideoFormat | 'video/mp4' | 'video/quicktime' | undefined"
         }
       ]
+    },
+    {
+      "name": "PluginListenerHandle",
+      "slug": "pluginlistenerhandle",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "remove",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "() => Promise<void>"
+        }
+      ]
+    },
+    {
+      "name": "ScreenRecorderStoppedEvent",
+      "slug": "screenrecorderstoppedevent",
+      "docs": "Payload for the `onStopped` event.\n\nFired when a recording ends without {@link ScreenRecorderPlugin.stop} being\ncalled: the user stopped capture from the system UI (Android \"Stop sharing\"),\nthe recorder hit a limit (max duration or max file size), or the system\ninterrupted capture (iOS, for example an incoming call).",
+      "tags": [
+        {
+          "text": "8.4.0",
+          "name": "since"
+        }
+      ],
+      "methods": [],
+      "properties": [
+        {
+          "name": "url",
+          "tags": [
+            {
+              "text": "8.4.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Local URI of the finished recording (`file://` on Android).\nEmpty string when the file path could not be resolved.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "error",
+          "tags": [
+            {
+              "text": "8.4.0",
+              "name": "since"
+            }
+          ],
+          "docs": "Error message when the recording ended with a failure.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
     }
   ],
   "enums": [],

package/dist/esm/definitions.d.ts

@@ -1,3 +1,29 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+/**
+ * Payload for the `onStopped` event.
+ *
+ * Fired when a recording ends without {@link ScreenRecorderPlugin.stop} being
+ * called: the user stopped capture from the system UI (Android "Stop sharing"),
+ * the recorder hit a limit (max duration or max file size), or the system
+ * interrupted capture (iOS, for example an incoming call).
+ *
+ * @since 8.4.0
+ */
+export interface ScreenRecorderStoppedEvent {
+    /**
+     * Local URI of the finished recording (`file://` on Android).
+     * Empty string when the file path could not be resolved.
+     *
+     * @since 8.4.0
+     */
+    url: string;
+    /**
+     * Error message when the recording ended with a failure.
+     *
+     * @since 8.4.0
+     */
+    error?: string;
+}
 /**
  * Supported video container formats for screen recordings.
  *
@@ -80,6 +106,21 @@ export interface ScreenRecorderPlugin {
      * ```
      */
     stop(): Promise<void>;
+    /**
+     * Listen for recordings that ended without {@link stop} being called.
+     *
+     * @param eventName - `onStopped`
+     * @param listenerFunc - Called with a `ScreenRecorderStoppedEvent`
+     * (`url` and optional `error`) when the recording ended outside `stop()`.
+     * @since 8.4.0
+     */
+    addListener(eventName: 'onStopped', listenerFunc: (event: ScreenRecorderStoppedEvent) => void): Promise<PluginListenerHandle>;
+    /**
+     * Remove all listeners registered with {@link addListener}.
+     *
+     * @since 8.4.0
+     */
+    removeAllListeners(): Promise<void>;
     /**
      * Get the native Capacitor plugin version.
      *

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Supported video container formats for screen recordings.\n *\n * @since 8.3.0\n */\nexport type ScreenRecorderVideoFormat = 'mp4' | 'mov';\n\n/**\n * Options for {@link ScreenRecorderPlugin.start}.\n *\n * @since 8.3.0\n */\nexport interface StartRecordingOptions {\n  /**\n   * Whether to record audio along with the screen video.\n   *\n   * @default false\n   * @since 1.0.0\n   */\n  recordAudio?: boolean;\n\n  /**\n   * Video container format for the saved recording.\n   *\n   * Accepts `mp4`, `mov`, or MIME types `video/mp4` and `video/quicktime`.\n   * iOS supports both `mp4` and `mov`. Android records MPEG-4 (`.mp4`) regardless of this value.\n   *\n   * @default 'mp4'\n   * @since 8.3.0\n   * @example 'mov'\n   */\n  format?: ScreenRecorderVideoFormat | 'video/mp4' | 'video/quicktime';\n}\n\n/**\n * Capacitor Screen Recorder Plugin for recording the device screen.\n * Allows you to capture video recordings of the screen with optional audio.\n *\n * @since 1.0.0\n */\nexport interface ScreenRecorderPlugin {\n  /**\n   * Start recording the device screen.\n   *\n   * Initiates screen recording with optional audio capture. The user will be\n   * prompted to grant screen recording permissions if not already granted.\n   * On iOS, the system recording UI will be displayed. On Android, the recording\n   * starts immediately after permission is granted.\n   *\n   * @param options - Recording configuration options\n   * @param options.recordAudio - Whether to record audio along with the screen video. Defaults to false.\n   * @param options.format - Video container format for the saved recording. Defaults to `mp4`.\n   * @returns Promise that resolves when recording starts\n   * @throws Error if recording fails to start or permissions are denied\n   * @since 1.0.0\n   * @example\n   * ```typescript\n   * // Start recording without audio\n   * await ScreenRecorder.start();\n   *\n   * // Start recording with audio\n   * await ScreenRecorder.start({ recordAudio: true });\n   *\n   * // Start recording as MOV on iOS\n   * await ScreenRecorder.start({ format: 'mov' });\n   * ```\n   */\n  start(options?: StartRecordingOptions): Promise<void>;\n\n  /**\n   * Stop the current screen recording.\n   *\n   * Stops the active screen recording and saves the video to the device's\n   * camera roll or gallery. On iOS, the system will show a preview of the\n   * recording. On Android, the video is saved directly to the gallery.\n   *\n   * @returns Promise that resolves when recording stops and the video is saved\n   * @throws Error if stopping the recording fails or no recording is active\n   * @since 1.0.0\n   * @example\n   * ```typescript\n   * await ScreenRecorder.stop();\n   * console.log('Recording saved to gallery');\n   * ```\n   */\n  stop(): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version.\n   *\n   * @returns Promise that resolves with the plugin version\n   * @throws Error if getting the version fails\n   * @since 1.0.0\n   * @example\n   * ```typescript\n   * const { version } = await ScreenRecorder.getPluginVersion();\n   * console.log('Plugin version:', version);\n   * ```\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * Payload for the `onStopped` event.\n *\n * Fired when a recording ends without {@link ScreenRecorderPlugin.stop} being\n * called: the user stopped capture from the system UI (Android \"Stop sharing\"),\n * the recorder hit a limit (max duration or max file size), or the system\n * interrupted capture (iOS, for example an incoming call).\n *\n * @since 8.4.0\n */\nexport interface ScreenRecorderStoppedEvent {\n  /**\n   * Local URI of the finished recording (`file://` on Android).\n   * Empty string when the file path could not be resolved.\n   *\n   * @since 8.4.0\n   */\n  url: string;\n\n  /**\n   * Error message when the recording ended with a failure.\n   *\n   * @since 8.4.0\n   */\n  error?: string;\n}\n\n/**\n * Supported video container formats for screen recordings.\n *\n * @since 8.3.0\n */\nexport type ScreenRecorderVideoFormat = 'mp4' | 'mov';\n\n/**\n * Options for {@link ScreenRecorderPlugin.start}.\n *\n * @since 8.3.0\n */\nexport interface StartRecordingOptions {\n  /**\n   * Whether to record audio along with the screen video.\n   *\n   * @default false\n   * @since 1.0.0\n   */\n  recordAudio?: boolean;\n\n  /**\n   * Video container format for the saved recording.\n   *\n   * Accepts `mp4`, `mov`, or MIME types `video/mp4` and `video/quicktime`.\n   * iOS supports both `mp4` and `mov`. Android records MPEG-4 (`.mp4`) regardless of this value.\n   *\n   * @default 'mp4'\n   * @since 8.3.0\n   * @example 'mov'\n   */\n  format?: ScreenRecorderVideoFormat | 'video/mp4' | 'video/quicktime';\n}\n\n/**\n * Capacitor Screen Recorder Plugin for recording the device screen.\n * Allows you to capture video recordings of the screen with optional audio.\n *\n * @since 1.0.0\n */\nexport interface ScreenRecorderPlugin {\n  /**\n   * Start recording the device screen.\n   *\n   * Initiates screen recording with optional audio capture. The user will be\n   * prompted to grant screen recording permissions if not already granted.\n   * On iOS, the system recording UI will be displayed. On Android, the recording\n   * starts immediately after permission is granted.\n   *\n   * @param options - Recording configuration options\n   * @param options.recordAudio - Whether to record audio along with the screen video. Defaults to false.\n   * @param options.format - Video container format for the saved recording. Defaults to `mp4`.\n   * @returns Promise that resolves when recording starts\n   * @throws Error if recording fails to start or permissions are denied\n   * @since 1.0.0\n   * @example\n   * ```typescript\n   * // Start recording without audio\n   * await ScreenRecorder.start();\n   *\n   * // Start recording with audio\n   * await ScreenRecorder.start({ recordAudio: true });\n   *\n   * // Start recording as MOV on iOS\n   * await ScreenRecorder.start({ format: 'mov' });\n   * ```\n   */\n  start(options?: StartRecordingOptions): Promise<void>;\n\n  /**\n   * Stop the current screen recording.\n   *\n   * Stops the active screen recording and saves the video to the device's\n   * camera roll or gallery. On iOS, the system will show a preview of the\n   * recording. On Android, the video is saved directly to the gallery.\n   *\n   * @returns Promise that resolves when recording stops and the video is saved\n   * @throws Error if stopping the recording fails or no recording is active\n   * @since 1.0.0\n   * @example\n   * ```typescript\n   * await ScreenRecorder.stop();\n   * console.log('Recording saved to gallery');\n   * ```\n   */\n  stop(): Promise<void>;\n\n  /**\n   * Listen for recordings that ended without {@link stop} being called.\n   *\n   * @param eventName - `onStopped`\n   * @param listenerFunc - Called with a `ScreenRecorderStoppedEvent`\n   * (`url` and optional `error`) when the recording ended outside `stop()`.\n   * @since 8.4.0\n   */\n  addListener(\n    eventName: 'onStopped',\n    listenerFunc: (event: ScreenRecorderStoppedEvent) => void,\n  ): Promise<PluginListenerHandle>;\n\n  /**\n   * Remove all listeners registered with {@link addListener}.\n   *\n   * @since 8.4.0\n   */\n  removeAllListeners(): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version.\n   *\n   * @returns Promise that resolves with the plugin version\n   * @throws Error if getting the version fails\n   * @since 1.0.0\n   * @example\n   * ```typescript\n   * const { version } = await ScreenRecorder.getPluginVersion();\n   * console.log('Plugin version:', version);\n   * ```\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n}\n"]}

package/ios/Sources/ScreenRecorderPlugin/ScreenRecorderPlugin.swift

@@ -7,7 +7,7 @@ import Capacitor
  */
 @objc(ScreenRecorderPlugin)
 public class ScreenRecorderPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.3.17"
+    private let pluginVersion: String = "8.4.0"
     public let identifier = "ScreenRecorderPlugin"
     public let jsName = "ScreenRecorder"
     public let pluginMethods: [CAPPluginMethod] = [
@@ -17,6 +17,17 @@ public class ScreenRecorderPlugin: CAPPlugin, CAPBridgedPlugin {
     ]
     private let implementation = ScreenRecorder()
 
+    override public func load() {
+        implementation.onExternalStop = { [weak self] url, error in
+            guard let self = self else { return }
+            var data: [String: Any] = ["url": url?.absoluteString ?? ""]
+            if let error = error {
+                data["error"] = error.localizedDescription
+            }
+            self.notifyListeners("onStopped", data: data)
+        }
+    }
+
     @objc func start(_ call: CAPPluginCall) {
         let recordAudio = call.getBool("recordAudio") ?? false
         let videoFormat = VideoContainerFormat.from(call.getString("format"))

package/ios/Sources/ScreenRecorderPlugin/Wyler.swift

@@ -50,7 +50,7 @@ public enum VideoContainerFormat {
     }
 }
 
-public final class ScreenRecorder {
+public final class ScreenRecorder: NSObject, RPScreenRecorderDelegate {
     private var videoOutputURL: URL?
     private var didCreateOutputFile = false
     private var videoWriter: AVAssetWriter?
@@ -62,6 +62,14 @@ public final class ScreenRecorder {
     private var recordAudio = false
     private var videoFormat: VideoContainerFormat = .mp4
     private var isRecording = false
+    private var stopRequested = false
+    private var startSettled = false
+    private var videoHasContent = false
+    private var isFinalizingExternally = false
+    private var pendingStartHandler: ((Error?) -> Void)?
+    private let stateLock = NSLock()
+    /// Fired when recording ends without `stoprecording()` being called.
+    public var onExternalStop: ((URL?, Error?) -> Void)?
     let recorder = RPScreenRecorder.shared()
 
     public func startRecording(to outputURL: URL? = nil,
@@ -70,10 +78,16 @@ public final class ScreenRecorder {
                                recordAudio: Bool = false,
                                videoFormat: VideoContainerFormat = .mp4,
                                handler: @escaping (Error?) -> Void) {
-        guard !isRecording else {
+        guard !isRecording, !isFinalizingExternally else {
             return handler(ScreenRecorderError.alreadyRecording)
         }
         isRecording = true
+        pendingStartHandler = nil
+        stopRequested = false
+        startSettled = false
+        videoHasContent = false
+        isFinalizingExternally = false
+        recorder.delegate = self
 
         self.saveToCameraRoll = saveToCameraRoll
         self.recordAudio = recordAudio
@@ -180,19 +194,15 @@ public final class ScreenRecorder {
             self.isRecording = false
             return handler(ScreenRecorderError.notAvailable)
         }
+        pendingStartHandler = handler
         var sent = false
         recorder.startCapture(handler: { (sampleBuffer, sampleType, passedError) in
             if let passedError = passedError {
-                self.videoWriterInput?.markAsFinished()
-                self.audioWriterInput?.markAsFinished()
-                if self.videoWriter?.status == .writing {
-                    self.videoWriter?.cancelWriting()
-                }
-                self.deleteOutputFileIfNeeded(outputURL: outputURL, didCreate: didCreate)
                 if !sent {
-                    self.isRecording = false
-                    handler(passedError)
+                    self.failPendingStart(passedError, outputURL: outputURL, didCreate: didCreate)
                     sent = true
+                } else if self.isRecording && !self.stopRequested && !self.isFinalizingExternally {
+                    self.handleRecordingEndedExternally(error: passedError)
                 }
                 return
             }
@@ -220,12 +230,35 @@ public final class ScreenRecorder {
                 break
             }
             if !sent {
-                handler(nil)
+                self.completePendingStart(nil)
                 sent = true
             }
         })
     }
 
+    private func completePendingStart(_ error: Error?) {
+        stateLock.lock()
+        let startHandler = pendingStartHandler
+        pendingStartHandler = nil
+        startSettled = true
+        if error != nil {
+            isRecording = false
+        }
+        stateLock.unlock()
+        startHandler?(error)
+    }
+
+    private func failPendingStart(_ error: Error, outputURL: URL?, didCreate: Bool) {
+        recorder.delegate = nil
+        videoWriterInput?.markAsFinished()
+        audioWriterInput?.markAsFinished()
+        if videoWriter?.status == .writing {
+            videoWriter?.cancelWriting()
+        }
+        deleteOutputFileIfNeeded(outputURL: outputURL, didCreate: didCreate)
+        completePendingStart(error)
+    }
+
     private func handleSampleBuffer(sampleBuffer: CMSampleBuffer) {
         if self.videoWriter?.status == AVAssetWriter.Status.unknown {
             self.videoWriter?.startWriting()
@@ -233,6 +266,7 @@ public final class ScreenRecorder {
         } else if self.videoWriter?.status == AVAssetWriter.Status.writing &&
                     self.videoWriterInput?.isReadyForMoreMediaData == true {
             self.videoWriterInput?.append(sampleBuffer)
+            self.videoHasContent = true
         }
     }
 
@@ -245,6 +279,12 @@ public final class ScreenRecorder {
     }
 
     public func stoprecording(handler: @escaping (Error?) -> Void) {
+        if isFinalizingExternally || !isRecording {
+            handler(nil)
+            return
+        }
+        stopRequested = true
+        recorder.delegate = nil
         recorder.stopCapture(handler: { error in
             let outputURL = self.videoOutputURL
             let didCreate = self.didCreateOutputFile
@@ -381,4 +421,112 @@ public final class ScreenRecorder {
             debugPrint("Failed to delete recording file \(fileURL): \(error)")
         }
     }
+
+    private func handleRecordingEndedExternally(error: Error?) {
+        stateLock.lock()
+        let shouldHandle = isRecording && !stopRequested && !isFinalizingExternally
+        if shouldHandle {
+            isFinalizingExternally = true
+        }
+        stateLock.unlock()
+        guard shouldHandle else { return }
+        recorder.delegate = nil
+
+        let outputURL = videoOutputURL
+        let didCreate = didCreateOutputFile
+        let hadVideo = videoHasContent
+
+        recorder.stopCapture(handler: { _ in
+            self.audioMixerQueue.sync {
+                if let mixer = self.audioTrackMixer {
+                    for sample in mixer.drain() {
+                        self.add(sample: sample, to: self.audioWriterInput)
+                    }
+                }
+            }
+
+            self.videoWriterInput?.markAsFinished()
+            self.audioWriterInput?.markAsFinished()
+
+            guard let writer = self.videoWriter else {
+                self.finishExternalStop(
+                    outputURL: outputURL,
+                    didCreate: didCreate,
+                    hadVideo: hadVideo,
+                    triggerError: error,
+                    finishError: nil,
+                    writerFailed: true,
+                )
+                return
+            }
+
+            let deliver: (Error?, Bool) -> Void = { finishError, writerFailed in
+                self.finishExternalStop(
+                    outputURL: outputURL,
+                    didCreate: didCreate,
+                    hadVideo: hadVideo,
+                    triggerError: error,
+                    finishError: finishError,
+                    writerFailed: writerFailed,
+                )
+            }
+
+            if writer.status == .writing {
+                writer.finishWriting {
+                    if let finishError = writer.error {
+                        self.deleteOutputFileIfNeeded(outputURL: outputURL, didCreate: didCreate)
+                        deliver(finishError, true)
+                        return
+                    }
+                    deliver(nil, false)
+                }
+            } else if writer.status == .failed {
+                self.deleteOutputFileIfNeeded(outputURL: outputURL, didCreate: didCreate)
+                deliver(writer.error, true)
+            } else {
+                deliver(nil, false)
+            }
+        })
+    }
+
+    private func finishExternalStop(
+        outputURL: URL?,
+        didCreate: Bool,
+        hadVideo: Bool,
+        triggerError: Error?,
+        finishError: Error?,
+        writerFailed: Bool,
+    ) {
+        stateLock.lock()
+        isFinalizingExternally = false
+        isRecording = false
+        stateLock.unlock()
+
+        let combinedError = triggerError ?? finishError
+        if !hadVideo {
+            deleteOutputFileIfNeeded(outputURL: outputURL, didCreate: didCreate)
+            onExternalStop?(nil, combinedError)
+            return
+        }
+        let exists = outputURL.map { FileManager.default.fileExists(atPath: $0.path) } ?? false
+        let url: URL? = (!writerFailed && exists) ? outputURL : nil
+        onExternalStop?(url, combinedError)
+    }
+
+    public func screenRecorder(
+        _ screenRecorder: RPScreenRecorder,
+        didStopRecordingWithError error: Error,
+        previewViewController: RPPreviewViewController?
+    ) {
+        if !startSettled {
+            failPendingStart(
+                error,
+                outputURL: videoOutputURL,
+                didCreate: didCreateOutputFile,
+            )
+            return
+        }
+        guard isRecording, !stopRequested else { return }
+        handleRecordingEndedExternally(error: error)
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-screen-recorder",
-  "version": "8.3.17",
+  "version": "8.4.0",
   "description": "Record device's screen",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",