munim-ffmpeg 0.7.0 → 0.8.0

package/README.md

@@ -94,12 +94,13 @@
 ### FFmpeg execution
 
 - 🎬 **Argument-array commands:** FFmpeg's own CLI code paths, without shell parsing or quoting
-- 🆕 **FFmpeg 9.0.1:** The current upstream release, identical on both platforms
+- 🆕 **FFmpeg 9.0.2:** The current upstream release, identical on both platforms
 - ⚡ **Asynchronous sessions:** Keep the React Native thread responsive during native work
 - 📝 **Live logs:** Receive FFmpeg output as it is produced
 - 📈 **Encoding statistics:** Track time, size, bitrate, speed, frames, FPS, and quality
 - 🎯 **Targeted cancellation:** Capture a native session ID immediately and cancel only that command
 - 🛑 **Global cancellation:** Stop all active sessions during workflow or screen cleanup
+- ⏸️ **Pause and resume:** Hold a running or queued session with no CPU use and continue exactly where it stopped
 
 ### FFprobe and media inspection
 
@@ -132,6 +133,8 @@
 | Immediate session ID         | ✅           | ✅         | `onSessionCreated` fires after the native session is created.                                                                                                           |
 | Cancel one FFmpeg session    | ✅           | ✅         | Pass the positive safe-integer ID received by `execute`'s `onSessionCreated`. The native dependency does not expose FFprobe cancellation.                               |
 | Cancel all FFmpeg sessions   | ✅           | ✅         | Use `cancelAll()` or call `cancel()` without an ID.                                                                                                                     |
+| Pause and resume a session   | ✅           | ✅         | `pause()` / `resume()` with an `execute` session ID, running or queued. FFprobe sessions cannot be paused.                                                              |
+| Session state                | ✅           | ✅         | `getSessionState()` reports `queued`, `running`, `paused`, `completed`, `failed`, or `cancelled`.                                                                       |
 | Expo Go                      | ❌           | ❌         | A native development build is required.                                                                                                                                 |
 | Capability discovery         | ✅           | ✅         | `listEncoders()`, `listDecoders()`, `listMuxers()`, `listDemuxers()`, `listFilters()`, `listProtocols()`, and `pickEncoder()` report what the bundled build supports.   |
 | Subtitle burn-in             | ✅           | ✅         | libass with system fonts: Core Text on iOS, fontconfig over `/system/fonts` on Android.                                                                                 |
