munim-ffmpeg 0.7.1 → 0.8.0

package/README.md

@@ -100,6 +100,7 @@
 - 📈 **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                       |
@@ -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.

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.1",
+  "version": "0.8.0",
   "description": "Fast FFmpeg and FFprobe for Expo and React Native, powered by Nitro Modules",
   "main": "lib/index",
   "module": "lib/index",

package/scripts/binaries.json

@@ -1,5 +1,5 @@
 {
   "archive": "munim-ffmpeg-binaries.tar.gz",
-  "sha256": "6d709ca6ddf428743c29d54325cca34c3335d771076690472bb036c2d849e64f",
+  "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
 }