capacitor-native-video-compressor 1.0.4 → 1.1.0

package/README.md

@@ -124,6 +124,51 @@ try {
 listener.remove();
 ```
 
+### 3. Cancelling a Compression
+
+Compressing a long video runs for minutes, so give the user a way out. Pass a
+`jobId` when starting, then cancel with the same id:
+
+```typescript
+import { NativeVideoCompressor, CANCELLED } from 'capacitor-native-video-compressor';
+
+const jobId = crypto.randomUUID();
+
+try {
+  const result = await NativeVideoCompressor.compressVideo({
+    sourcePath: '/path/to/video.mp4',
+    quality: 'HIGH',
+    jobId,
+  });
+} catch (error) {
+  if (error.code === CANCELLED) {
+    // The user asked for this — no error toast, no retry prompt.
+    return;
+  }
+  throw error;
+}
+
+// From a Cancel button, anywhere:
+await NativeVideoCompressor.cancel({ jobId });
+```
+
+**Why `jobId`.** Every platform compresses one video at a time, so cancellation
+is global by nature. Two independent queues in the same app (say comments and
+notes) would otherwise cancel each other's work. `cancel()` with no `jobId`
+cancels whatever is running, whoever started it — fine when there is only one
+caller.
+
+**What it costs.** The partial output is deleted on every platform. On web,
+cancelling terminates the FFmpeg worker, because `ffmpeg.exec()` runs as
+synchronous WASM inside it and never reaches a message poll while encoding —
+the `AbortSignal` `exec()` accepts only rejects the main-thread promise while
+the encode keeps burning CPU behind it. The loaded core is dropped with the
+worker, but the core URLs are cached in module scope, so the next compress
+re-instantiates without re-downloading the wasm.
+
+`cancel()` resolves `{ cancelled: false }` when nothing was running, or when a
+different job was — it never throws.
+
 ### Quality Presets
 
 The `quality` parameter determines the output resolution and compression ratio. Depending on the original aspect ratio, the video will be scaled to match the following heights (or widths, preserving aspect ratio):
@@ -149,6 +194,7 @@ The `quality` parameter determines the output resolution and compression ratio.
 <docgen-index>
 
 * [`compressVideo(...)`](#compressvideo)
+* [`cancel(...)`](#cancel)
 * [`initialize()`](#initialize)
 * [`addListener('onProgress', ...)`](#addlisteneronprogress-)
 * [Interfaces](#interfaces)
@@ -173,6 +219,28 @@ compressVideo(options: CompressOptions) => Promise<CompressResult>
 --------------------
 
 
+### cancel(...)
+
+```typescript
+cancel(options?: CancelOptions | undefined) => Promise<CancelResult>
+```
+
+Stop the compress that is running now. `compressVideo` then rejects with
+code {@link CANCELLED} and its partial output is deleted.
+
+This is the only way to stop one: the work is synchronous WASM inside a
+web worker (web) or an AVFoundation / LightCompressor pass on its own
+thread (native), and none of them watch an AbortSignal.
+
+| Param         | Type                                                    |
+| ------------- | ------------------------------------------------------- |
+| **`options`** | <code><a href="#canceloptions">CancelOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#cancelresult">CancelResult</a>&gt;</code>
+
+--------------------
+
+
 ### initialize()
 
 ```typescript
@@ -213,11 +281,26 @@ addListener(eventName: 'onProgress', listenerFunc: (info: { status: string; perc
 
 #### CompressOptions
 
-| Prop             | Type                                                                            |
-| ---------------- | ------------------------------------------------------------------------------- |
-| **`sourcePath`** | <code>string</code>                                                             |
-| **`destPath`**   | <code>string</code>                                                             |
-| **`quality`**    | <code>'VERY_HIGH' \| 'HIGH' \| 'MEDIUM' \| 'LOW' \| 'VERY_LOW' \| '360P'</code> |
+| Prop             | Type                                                                            | Description                                                                                                                                                                                                                                                                                                                                              |
+| ---------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`sourcePath`** | <code>string</code>                                                             |                                                                                                                                                                                                                                                                                                                                                          |
+| **`destPath`**   | <code>string</code>                                                             |                                                                                                                                                                                                                                                                                                                                                          |
+| **`quality`**    | <code>'VERY_HIGH' \| 'HIGH' \| 'MEDIUM' \| 'LOW' \| 'VERY_LOW' \| '360P'</code> |                                                                                                                                                                                                                                                                                                                                                          |
+| **`jobId`**      | <code>string</code>                                                             | Names this compress so `cancel({ jobId })` can target it. Every platform compresses one video at a time, so cancellation is global by nature. Two independent callers in the same app (say a comment queue and a notes queue) therefore need a way to say *which* job they mean — without one, a cancel from either kills whatever the other is running. |
+
+
+#### CancelResult
+
+| Prop            | Type                 | Description                                                  |
+| --------------- | -------------------- | ------------------------------------------------------------ |
+| **`cancelled`** | <code>boolean</code> | False when nothing was running, or when a different job was. |
+
+
+#### CancelOptions
+
+| Prop        | Type                | Description                                                                                               |
+| ----------- | ------------------- | --------------------------------------------------------------------------------------------------------- |
+| **`jobId`** | <code>string</code> | Only cancel if this is the job currently running. Omit to cancel whatever is running, whoever started it. |
 
 
 #### PluginListenerHandle

package/android/src/main/java/com/atomic/videocompressor/NativeVideoCompressorPlugin.java

@@ -22,6 +22,57 @@ import java.util.Collections;
 @CapacitorPlugin(name = "NativeVideoCompressor")
 public class NativeVideoCompressorPlugin extends Plugin {
 
+    /**
+     * Matches the `CANCELLED` constant the JS side exports, so one
+     * `error.code` check covers web, iOS and Android alike.
+     */
+    private static final String CANCELLED_CODE = "CANCELLED";
+
+    private static final String STORAGE_SUBFOLDER = "compressed_videos";
+
+    /** The job compressVideo is running right now, for cancel({ jobId }). */
+    private String currentJobId = null;
+
+    /**
+     * Nothing to do natively; LightCompressor needs no warm-up. Answered
+     * rather than left unimplemented so a caller can await it unconditionally
+     * (the web build does need it, and shares the call site).
+     */
+    @PluginMethod
+    public void initialize(PluginCall call) {
+        JSObject ret = new JSObject();
+        ret.put("success", true);
+        ret.put("message", "No initialization needed on Android");
+        call.resolve(ret);
+    }
+
+    /**
+     * Stop the running compress. LightCompressor cancels its coroutine job and
+     * fires onCancelled, which is already wired below.
+     */
+    @PluginMethod
+    public void cancel(PluginCall call) {
+        String requested = call.getString("jobId");
+        JSObject ret = new JSObject();
+        boolean cancelled;
+
+        // The cancel call itself must be INSIDE the lock. Released first, the
+        // running job could finish and a new one start in the gap — and
+        // VideoCompressor.cancel() being global, it would kill the newcomer.
+        // That is exactly what checking the jobId is meant to prevent.
+        // The call is non-blocking (it cancels a coroutine job), so holding
+        // the lock across it costs nothing.
+        synchronized (this) {
+            cancelled = currentJobId != null && (requested == null || requested.equals(currentJobId));
+            if (cancelled) {
+                VideoCompressor.cancel();
+            }
+        }
+
+        ret.put("cancelled", cancelled);
+        call.resolve(ret);
+    }
+
     @PluginMethod
     public void compressVideo(PluginCall call) {
         String sourcePath = call.getString("sourcePath");
@@ -31,6 +82,11 @@ public class NativeVideoCompressorPlugin extends Plugin {
             return;
         }
 
+        String jobId = call.getString("jobId", "default");
+        synchronized (this) {
+            currentJobId = jobId;
+        }
+
         // 1. Chuẩn bị Uri và Tên file xuất ra
         Uri srcUri;
         String fileName = "compressed_" + System.currentTimeMillis() + ".mp4";
@@ -80,7 +136,7 @@ public class NativeVideoCompressorPlugin extends Plugin {
         );
 
         // 3. Cấu hình nơi lưu (Lưu an toàn vào thư mục nội bộ của App)
-        AppSpecificStorageConfiguration storageConfig = new AppSpecificStorageConfiguration("compressed_videos");
+        AppSpecificStorageConfiguration storageConfig = new AppSpecificStorageConfiguration(STORAGE_SUBFOLDER);
 
         // Khởi động Foreground Service để giữ app luôn sống khi chạy ngầm
         Intent serviceIntent = new Intent(getContext(), VideoCompressionService.class);
@@ -114,13 +170,13 @@ public class NativeVideoCompressorPlugin extends Plugin {
 
                 @Override
                 public void onFailure(int i, @NonNull String failureMessage) {
-                    getContext().stopService(serviceIntent);
+                    finishJob(serviceIntent);
                     call.reject("Nén thất bại: " + failureMessage);
                 }
 
                 @Override
                 public void onSuccess(int i, long l, @Nullable String s) {
-                    getContext().stopService(serviceIntent);
+                    finishJob(serviceIntent);
                     // Nén xong, trả kết quả đường dẫn file mới về cho JS
                     JSObject ret = new JSObject();
                     ret.put("success", true);
@@ -137,10 +193,37 @@ public class NativeVideoCompressorPlugin extends Plugin {
 
                 @Override
                 public void onCancelled(int i) {
-                    getContext().stopService(serviceIntent);
-                    call.reject("Đã hủy nén");
+                    finishJob(serviceIntent);
+                    // LightCompressor leaves whatever it had already written
+                    // behind; without this the cache keeps a partial mp4 per
+                    // cancel, and nothing ever collects them.
+                    deleteOutput(fileName);
+                    // Coded so the caller can tell "the user asked for this"
+                    // apart from a real failure — same code on every platform.
+                    call.reject("Đã hủy nén", CANCELLED_CODE);
                 }
             }
         );
     }
+
+    /** Every terminal callback ends here, so neither is ever left running. */
+    private void finishJob(Intent serviceIntent) {
+        getContext().stopService(serviceIntent);
+        synchronized (this) {
+            currentJobId = null;
+        }
+    }
+
+    /** Best-effort: a partial file left in the cache is not worth failing over. */
+    private void deleteOutput(String fileName) {
+        try {
+            File dir = new File(getContext().getExternalFilesDir(null), STORAGE_SUBFOLDER);
+            File partial = new File(dir, fileName);
+            if (partial.exists()) {
+                partial.delete();
+            }
+        } catch (Exception e) {
+            Log.w("NativeVideoCompressor", "Could not delete cancelled output", e);
+        }
+    }
 }

package/dist/docs.json

@@ -24,6 +24,25 @@
         ],
         "slug": "compressvideo"
       },
+      {
+        "name": "cancel",
+        "signature": "(options?: CancelOptions | undefined) => Promise<CancelResult>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "",
+            "type": "CancelOptions | undefined"
+          }
+        ],
+        "returns": "Promise<CancelResult>",
+        "tags": [],
+        "docs": "Stop the compress that is running now. `compressVideo` then rejects with\ncode {@link CANCELLED} and its partial output is deleted.\n\nThis is the only way to stop one: the work is synchronous WASM inside a\nweb worker (web) or an AVFoundation / LightCompressor pass on its own\nthread (native), and none of them watch an AbortSignal.",
+        "complexTypes": [
+          "CancelResult",
+          "CancelOptions"
+        ],
+        "slug": "cancel"
+      },
       {
         "name": "initialize",
         "signature": "() => Promise<{ success: boolean; message?: string; }>",
@@ -111,6 +130,45 @@
           "docs": "",
           "complexTypes": [],
           "type": "'VERY_HIGH' | 'HIGH' | 'MEDIUM' | 'LOW' | 'VERY_LOW' | '360P' | undefined"
+        },
+        {
+          "name": "jobId",
+          "tags": [],
+          "docs": "Names this compress so `cancel({ jobId })` can target it.\n\nEvery platform compresses one video at a time, so cancellation is global\nby nature. Two independent callers in the same app (say a comment queue\nand a notes queue) therefore need a way to say *which* job they mean —\nwithout one, a cancel from either kills whatever the other is running.",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
+    {
+      "name": "CancelResult",
+      "slug": "cancelresult",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "cancelled",
+          "tags": [],
+          "docs": "False when nothing was running, or when a different job was.",
+          "complexTypes": [],
+          "type": "boolean"
+        }
+      ]
+    },
+    {
+      "name": "CancelOptions",
+      "slug": "canceloptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "jobId",
+          "tags": [],
+          "docs": "Only cancel if this is the job currently running. Omit to cancel whatever\nis running, whoever started it.",
+          "complexTypes": [],
+          "type": "string | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -1,15 +1,50 @@
 import type { PluginListenerHandle } from '@capacitor/core';
+/**
+ * `code` on the error `compressVideo` rejects with when `cancel()` stopped it.
+ * Callers should treat it as "the user asked for this" — no error toast, no
+ * retry prompt — and tell it apart from a genuine compression failure.
+ */
+export declare const CANCELLED = "CANCELLED";
 export interface CompressOptions {
     sourcePath: string;
     destPath?: string;
     quality?: 'VERY_HIGH' | 'HIGH' | 'MEDIUM' | 'LOW' | 'VERY_LOW' | '360P';
+    /**
+     * Names this compress so `cancel({ jobId })` can target it.
+     *
+     * Every platform compresses one video at a time, so cancellation is global
+     * by nature. Two independent callers in the same app (say a comment queue
+     * and a notes queue) therefore need a way to say *which* job they mean —
+     * without one, a cancel from either kills whatever the other is running.
+     */
+    jobId?: string;
 }
 export interface CompressResult {
     success: boolean;
     destPath: string;
 }
+export interface CancelOptions {
+    /**
+     * Only cancel if this is the job currently running. Omit to cancel whatever
+     * is running, whoever started it.
+     */
+    jobId?: string;
+}
+export interface CancelResult {
+    /** False when nothing was running, or when a different job was. */
+    cancelled: boolean;
+}
 export interface NativeVideoCompressorPlugin {
     compressVideo(options: CompressOptions): Promise<CompressResult>;
+    /**
+     * Stop the compress that is running now. `compressVideo` then rejects with
+     * code {@link CANCELLED} and its partial output is deleted.
+     *
+     * This is the only way to stop one: the work is synchronous WASM inside a
+     * web worker (web) or an AVFoundation / LightCompressor pass on its own
+     * thread (native), and none of them watch an AbortSignal.
+     */
+    cancel(options?: CancelOptions): Promise<CancelResult>;
     initialize(): Promise<{
         success: boolean;
         message?: string;

package/dist/esm/definitions.js

@@ -1,2 +1,7 @@
-export {};
+/**
+ * `code` on the error `compressVideo` rejects with when `cancel()` stopped it.
+ * Callers should treat it as "the user asked for this" — no error toast, no
+ * retry prompt — and tell it apart from a genuine compression failure.
+ */
+export const CANCELLED = 'CANCELLED';
 //# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\nexport interface CompressOptions {\n  sourcePath: string;\n  destPath?: string;\n  quality?: 'VERY_HIGH' | 'HIGH' | 'MEDIUM' | 'LOW' | 'VERY_LOW' | '360P';\n}\n\nexport interface CompressResult {\n  success: boolean;\n  destPath: string;\n}\n\nexport interface NativeVideoCompressorPlugin {\n  compressVideo(options: CompressOptions): Promise<CompressResult>;\n\n  initialize(): Promise<{ success: boolean; message?: string }>;\n\n  // Đã sửa lại chuẩn cho Capacitor mới nhất (chỉ trả về Promise)\n  addListener(\n    eventName: 'onProgress',\n    listenerFunc: (info: { status: string; percent?: number }) => void,\n  ): Promise<PluginListenerHandle>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\n/**\n * `code` on the error `compressVideo` rejects with when `cancel()` stopped it.\n * Callers should treat it as \"the user asked for this\" — no error toast, no\n * retry prompt — and tell it apart from a genuine compression failure.\n */\nexport const CANCELLED = 'CANCELLED';\n\nexport interface CompressOptions {\n  sourcePath: string;\n  destPath?: string;\n  quality?: 'VERY_HIGH' | 'HIGH' | 'MEDIUM' | 'LOW' | 'VERY_LOW' | '360P';\n  /**\n   * Names this compress so `cancel({ jobId })` can target it.\n   *\n   * Every platform compresses one video at a time, so cancellation is global\n   * by nature. Two independent callers in the same app (say a comment queue\n   * and a notes queue) therefore need a way to say *which* job they mean —\n   * without one, a cancel from either kills whatever the other is running.\n   */\n  jobId?: string;\n}\n\nexport interface CompressResult {\n  success: boolean;\n  destPath: string;\n}\n\nexport interface CancelOptions {\n  /**\n   * Only cancel if this is the job currently running. Omit to cancel whatever\n   * is running, whoever started it.\n   */\n  jobId?: string;\n}\n\nexport interface CancelResult {\n  /** False when nothing was running, or when a different job was. */\n  cancelled: boolean;\n}\n\nexport interface NativeVideoCompressorPlugin {\n  compressVideo(options: CompressOptions): Promise<CompressResult>;\n\n  /**\n   * Stop the compress that is running now. `compressVideo` then rejects with\n   * code {@link CANCELLED} and its partial output is deleted.\n   *\n   * This is the only way to stop one: the work is synchronous WASM inside a\n   * web worker (web) or an AVFoundation / LightCompressor pass on its own\n   * thread (native), and none of them watch an AbortSignal.\n   */\n  cancel(options?: CancelOptions): Promise<CancelResult>;\n\n  initialize(): Promise<{ success: boolean; message?: string }>;\n\n  // Đã sửa lại chuẩn cho Capacitor mới nhất (chỉ trả về Promise)\n  addListener(\n    eventName: 'onProgress',\n    listenerFunc: (info: { status: string; percent?: number }) => void,\n  ): Promise<PluginListenerHandle>;\n}\n"]}

package/dist/esm/web.d.ts

@@ -1,12 +1,33 @@
 import { WebPlugin } from '@capacitor/core';
-import type { NativeVideoCompressorPlugin, CompressOptions, CompressResult } from './definitions';
+import type { NativeVideoCompressorPlugin, CompressOptions, CompressResult, CancelOptions, CancelResult } from './definitions';
 export declare class NativeVideoCompressorWeb extends WebPlugin implements NativeVideoCompressorPlugin {
     private ffmpeg;
     private isLoaded;
-    private loadFFmpeg;
+    /** The mediabunny conversion running now, so `cancel()` can abort it. */
+    private activeConversion;
+    /** The job `compressVideo` is running right now, for `cancel({ jobId })`. */
+    private currentJobId;
+    private cancelRequested;
     initialize(): Promise<{
         success: boolean;
         message?: string;
     }>;
     compressVideo(options: CompressOptions): Promise<CompressResult>;
+    /**
+     * Kill whichever engine is mid-compress. Only one is ever active at a time,
+     * so acting on both is safe.
+     *
+     * WebCodecs: `conversion.cancel()` makes the in-flight `execute()` reject
+     * with `ConversionCanceledError`, surfaced as a `CancelledError` below.
+     * ffmpeg: `exec()` runs synchronously inside the worker and never reaches a
+     * message poll while encoding, so `worker.terminate()` is the only way to
+     * stop it — its cost is the loaded core, which is why the core URLs are
+     * cached above.
+     */
+    cancel(options?: CancelOptions): Promise<CancelResult>;
+    private fetchSourceBlob;
+    private canUseWebCodecs;
+    private compressWithWebCodecs;
+    private loadFFmpeg;
+    private compressWithFfmpeg;
 }