@@ -144,13 +147,12 @@ Codec availability is determined by the native FFmpeg builds described in [Bundl
 
 ## Where this is verified
 
-Every release runs the example's 25-check device suite. For 0.4.x:
+Every release runs the example's device suite (33 checks, including pause/resume). For 0.8.x:
 
 | Target                     | Result                                                           |
 | -------------------------- | ---------------------------------------------------------------- |
-| iPad Air (M3), iOS 26      | 25/25                                                            |
-| iOS Simulator, arm64       | 25/25                                                            |
-| Galaxy A14 5G, arm64-v8a   | 25/25                                                            |
+| iPad Air (M3), iPadOS 27   | 33/33                                                            |
+| Galaxy A14 5G, arm64-v8a   | 33/33                                                            |
 | Android emulator, arm64    | Software encoding passes; hardware encoding does not — see below |
 | Android emulator, `x86_64` | Same: `libopenh264` passes, MediaCodec does not                  |
 | Android `armeabi-v7a`      | Built and statically checked, not executed                       |
@@ -183,11 +185,11 @@ await execute([
 
 ## Bundled FFmpeg builds
 
-Both platforms run **FFmpeg 9.0.1**, built from [ffmpeg.org](https://www.ffmpeg.org/) by the scripts in [`scripts/ffmpeg/`](./scripts/ffmpeg). There is no FFmpegKit here: that project was retired in 2025 and pinned to FFmpeg 6.0.
+Both platforms run **FFmpeg 9.0.2**, built from [ffmpeg.org](https://www.ffmpeg.org/) by the scripts in [`scripts/ffmpeg/`](./scripts/ffmpeg). There is no FFmpegKit here: that project was retired in 2025 and pinned to FFmpeg 6.0.
 
 |                 | iOS                                                     | Android                         |
 | --------------- | ------------------------------------------------------- | ------------------------------- |
-| FFmpeg          | 9.0.1                                                   | 9.0.1                           |
+| FFmpeg          | 9.0.2                                                   | 9.0.2                           |
 | Architectures   | arm64 device, arm64 + x86_64 simulator                  | arm64-v8a, armeabi-v7a, x86_64  |
 | Hardware codecs | VideoToolbox, AudioToolbox                              | MediaCodec                      |
 | TLS             | SecureTransport                                         | mbedTLS                         |
@@ -473,6 +475,57 @@ Cancels every active FFmpeg session.
 function cancelAll(): void
 ```
 
+### `pause(sessionId)` and `resume(sessionId)`
+
+Pauses a session started with `execute()`, whether it is running or still queued behind another one, and resumes it later.
+
+```typescript
+function pause(sessionId: number): boolean
+function resume(sessionId: number): boolean
+```
+
+FFmpeg itself has no pause, so munim-ffmpeg stops the threads that read its inputs. Everything downstream finishes the frames it already has and then waits, so a paused session uses no CPU. Output files stay open, and `resume()` carries on from the exact packet where reading stopped. Nothing is re-encoded, skipped or duplicated, and the `execute()` promise settles once, when the work is done. `-re` and `-readrate` inputs have their clocks shifted by the time spent paused, so they do not rush to catch up afterwards.
+
+`pause()` returns `false` if the session is unknown, has already finished, or is an FFprobe session. `resume()` returns `false` if the session was not paused. `cancel()` and `cancelAll()` work while paused.
+
+Notes:
+
+- The statistics callback keeps firing while paused, reporting the same `timeMs`. `speed` includes the paused time.
+- Live network inputs are not read while paused. Servers that drop idle connections may end the session when it resumes.
+
+```typescript
+import { execute, pause, resume } from 'munim-ffmpeg'
+
+let sessionId: number | undefined
+const done = execute(args, undefined, undefined, (id) => {
+  sessionId = id
+})
+
+// Later, from a pause button:
+pause(sessionId!)
+// …and from a resume button:
+resume(sessionId!)
+
+const result = await done
+```
+
+### `getSessionState(sessionId)`
+
+```typescript
+type FFmpegSessionState =
+  | 'queued'
+  | 'running'
+  | 'paused'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'unknown'
+
+function getSessionState(sessionId: number): FFmpegSessionState
+```
+
+`queued` sessions are waiting for the one running ahead of them, since FFmpeg runs one execution at a time. `unknown` means the ID was never issued, or it finished long enough ago that its record was dropped (the last 512 finished sessions are kept).
+
 ### `getFFmpegVersion()`
 
 Returns the version reported by the bundled native FFmpeg library.
@@ -882,7 +935,7 @@ if (result.success) {
 
 The JavaScript, TypeScript, Swift, Kotlin, C core, and generated Nitro bridge in this repository are Apache-2.0.
 
-The bundled FFmpeg 9.0.1 is **LGPLv3**, on both platforms. It is configured without `--enable-gpl`, so no x264, x265, xvid, or vid.stab. The external libraries it links are LAME (LGPL), Opus (BSD), libvpx (BSD), dav1d (BSD), libaom (BSD 2-clause with the Alliance for Open Media patent licence), openh264 (BSD 2-clause), libass (ISC), FreeType (FTL, BSD-style with credit), HarfBuzz (MIT-style), FriBidi (LGPL), and, on Android only, mbedTLS (Apache-2.0), fontconfig (MIT-style), and expat (MIT). None of them change the LGPL story.
+The bundled FFmpeg 9.0.2 is **LGPLv3**, on both platforms. It is configured without `--enable-gpl`, so no x264, x265, xvid, or vid.stab. The external libraries it links are LAME (LGPL), Opus (BSD), libvpx (BSD), dav1d (BSD), libaom (BSD 2-clause with the Alliance for Open Media patent licence), openh264 (BSD 2-clause), libass (ISC), FreeType (FTL, BSD-style with credit), HarfBuzz (MIT-style), FriBidi (LGPL), and, on Android only, mbedTLS (Apache-2.0), fontconfig (MIT-style), and expat (MIT). None of them change the LGPL story.
 
 > **A note on H.264 patents.** Hardware encoders are covered by the licences device manufacturers already pay for. Software H.264 encoding through `libopenh264` is not: Cisco's royalty coverage applies to _their_ prebuilt binary, and this package builds openh264 from source. If you ship software H.264 encoding at scale, check where you stand with AVC licensing. Hardware encoders avoid the question entirely, which is why `pickEncoder` should list them first.
 

package/android/src/main/java/com/margelo/nitro/munimffmpeg/FFmpegNative.kt

@@ -79,16 +79,27 @@ object FFmpegNative {
     arguments: Array<String>,
     stdoutPath: String,
     session: FFmpegSession,
+    sessionId: Long,
   ): Int
 
   external fun nativeExecuteProbe(
     arguments: Array<String>,
     outputPath: String,
     session: FFmpegSession,
+    sessionId: Long,
   ): Int
 
   external fun nativeCancel()
 
+  external fun nativePause(sessionId: Long): Boolean
+
+  external fun nativeResume(sessionId: Long): Boolean
+
+  external fun nativeIsPaused(sessionId: Long): Boolean
+
+  /** Id of the execution or probe currently running, or 0. */
+  external fun nativeRunningSession(): Long
+
   /**
    * libass discovers fonts through fontconfig, and Android has no fonts.conf,
    * so one pointing at the system font directories is written to the app's

package/android/src/main/java/com/margelo/nitro/munimffmpeg/HybridMunimFfmpeg.kt

@@ -16,6 +16,7 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     get() = FFmpegNative.nativeVersion()
 
   private val sessions = AtomicLong(0)
+  private val registry = SessionRegistry()
 
   private fun nextSession() = sessions.incrementAndGet().toDouble()
 
@@ -72,6 +73,7 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     onSessionCreated: ((sessionId: Double) -> Unit)?,
   ): Promise<FFmpegSessionResult> {
     val sessionId = nextSession()
+    registry.register(sessionId, SessionRegistry.Kind.EXECUTE)
     onSessionCreated?.invoke(sessionId)
 
     return runOnFfmpegThread {
@@ -84,7 +86,11 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
         logSink = { message -> onLog?.invoke(message) },
         statisticsSink = onStatistics,
       )
-      val returnCode = FFmpegNative.nativeExecute(arguments_, stdout.absolutePath, session)
+      val returnCode =
+        FFmpegNative.nativeExecute(arguments_, stdout.absolutePath, session, sessionId.toLong())
+      // A pause that raced the end of the run would otherwise stay listed.
+      FFmpegNative.nativeResume(sessionId.toLong())
+      registry.finish(sessionId, returnCode)
 
       val printed = runCatching { stdout.readText() }.getOrDefault("")
       stdout.delete()
@@ -99,11 +105,13 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     onSessionCreated: ((sessionId: Double) -> Unit)?,
   ): Promise<FFmpegSessionResult> {
     val sessionId = nextSession()
+    registry.register(sessionId, SessionRegistry.Kind.PROBE)
     onSessionCreated?.invoke(sessionId)
 
     return runOnFfmpegThread {
       val startedAt = System.currentTimeMillis()
-      val (returnCode, report) = runProbe(arguments_, onLog)
+      val (returnCode, report) = runProbe(arguments_, onLog, sessionId.toLong())
+      registry.finish(sessionId, returnCode)
       result(sessionId, returnCode, report, System.currentTimeMillis() - startedAt)
     }
   }
@@ -141,6 +149,7 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
   private fun runProbe(
     arguments: Array<String>,
     onLog: ((message: String) -> Unit)?,
+    sessionId: Long = 0,
   ): Pair<Int, String> {
     val destination = File.createTempFile("munim-ffprobe", ".txt")
     try {
@@ -149,7 +158,7 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
         statisticsSink = null,
       )
       val returnCode =
-        FFmpegNative.nativeExecuteProbe(arguments, destination.absolutePath, session)
+        FFmpegNative.nativeExecuteProbe(arguments, destination.absolutePath, session, sessionId)
 
       val report = destination.readText()
       return returnCode to report.ifEmpty { session.output }
@@ -158,17 +167,19 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     }
   }
 
-  override fun cancel(sessionId: Double?) {
-    if (sessionId != null) {
-      require(
-        sessionId.isFinite() &&
-          sessionId > 0 &&
-          sessionId % 1.0 == 0.0 &&
-          sessionId <= 9_007_199_254_740_991.0,
-      ) {
-        "Invalid FFmpeg session ID: $sessionId. Expected a positive safe integer."
-      }
+  private fun validate(sessionId: Double) {
+    require(
+      sessionId.isFinite() &&
+        sessionId > 0 &&
+        sessionId % 1.0 == 0.0 &&
+        sessionId <= 9_007_199_254_740_991.0,
+    ) {
+      "Invalid FFmpeg session ID: $sessionId. Expected a positive safe integer."
     }
+  }
+
+  override fun cancel(sessionId: Double?) {
+    if (sessionId != null) validate(sessionId)
     // Only one execution runs at a time, so a targeted cancel and cancelAll()
     // are the same operation.
     FFmpegNative.nativeCancel()
@@ -178,6 +189,36 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     FFmpegNative.nativeCancel()
   }
 
+  override fun pause(sessionId: Double): Boolean {
+    validate(sessionId)
+    if (registry.activeKind(sessionId) != SessionRegistry.Kind.EXECUTE) return false
+    FFmpegNative.nativePause(sessionId.toLong())
+    // The run may have ended between the check and the pause.
+    if (registry.activeKind(sessionId) == null) {
+      FFmpegNative.nativeResume(sessionId.toLong())
+      return false
+    }
+    return true
+  }
+
+  override fun resume(sessionId: Double): Boolean {
+    validate(sessionId)
+    return FFmpegNative.nativeResume(sessionId.toLong())
+  }
+
+  override fun getSessionState(sessionId: Double): FFmpegSessionState {
+    validate(sessionId)
+    registry.finishedState(sessionId)?.let { return it }
+    if (registry.activeKind(sessionId) == null) return FFmpegSessionState.UNKNOWN
+    val id = sessionId.toLong()
+    if (FFmpegNative.nativeIsPaused(id)) return FFmpegSessionState.PAUSED
+    return if (FFmpegNative.nativeRunningSession() == id) {
+      FFmpegSessionState.RUNNING
+    } else {
+      FFmpegSessionState.QUEUED
+    }
+  }
+
   private companion object {
     private val threadCounter = AtomicInteger(0)
 
@@ -191,3 +232,43 @@ class HybridMunimFfmpeg : HybridMunimFfmpegSpec() {
     )
   }
 }
+
+/**
+ * What the module remembers about each session id. Whether an unfinished
+ * session is queued, running or paused is asked of the native core, which is
+ * the only place that knows.
+ */
+private class SessionRegistry {
+  enum class Kind { EXECUTE, PROBE }
+
+  private val kinds = HashMap<Double, Kind>()
+  private val finished = LinkedHashMap<Double, FFmpegSessionState>()
+
+  @Synchronized
+  fun register(sessionId: Double, kind: Kind) {
+    kinds[sessionId] = kind
+  }
+
+  @Synchronized
+  fun finish(sessionId: Double, returnCode: Int) {
+    kinds.remove(sessionId)
+    finished[sessionId] = when (returnCode) {
+      FFmpegNative.CANCELLED -> FFmpegSessionState.CANCELLED
+      0 -> FFmpegSessionState.COMPLETED
+      else -> FFmpegSessionState.FAILED
+    }
+    // Finished sessions are forgotten, oldest first, beyond this many.
+    while (finished.size > FINISHED_LIMIT) finished.remove(finished.keys.first())
+  }
+
+  /** null once finished or never issued. */
+  @Synchronized
+  fun activeKind(sessionId: Double): Kind? = kinds[sessionId]
+
+  @Synchronized
+  fun finishedState(sessionId: Double): FFmpegSessionState? = finished[sessionId]
+
+  private companion object {
+    const val FINISHED_LIMIT = 512
+  }
+}

package/ios/HybridMunimFfmpeg.swift

@@ -55,8 +55,57 @@ private let installCallbacks: Void = munim_ffmpeg_set_callbacks({ context, messa
   session.onStatistics?(timeMs, sizeBytes, bitrate, speed, frame, fps, quality)
 }, nil)
 
+/// What the module remembers about each session id. Whether an unfinished
+/// session is queued, running or paused is asked of the C core, which is the
+/// only place that knows.
+private final class SessionRegistry {
+  enum Kind { case execute, probe }
+
+  private var kinds: [Double: Kind] = [:]
+  private var finished: [Double: FFmpegSessionState] = [:]
+  private var finishedOrder: [Double] = []
+  private let lock = NSLock()
+  /// Finished sessions are forgotten, oldest first, beyond this many.
+  private let finishedLimit = 512
+
+  func register(_ sessionId: Double, _ kind: Kind) {
+    lock.lock()
+    kinds[sessionId] = kind
+    lock.unlock()
+  }
+
+  func finish(_ sessionId: Double, returnCode: Int32) {
+    let state: FFmpegSessionState =
+      returnCode == Int32(MUNIM_FFMPEG_CANCELLED) ? .cancelled
+      : returnCode == 0 ? .completed
+      : .failed
+    lock.lock()
+    kinds[sessionId] = nil
+    finished[sessionId] = state
+    finishedOrder.append(sessionId)
+    if finishedOrder.count > finishedLimit {
+      finished[finishedOrder.removeFirst()] = nil
+    }
+    lock.unlock()
+  }
+
+  /// nil once finished or never issued.
+  func activeKind(_ sessionId: Double) -> Kind? {
+    lock.lock()
+    defer { lock.unlock() }
+    return kinds[sessionId]
+  }
+
+  func finishedState(_ sessionId: Double) -> FFmpegSessionState? {
+    lock.lock()
+    defer { lock.unlock() }
+    return finished[sessionId]
+  }
+}
+
 final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
   private var sessionCounter: Double = 0
+  private let registry = SessionRegistry()
 
   var ffmpegVersion: String {
     String(cString: munim_ffmpeg_version())
@@ -99,6 +148,7 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
   ) throws -> Promise<FFmpegSessionResult> {
     let promise = Promise<FFmpegSessionResult>()
     let sessionId = nextSession()
+    registry.register(sessionId, .execute)
     onSessionCreated?(sessionId)
 
     executionQueue.async {
@@ -112,14 +162,18 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
 
       let returnCode = withExtendedLifetime(session) {
         withArrayOfCStrings(arguments_) { argv in
-          munim_ffmpeg_execute_ctx(
+          munim_ffmpeg_execute_session(
             Int32(arguments_.count),
             argv,
             printedPath,
-            Unmanaged.passUnretained(session).toOpaque()
+            Unmanaged.passUnretained(session).toOpaque(),
+            Int64(sessionId)
           )
         }
       }
+      // A pause that raced the end of the run would otherwise stay listed.
+      _ = munim_ffmpeg_resume(Int64(sessionId))
+      self.registry.finish(sessionId, returnCode: returnCode)
 
       let printed = (try? String(contentsOfFile: printedPath, encoding: .utf8)) ?? ""
       try? FileManager.default.removeItem(atPath: printedPath)
@@ -144,11 +198,13 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
   ) throws -> Promise<FFmpegSessionResult> {
     let promise = Promise<FFmpegSessionResult>()
     let sessionId = nextSession()
+    registry.register(sessionId, .probe)
     onSessionCreated?(sessionId)
 
     executionQueue.async {
       let startedAt = Date()
-      let (returnCode, report) = Self.runProbe(arguments_, onLog: onLog)
+      let (returnCode, report) = Self.runProbe(arguments_, onLog: onLog, sessionId: sessionId)
+      self.registry.finish(sessionId, returnCode: returnCode)
       promise.resolve(
         withResult: self.result(
           sessionId: sessionId,
@@ -195,7 +251,8 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
   /// so it is pointed at a temporary file with `-o` and read back.
   private static func runProbe(
     _ arguments: [String],
-    onLog: ((String) -> Void)?
+    onLog: ((String) -> Void)?,
+    sessionId: Double = 0
   ) -> (Int32, String) {
     let destination = temporaryFile()
 
@@ -204,11 +261,12 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
 
     let returnCode = withExtendedLifetime(session) {
       withArrayOfCStrings(arguments) { argv in
-        munim_ffmpeg_probe_ctx(
+        munim_ffmpeg_probe_session(
           Int32(arguments.count),
           argv,
           destination,
-          Unmanaged.passUnretained(session).toOpaque()
+          Unmanaged.passUnretained(session).toOpaque(),
+          Int64(sessionId)
         )
       }
     }
@@ -219,16 +277,20 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
     return (returnCode, report.isEmpty ? session.output : report)
   }
 
+  private static func validate(_ sessionId: Double) throws {
+    guard
+      sessionId.isFinite,
+      sessionId > 0,
+      sessionId.rounded(.towardZero) == sessionId,
+      sessionId <= 9_007_199_254_740_991
+    else {
+      throw MunimFfmpegError.invalidSessionId(sessionId)
+    }
+  }
+
   func cancel(sessionId: Double?) throws {
     if let sessionId {
-      guard
-        sessionId.isFinite,
-        sessionId > 0,
-        sessionId.rounded(.towardZero) == sessionId,
-        sessionId <= 9_007_199_254_740_991
-      else {
-        throw MunimFfmpegError.invalidSessionId(sessionId)
-      }
+      try Self.validate(sessionId)
     }
     // One execution runs at a time, so cancelling a specific session and
     // cancelling everything are the same operation.
@@ -238,6 +300,32 @@ final class HybridMunimFfmpeg: HybridMunimFfmpegSpec {
   func cancelAll() throws {
     munim_ffmpeg_cancel()
   }
+
+  func pause(sessionId: Double) throws -> Bool {
+    try Self.validate(sessionId)
+    guard registry.activeKind(sessionId) == .execute else { return false }
+    _ = munim_ffmpeg_pause(Int64(sessionId))
+    // The run may have ended between the check and the pause; the core drops
+    // the pause of a finished session, so report what actually happened.
+    if registry.activeKind(sessionId) == nil {
+      _ = munim_ffmpeg_resume(Int64(sessionId))
+      return false
+    }
+    return true
+  }
+
+  func resume(sessionId: Double) throws -> Bool {
+    try Self.validate(sessionId)
+    return munim_ffmpeg_resume(Int64(sessionId)) != 0
+  }
+
+  func getSessionState(sessionId: Double) throws -> FFmpegSessionState {
+    try Self.validate(sessionId)
+    if let state = registry.finishedState(sessionId) { return state }
+    guard registry.activeKind(sessionId) != nil else { return .unknown }
+    if munim_ffmpeg_is_paused(Int64(sessionId)) != 0 { return .paused }
+    return munim_ffmpeg_running_session() == Int64(sessionId) ? .running : .queued
+  }
 }
 
 /// Builds a C `argv` that stays valid for the duration of `body`.

package/ios/munim_ffmpeg_core.h

@@ -61,6 +61,41 @@ int munim_ffmpeg_probe_ctx(int argc, const char *const *argv,
  */
 void munim_ffmpeg_cancel(void);
 
+/**
+ * Like munim_ffmpeg_execute_ctx, for a run identified by `session_id` (> 0) so
+ * it can be paused and resumed. munim_ffmpeg_execute_ctx runs with id 0, which
+ * cannot be paused.
+ */
+int munim_ffmpeg_execute_session(int argc, const char *const *argv,
+                                 const char *stdout_path, void *context,
+                                 long long session_id);
+
+/**
+ * Pauses the execution with `session_id`. If it is running, its input threads
+ * stop reading and the rest of the pipeline idles once it has drained; if it is
+ * still queued, it will start paused. Output files stay open and
+ * munim_ffmpeg_resume() continues exactly where it stopped. Cancelling works
+ * as usual and also clears every pause. Returns 1 if the session is running.
+ */
+int munim_ffmpeg_pause(long long session_id);
+
+/** Resumes `session_id`. Returns 1 if it was paused. */
+int munim_ffmpeg_resume(long long session_id);
+
+/** Returns 1 while `session_id` is paused. */
+int munim_ffmpeg_is_paused(long long session_id);
+
+/**
+ * Id of the execution or probe currently running, or 0. Probes started through
+ * munim_ffmpeg_probe_session report their id here but cannot be paused.
+ */
+long long munim_ffmpeg_running_session(void);
+
+/** Like munim_ffmpeg_probe_ctx, for a run identified by `session_id`. */
+int munim_ffmpeg_probe_session(int argc, const char *const *argv,
+                               const char *output_path, void *context,
+                               long long session_id);
+
 /** Return code reported when a run was cancelled. */
 #define MUNIM_FFMPEG_CANCELLED 255
 

package/lib/index.d.ts

@@ -1,6 +1,6 @@
-import type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegStatisticsCallback, MunimFfmpeg as MunimFfmpegSpec } from './specs/MunimFfmpeg.nitro';
+import type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegSessionState, FFmpegStatisticsCallback, MunimFfmpeg as MunimFfmpegSpec } from './specs/MunimFfmpeg.nitro';
 declare const MunimFfmpeg: MunimFfmpegSpec;
-export type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegStatisticsCallback, MunimFfmpegSpec, };
+export type { FFmpegLogCallback, FFmpegSessionResult, FFmpegSessionCreatedCallback, FFmpegSessionState, FFmpegStatisticsCallback, MunimFfmpegSpec, };
 /**
  * Converts a `file://` URI into the plain path FFmpeg expects.
  *
@@ -98,6 +98,20 @@ export declare function getMediaInformation(path: string): Promise<MediaInformat
 export declare function getMediaDuration(information: MediaInformation): number | undefined;
 export declare function cancel(sessionId?: number): void;
 export declare function cancelAll(): void;
+/**
+ * Pauses a session started with `execute()`, whether it is running or still
+ * queued. FFmpeg stops reading its inputs and the rest of the pipeline idles
+ * once it has drained, so a paused session costs no CPU. Output files stay
+ * open, and `resume()` continues from exactly where it stopped: nothing is
+ * re-encoded or skipped, and the `execute()` promise settles once, when the
+ * work finishes. `cancel()` still works while paused.
+ *
+ * Returns false if the session is unknown, has finished, or is a probe.
+ */
+export declare function pause(sessionId: number): boolean;
+/** Resumes a paused session. Returns false if it was not paused. */
+export declare function resume(sessionId: number): boolean;
+export declare function getSessionState(sessionId: number): FFmpegSessionState;
 export declare function getFFmpegVersion(): string;
 /** Encoder names the bundled FFmpeg build can write, e.g. `libx264`. */
 export declare function listEncoders(): Promise<string[]>;

package/lib/index.js

@@ -46,6 +46,26 @@ export function cancel(sessionId) {
 export function cancelAll() {
     MunimFfmpeg.cancelAll();
 }
+/**
+ * Pauses a session started with `execute()`, whether it is running or still
+ * queued. FFmpeg stops reading its inputs and the rest of the pipeline idles
+ * once it has drained, so a paused session costs no CPU. Output files stay
+ * open, and `resume()` continues from exactly where it stopped: nothing is
+ * re-encoded or skipped, and the `execute()` promise settles once, when the
+ * work finishes. `cancel()` still works while paused.
+ *
+ * Returns false if the session is unknown, has finished, or is a probe.
+ */
+export function pause(sessionId) {
+    return MunimFfmpeg.pause(sessionId);
+}
+/** Resumes a paused session. Returns false if it was not paused. */
+export function resume(sessionId) {
+    return MunimFfmpeg.resume(sessionId);
+}
+export function getSessionState(sessionId) {
+    return MunimFfmpeg.getSessionState(sessionId);
+}
 export function getFFmpegVersion() {
     return MunimFfmpeg.ffmpegVersion;
 }

package/lib/specs/MunimFfmpeg.nitro.d.ts

@@ -9,6 +9,12 @@ export type FFmpegSessionResult = {
     output: string;
     failStackTrace?: string;
 };
+/**
+ * Where a session is in its life. `queued` sessions wait for the one running
+ * ahead of them (FFmpeg runs one execution at a time); `unknown` means the id
+ * was never issued or its record has been dropped.
+ */
+export type FFmpegSessionState = 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'unknown';
 export type FFmpegLogCallback = (message: string) => void;
 export type FFmpegSessionCreatedCallback = (sessionId: number) => void;
 export type FFmpegStatisticsCallback = (timeMs: number, sizeBytes: number, bitrateKbits: number, speed: number, videoFrameNumber: number, fps: number, quality: number) => void;
@@ -22,4 +28,13 @@ export interface MunimFfmpeg extends HybridObject<{
     getMediaInformation(path: string): Promise<string>;
     cancel(sessionId?: number): void;
     cancelAll(): void;
+    /**
+     * Pauses an `execute()` session, running or still queued. Input stops being
+     * read and the pipeline idles; output files stay open. Returns false if the
+     * session is unknown, finished, or a probe (probes cannot be paused).
+     */
+    pause(sessionId: number): boolean;
+    /** Resumes a paused session. Returns false if it was not paused. */
+    resume(sessionId: number): boolean;
+    getSessionState(sessionId: number): FFmpegSessionState;
 }

package/nitrogen/generated/android/c++/JFFmpegSessionState.hpp

@@ -0,0 +1,73 @@
+///
+/// JFFmpegSessionState.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include "FFmpegSessionState.hpp"
+
+namespace margelo::nitro::munimffmpeg {
+
+  using namespace facebook;
+
+  /**
+   * The C++ JNI bridge between the C++ enum "FFmpegSessionState" and the Kotlin enum "FFmpegSessionState".
+   */
+  struct JFFmpegSessionState final: public jni::JavaClass<JFFmpegSessionState> {
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/munimffmpeg/FFmpegSessionState;";
+
+  public:
+    /**
+     * Convert this Java/Kotlin-based enum to the C++ enum FFmpegSessionState.
+     */
+    [[maybe_unused]]
+    [[nodiscard]]
+    FFmpegSessionState toCpp() const {
+      static const auto clazz = javaClassStatic();
+      static const auto fieldOrdinal = clazz->getField<int>("value");
+      int ordinal = this->getFieldValue(fieldOrdinal);
+      return static_cast<FFmpegSessionState>(ordinal);
+    }
+
+  public:
+    /**
+     * Create a Java/Kotlin-based enum with the given C++ enum's value.
+     */
+    [[maybe_unused]]
+    static jni::alias_ref<JFFmpegSessionState> fromCpp(FFmpegSessionState value) {
+      static const auto clazz = javaClassStatic();
+      switch (value) {
+        case FFmpegSessionState::QUEUED:
+          static const auto fieldQUEUED = clazz->getStaticField<JFFmpegSessionState>("QUEUED");
+          return clazz->getStaticFieldValue(fieldQUEUED);
+        case FFmpegSessionState::RUNNING:
+          static const auto fieldRUNNING = clazz->getStaticField<JFFmpegSessionState>("RUNNING");
+          return clazz->getStaticFieldValue(fieldRUNNING);
+        case FFmpegSessionState::PAUSED:
+          static const auto fieldPAUSED = clazz->getStaticField<JFFmpegSessionState>("PAUSED");
+          return clazz->getStaticFieldValue(fieldPAUSED);
+        case FFmpegSessionState::COMPLETED:
+          static const auto fieldCOMPLETED = clazz->getStaticField<JFFmpegSessionState>("COMPLETED");
+          return clazz->getStaticFieldValue(fieldCOMPLETED);
+        case FFmpegSessionState::FAILED:
+          static const auto fieldFAILED = clazz->getStaticField<JFFmpegSessionState>("FAILED");
+          return clazz->getStaticFieldValue(fieldFAILED);
+        case FFmpegSessionState::CANCELLED:
+          static const auto fieldCANCELLED = clazz->getStaticField<JFFmpegSessionState>("CANCELLED");
+          return clazz->getStaticFieldValue(fieldCANCELLED);
+        case FFmpegSessionState::UNKNOWN:
+          static const auto fieldUNKNOWN = clazz->getStaticField<JFFmpegSessionState>("UNKNOWN");
+          return clazz->getStaticFieldValue(fieldUNKNOWN);
+        default:
+          std::string stringValue = std::to_string(static_cast<int>(value));
+          throw std::invalid_argument("Invalid enum value (" + stringValue + "!");
+      }
+    }
+  };
+
+} // namespace margelo::nitro::munimffmpeg

package/nitrogen/generated/android/c++/JHybridMunimFfmpegSpec.cpp

@@ -9,6 +9,8 @@
 
 // Forward declaration of `FFmpegSessionResult` to properly resolve imports.
 namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
+// Forward declaration of `FFmpegSessionState` to properly resolve imports.
+namespace margelo::nitro::munimffmpeg { enum class FFmpegSessionState; }
 
 #include <string>
 #include "FFmpegSessionResult.hpp"
@@ -16,6 +18,8 @@ namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
 #include <NitroModules/JPromise.hpp>
 #include "JFFmpegSessionResult.hpp"
 #include <optional>
+#include "FFmpegSessionState.hpp"
+#include "JFFmpegSessionState.hpp"
 #include <vector>
 #include <functional>
 #include "JFunc_void_std__string.hpp"
@@ -134,5 +138,20 @@ namespace margelo::nitro::munimffmpeg {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void()>("cancelAll");
     method(_javaPart);
   }
+  bool JHybridMunimFfmpegSpec::pause(double sessionId) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jboolean(double /* sessionId */)>("pause");
+    auto __result = method(_javaPart, sessionId);
+    return static_cast<bool>(__result);
+  }
+  bool JHybridMunimFfmpegSpec::resume(double sessionId) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jboolean(double /* sessionId */)>("resume");
+    auto __result = method(_javaPart, sessionId);
+    return static_cast<bool>(__result);
+  }
+  FFmpegSessionState JHybridMunimFfmpegSpec::getSessionState(double sessionId) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JFFmpegSessionState>(double /* sessionId */)>("getSessionState");
+    auto __result = method(_javaPart, sessionId);
+    return __result->toCpp();
+  }
 
 } // namespace margelo::nitro::munimffmpeg

package/nitrogen/generated/android/c++/JHybridMunimFfmpegSpec.hpp

@@ -59,6 +59,9 @@ namespace margelo::nitro::munimffmpeg {
     std::shared_ptr<Promise<std::string>> getMediaInformation(const std::string& path) override;
     void cancel(std::optional<double> sessionId) override;
     void cancelAll() override;
+    bool pause(double sessionId) override;
+    bool resume(double sessionId) override;
+    FFmpegSessionState getSessionState(double sessionId) override;
 
   private:
     jni::global_ref<JHybridMunimFfmpegSpec::JavaPart> _javaPart;

package/nitrogen/generated/android/kotlin/com/margelo/nitro/munimffmpeg/FFmpegSessionState.kt

@@ -0,0 +1,28 @@
+///
+/// FFmpegSessionState.kt
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+package com.margelo.nitro.munimffmpeg
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+
+/**
+ * Represents the JavaScript enum/union "FFmpegSessionState".
+ */
+@DoNotStrip
+@Keep
+enum class FFmpegSessionState(@DoNotStrip @Keep val value: Int) {
+  QUEUED(0),
+  RUNNING(1),
+  PAUSED(2),
+  COMPLETED(3),
+  FAILED(4),
+  CANCELLED(5),
+  UNKNOWN(6);
+
+  companion object
+}

package/nitrogen/generated/android/kotlin/com/margelo/nitro/munimffmpeg/HybridMunimFfmpegSpec.kt

@@ -61,6 +61,18 @@ abstract class HybridMunimFfmpegSpec: HybridObject() {
   @DoNotStrip
   @Keep
   abstract fun cancelAll(): Unit
+  
+  @DoNotStrip
+  @Keep
+  abstract fun pause(sessionId: Double): Boolean
+  
+  @DoNotStrip
+  @Keep
+  abstract fun resume(sessionId: Double): Boolean
+  
+  @DoNotStrip
+  @Keep
+  abstract fun getSessionState(sessionId: Double): FFmpegSessionState
 
   // Default implementation of `HybridObject.toString()`
   override fun toString(): String {

package/nitrogen/generated/ios/NitroMunimFfmpeg-Swift-Cxx-Bridge.hpp

@@ -10,6 +10,8 @@
 // Forward declarations of C++ defined types
 // Forward declaration of `FFmpegSessionResult` to properly resolve imports.
 namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
+// Forward declaration of `FFmpegSessionState` to properly resolve imports.
+namespace margelo::nitro::munimffmpeg { enum class FFmpegSessionState; }
 // Forward declaration of `HybridMunimFfmpegSpec` to properly resolve imports.
 namespace margelo::nitro::munimffmpeg { class HybridMunimFfmpegSpec; }
 
@@ -19,6 +21,7 @@ namespace NitroMunimFfmpeg { class HybridMunimFfmpegSpec_cxx; }
 
 // Include C++ defined types
 #include "FFmpegSessionResult.hpp"
+#include "FFmpegSessionState.hpp"
 #include "HybridMunimFfmpegSpec.hpp"
 #include <NitroModules/Promise.hpp>
 #include <NitroModules/PromiseHolder.hpp>
@@ -294,5 +297,23 @@ namespace margelo::nitro::munimffmpeg::bridge::swift {
   inline Result_void_ create_Result_void_(const std::exception_ptr& error) noexcept {
     return Result<void>::withError(error);
   }
+  
+  // pragma MARK: Result<bool>
+  using Result_bool_ = Result<bool>;
+  inline Result_bool_ create_Result_bool_(bool value) noexcept {
+    return Result<bool>::withValue(std::move(value));
+  }
+  inline Result_bool_ create_Result_bool_(const std::exception_ptr& error) noexcept {
+    return Result<bool>::withError(error);
+  }
+  
+  // pragma MARK: Result<FFmpegSessionState>
+  using Result_FFmpegSessionState_ = Result<FFmpegSessionState>;
+  inline Result_FFmpegSessionState_ create_Result_FFmpegSessionState_(FFmpegSessionState value) noexcept {
+    return Result<FFmpegSessionState>::withValue(std::move(value));
+  }
+  inline Result_FFmpegSessionState_ create_Result_FFmpegSessionState_(const std::exception_ptr& error) noexcept {
+    return Result<FFmpegSessionState>::withError(error);
+  }
 
 } // namespace margelo::nitro::munimffmpeg::bridge::swift

package/nitrogen/generated/ios/NitroMunimFfmpeg-Swift-Cxx-Umbrella.hpp

@@ -10,11 +10,14 @@
 // Forward declarations of C++ defined types
 // Forward declaration of `FFmpegSessionResult` to properly resolve imports.
 namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
+// Forward declaration of `FFmpegSessionState` to properly resolve imports.
+namespace margelo::nitro::munimffmpeg { enum class FFmpegSessionState; }
 // Forward declaration of `HybridMunimFfmpegSpec` to properly resolve imports.
 namespace margelo::nitro::munimffmpeg { class HybridMunimFfmpegSpec; }
 
 // Include C++ defined types
 #include "FFmpegSessionResult.hpp"
+#include "FFmpegSessionState.hpp"
 #include "HybridMunimFfmpegSpec.hpp"
 #include <NitroModules/Promise.hpp>
 #include <NitroModules/Result.hpp>

package/nitrogen/generated/ios/c++/HybridMunimFfmpegSpecSwift.hpp

@@ -14,6 +14,8 @@ namespace NitroMunimFfmpeg { class HybridMunimFfmpegSpec_cxx; }
 
 // Forward declaration of `FFmpegSessionResult` to properly resolve imports.
 namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
+// Forward declaration of `FFmpegSessionState` to properly resolve imports.
+namespace margelo::nitro::munimffmpeg { enum class FFmpegSessionState; }
 
 #include <string>
 #include "FFmpegSessionResult.hpp"
@@ -21,6 +23,7 @@ namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
 #include <optional>
 #include <vector>
 #include <functional>
+#include "FFmpegSessionState.hpp"
 
 #include "NitroMunimFfmpeg-Swift-Cxx-Umbrella.hpp"
 
@@ -111,6 +114,30 @@ namespace margelo::nitro::munimffmpeg {
         std::rethrow_exception(__result.error());
       }
     }
+    inline bool pause(double sessionId) override {
+      auto __result = _swiftPart.pause(std::forward<decltype(sessionId)>(sessionId));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+      auto __value = std::move(__result.value());
+      return __value;
+    }
+    inline bool resume(double sessionId) override {
+      auto __result = _swiftPart.resume(std::forward<decltype(sessionId)>(sessionId));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+      auto __value = std::move(__result.value());
+      return __value;
+    }
+    inline FFmpegSessionState getSessionState(double sessionId) override {
+      auto __result = _swiftPart.getSessionState(std::forward<decltype(sessionId)>(sessionId));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+      auto __value = std::move(__result.value());
+      return __value;
+    }
 
   private:
     NitroMunimFfmpeg::HybridMunimFfmpegSpec_cxx _swiftPart;

package/nitrogen/generated/ios/swift/FFmpegSessionState.swift

@@ -0,0 +1,60 @@
+///
+/// FFmpegSessionState.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+/**
+ * Represents the JS union `FFmpegSessionState`, backed by a C++ enum.
+ */
+public typealias FFmpegSessionState = margelo.nitro.munimffmpeg.FFmpegSessionState
+
+public extension FFmpegSessionState {
+  /**
+   * Get a FFmpegSessionState for the given String value, or
+   * return `nil` if the given value was invalid/unknown.
+   */
+  init?(fromString string: String) {
+    switch string {
+      case "queued":
+        self = .queued
+      case "running":
+        self = .running
+      case "paused":
+        self = .paused
+      case "completed":
+        self = .completed
+      case "failed":
+        self = .failed
+      case "cancelled":
+        self = .cancelled
+      case "unknown":
+        self = .unknown
+      default:
+        return nil
+    }
+  }
+
+  /**
+   * Get the String value this FFmpegSessionState represents.
+   */
+  var stringValue: String {
+    switch self {
+      case .queued:
+        return "queued"
+      case .running:
+        return "running"
+      case .paused:
+        return "paused"
+      case .completed:
+        return "completed"
+      case .failed:
+        return "failed"
+      case .cancelled:
+        return "cancelled"
+      case .unknown:
+        return "unknown"
+    }
+  }
+}

package/nitrogen/generated/ios/swift/HybridMunimFfmpegSpec.swift

@@ -18,6 +18,9 @@ public protocol HybridMunimFfmpegSpec_protocol: HybridObject {
   func getMediaInformation(path: String) throws -> Promise<String>
   func cancel(sessionId: Double?) throws -> Void
   func cancelAll() throws -> Void
+  func pause(sessionId: Double) throws -> Bool
+  func resume(sessionId: Double) throws -> Bool
+  func getSessionState(sessionId: Double) throws -> FFmpegSessionState
 }
 
 public extension HybridMunimFfmpegSpec_protocol {

package/nitrogen/generated/ios/swift/HybridMunimFfmpegSpec_cxx.swift

@@ -274,4 +274,40 @@ open class HybridMunimFfmpegSpec_cxx {
       return bridge.create_Result_void_(__exceptionPtr)
     }
   }
+  
+  @inline(__always)
+  public final func pause(sessionId: Double) -> bridge.Result_bool_ {
+    do {
+      let __result = try self.__implementation.pause(sessionId: sessionId)
+      let __resultCpp = __result
+      return bridge.create_Result_bool_(__resultCpp)
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_bool_(__exceptionPtr)
+    }
+  }
+  
+  @inline(__always)
+  public final func resume(sessionId: Double) -> bridge.Result_bool_ {
+    do {
+      let __result = try self.__implementation.resume(sessionId: sessionId)
+      let __resultCpp = __result
+      return bridge.create_Result_bool_(__resultCpp)
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_bool_(__exceptionPtr)
+    }
+  }
+  
+  @inline(__always)
+  public final func getSessionState(sessionId: Double) -> bridge.Result_FFmpegSessionState_ {
+    do {
+      let __result = try self.__implementation.getSessionState(sessionId: sessionId)
+      let __resultCpp = __result
+      return bridge.create_Result_FFmpegSessionState_(__resultCpp)
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_FFmpegSessionState_(__exceptionPtr)
+    }
+  }
 }

package/nitrogen/generated/shared/c++/FFmpegSessionState.hpp

@@ -0,0 +1,96 @@
+///
+/// FFmpegSessionState.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::munimffmpeg {
+
+  /**
+   * An enum which can be represented as a JavaScript union (FFmpegSessionState).
+   */
+  enum class FFmpegSessionState {
+    QUEUED      SWIFT_NAME(queued) = 0,
+    RUNNING      SWIFT_NAME(running) = 1,
+    PAUSED      SWIFT_NAME(paused) = 2,
+    COMPLETED      SWIFT_NAME(completed) = 3,
+    FAILED      SWIFT_NAME(failed) = 4,
+    CANCELLED      SWIFT_NAME(cancelled) = 5,
+    UNKNOWN      SWIFT_NAME(unknown) = 6,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::munimffmpeg
+
+namespace margelo::nitro {
+
+  // C++ FFmpegSessionState <> JS FFmpegSessionState (union)
+  template <>
+  struct JSIConverter<margelo::nitro::munimffmpeg::FFmpegSessionState> final {
+    static inline margelo::nitro::munimffmpeg::FFmpegSessionState fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("queued"): return margelo::nitro::munimffmpeg::FFmpegSessionState::QUEUED;
+        case hashString("running"): return margelo::nitro::munimffmpeg::FFmpegSessionState::RUNNING;
+        case hashString("paused"): return margelo::nitro::munimffmpeg::FFmpegSessionState::PAUSED;
+        case hashString("completed"): return margelo::nitro::munimffmpeg::FFmpegSessionState::COMPLETED;
+        case hashString("failed"): return margelo::nitro::munimffmpeg::FFmpegSessionState::FAILED;
+        case hashString("cancelled"): return margelo::nitro::munimffmpeg::FFmpegSessionState::CANCELLED;
+        case hashString("unknown"): return margelo::nitro::munimffmpeg::FFmpegSessionState::UNKNOWN;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum FFmpegSessionState - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::munimffmpeg::FFmpegSessionState arg) {
+      switch (arg) {
+        case margelo::nitro::munimffmpeg::FFmpegSessionState::QUEUED: return JSIConverter<std::string>::toJSI(runtime, "queued");
+        case margelo::nitro::munimffmpeg::FFmpegSessionState::RUNNING: return JSIConverter<std::string>::toJSI(runtime, "running");
+        case margelo::nitro::munimffmpeg::FFmpegSessionState::PAUSED: return JSIConverter<std::string>::toJSI(runtime, "paused");
+        case margelo::nitro::munimffmpeg::FFmpegSessionState::COMPLETED: return JSIConverter<std::string>::toJSI(runtime, "completed");
+        case margelo::nitro::munimffmpeg::FFmpegSessionState::FAILED: return JSIConverter<std::string>::toJSI(runtime, "failed");
+        case margelo::nitro::munimffmpeg::FFmpegSessionState::CANCELLED: return JSIConverter<std::string>::toJSI(runtime, "cancelled");
+        case margelo::nitro::munimffmpeg::FFmpegSessionState::UNKNOWN: return JSIConverter<std::string>::toJSI(runtime, "unknown");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert FFmpegSessionState to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("queued"):
+        case hashString("running"):
+        case hashString("paused"):
+        case hashString("completed"):
+        case hashString("failed"):
+        case hashString("cancelled"):
+        case hashString("unknown"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/HybridMunimFfmpegSpec.cpp

@@ -20,6 +20,9 @@ namespace margelo::nitro::munimffmpeg {
       prototype.registerHybridMethod("getMediaInformation", &HybridMunimFfmpegSpec::getMediaInformation);
       prototype.registerHybridMethod("cancel", &HybridMunimFfmpegSpec::cancel);
       prototype.registerHybridMethod("cancelAll", &HybridMunimFfmpegSpec::cancelAll);
+      prototype.registerHybridMethod("pause", &HybridMunimFfmpegSpec::pause);
+      prototype.registerHybridMethod("resume", &HybridMunimFfmpegSpec::resume);
+      prototype.registerHybridMethod("getSessionState", &HybridMunimFfmpegSpec::getSessionState);
     });
   }
 

package/nitrogen/generated/shared/c++/HybridMunimFfmpegSpec.hpp

@@ -15,6 +15,8 @@
 
 // Forward declaration of `FFmpegSessionResult` to properly resolve imports.
 namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
+// Forward declaration of `FFmpegSessionState` to properly resolve imports.
+namespace margelo::nitro::munimffmpeg { enum class FFmpegSessionState; }
 
 #include <string>
 #include "FFmpegSessionResult.hpp"
@@ -22,6 +24,7 @@ namespace margelo::nitro::munimffmpeg { struct FFmpegSessionResult; }
 #include <vector>
 #include <functional>
 #include <optional>
+#include "FFmpegSessionState.hpp"
 
 namespace margelo::nitro::munimffmpeg {
 
@@ -59,6 +62,9 @@ namespace margelo::nitro::munimffmpeg {
       virtual std::shared_ptr<Promise<std::string>> getMediaInformation(const std::string& path) = 0;
       virtual void cancel(std::optional<double> sessionId) = 0;
       virtual void cancelAll() = 0;
+      virtual bool pause(double sessionId) = 0;
+      virtual bool resume(double sessionId) = 0;
+      virtual FFmpegSessionState getSessionState(double sessionId) = 0;
 
     protected:
       // Hybrid Setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "munim-ffmpeg",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",
@@ -118,7 +118,7 @@
     "nitrogen": "0.36.5",
     "prettier": "^3.8.3",
     "react": "19.2.3",
-    "react-native": "0.86.2",
+    "react-native": "0.86.3",
     "react-native-nitro-modules": "0.36.5",
     "semantic-release": "^25.0.9",
     "typescript": "^6.0.3",

package/scripts/binaries.json

@@ -1,5 +1,5 @@
 {
   "archive": "munim-ffmpeg-binaries.tar.gz",
-  "sha256": "992527af6fd69672cd863501371a835cad6983c45be5525b45a8462848fe7ecc",
-  "ffmpeg": "9.0.1"
+  "sha256": "7f5d42fff137ddf710360c11667c8113fdf1c241b6cbd0e4b5a2e1ba11b152f2",
+  "ffmpeg": "9.0.2"
 }

package/src/index.ts

@@ -3,6 +3,7 @@ import type {
   FFmpegLogCallback,
   FFmpegSessionResult,
   FFmpegSessionCreatedCallback,
+  FFmpegSessionState,
   FFmpegStatisticsCallback,
   MunimFfmpeg as MunimFfmpegSpec,
 } from './specs/MunimFfmpeg.nitro'
@@ -14,6 +15,7 @@ export type {
   FFmpegLogCallback,
   FFmpegSessionResult,
   FFmpegSessionCreatedCallback,
+  FFmpegSessionState,
   FFmpegStatisticsCallback,
   MunimFfmpegSpec,
 }
@@ -177,6 +179,29 @@ export function cancelAll(): void {
   MunimFfmpeg.cancelAll()
 }
 
+/**
+ * Pauses a session started with `execute()`, whether it is running or still
+ * queued. FFmpeg stops reading its inputs and the rest of the pipeline idles
+ * once it has drained, so a paused session costs no CPU. Output files stay
+ * open, and `resume()` continues from exactly where it stopped: nothing is
+ * re-encoded or skipped, and the `execute()` promise settles once, when the
+ * work finishes. `cancel()` still works while paused.
+ *
+ * Returns false if the session is unknown, has finished, or is a probe.
+ */
+export function pause(sessionId: number): boolean {
+  return MunimFfmpeg.pause(sessionId)
+}
+
+/** Resumes a paused session. Returns false if it was not paused. */
+export function resume(sessionId: number): boolean {
+  return MunimFfmpeg.resume(sessionId)
+}
+
+export function getSessionState(sessionId: number): FFmpegSessionState {
+  return MunimFfmpeg.getSessionState(sessionId)
+}
+
 export function getFFmpegVersion(): string {
   return MunimFfmpeg.ffmpegVersion
 }

package/src/specs/MunimFfmpeg.nitro.ts

@@ -11,6 +11,20 @@ export type FFmpegSessionResult = {
   failStackTrace?: string
 }
 
+/**
+ * Where a session is in its life. `queued` sessions wait for the one running
+ * ahead of them (FFmpeg runs one execution at a time); `unknown` means the id
+ * was never issued or its record has been dropped.
+ */
+export type FFmpegSessionState =
+  | 'queued'
+  | 'running'
+  | 'paused'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'unknown'
+
 export type FFmpegLogCallback = (message: string) => void
 
 export type FFmpegSessionCreatedCallback = (sessionId: number) => void
@@ -49,4 +63,16 @@ export interface MunimFfmpeg extends HybridObject<{
   cancel(sessionId?: number): void
 
   cancelAll(): void
+
+  /**
+   * Pauses an `execute()` session, running or still queued. Input stops being
+   * read and the pipeline idles; output files stay open. Returns false if the
+   * session is unknown, finished, or a probe (probes cannot be paused).
+   */
+  pause(sessionId: number): boolean
+
+  /** Resumes a paused session. Returns false if it was not paused. */
+  resume(sessionId: number): boolean
+
+  getSessionState(sessionId: number): FFmpegSessionState
 }