capacitor-native-video-compressor 1.1.3 → 2.0.0

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

@@ -1,10 +1,13 @@
 package com.atomic.videocompressor;
 
-import android.content.Intent;
 import android.net.Uri;
 import android.util.Log;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
+import androidx.work.Data;
+import androidx.work.ExistingWorkPolicy;
+import androidx.work.OneTimeWorkRequest;
+import androidx.work.WorkManager;
 import com.abedelazizshe.lightcompressorlibrary.CompressionListener;
 import com.abedelazizshe.lightcompressorlibrary.VideoCompressor;
 import com.abedelazizshe.lightcompressorlibrary.VideoQuality;
@@ -16,13 +19,17 @@ import com.getcapacitor.PluginCall;
 import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
 import java.io.File;
-import java.lang.ref.WeakReference;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
 
 @CapacitorPlugin(name = "NativeVideoCompressor")
 public class NativeVideoCompressorPlugin extends Plugin {
 
+    private static final String TAG = "NativeVideoCompressor";
+
     /**
      * Matches the `CANCELLED` constant the JS side exports, so one
      * `error.code` check covers web, iOS and Android alike.
@@ -32,51 +39,14 @@ public class NativeVideoCompressorPlugin extends Plugin {
     private static final String STORAGE_SUBFOLDER = "compressed_videos";
 
     /**
-     * Instance đang sống, để service gọi ngược khi user bấm "Huỷ" trên
-     * notification. WeakReference vì service sống lâu hơn bridge: giữ cứng ở
-     * đây là giữ luôn cả WebView sau khi Activity đã chết.
+     * Trần cho pha giữ-chờ-upload. Ngắn hơn mốc 10 phút mà WorkManager tự cắt,
+     * để một caller chết giữa chừng không chiếm quota job tới tận phút cuối.
      */
-    private static WeakReference<NativeVideoCompressorPlugin> active = new WeakReference<>(null);
+    private static final long HOLD_FOR_UPLOAD_TIMEOUT_MINUTES = 8;
 
     /** The job compressVideo is running right now, for cancel({ jobId }). */
     private String currentJobId = null;
 
-    @Override
-    public void load() {
-        super.load();
-        active = new WeakReference<>(this);
-    }
-
-    @Override
-    protected void handleOnDestroy() {
-        if (active.get() == this) active = new WeakReference<>(null);
-        super.handleOnDestroy();
-    }
-
-    /**
-     * User bấm "Huỷ" trên notification. Phải huỷ được cả hai pha:
-     *
-     *  - pha nén chạy trong LightCompressor (native) -> cancel() tĩnh, gọi được
-     *    kể cả khi bridge đã chết
-     *  - pha upload chạy trong JS -> chỉ có thể nhờ JS tự dừng, nên bắn
-     *    onCancelRequested; không có event này thì bấm Huỷ lúc đang upload chỉ
-     *    tắt được notification còn request vẫn chạy tiếp, và Play coi như
-     *    "không dừng được bởi user".
-     */
-    static void cancelAllFromNotification() {
-        try {
-            VideoCompressor.cancel();
-        } catch (Exception e) {
-            Log.w("NativeVideoCompressor", "Could not cancel compression", e);
-        }
-        NativeVideoCompressorPlugin plugin = active.get();
-        if (plugin == null) return;
-        synchronized (plugin) {
-            plugin.currentJobId = null;
-        }
-        plugin.notifyListeners("onCancelRequested", new JSObject());
-    }
-
     /**
      * Nothing to do natively; LightCompressor needs no warm-up. Answered
      * rather than left unimplemented so a caller can await it unconditionally
@@ -104,11 +74,15 @@ public class NativeVideoCompressorPlugin extends Plugin {
         // 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.
+        // Both calls are non-blocking (one cancels a coroutine job, the other
+        // returns an Operation), so holding the lock across them costs nothing.
         synchronized (this) {
             cancelled = currentJobId != null && (requested == null || requested.equals(currentJobId));
             if (cancelled) {
+                // Huỷ cả work: pha nén có thể chưa kịp bắt đầu, lúc đó
+                // VideoCompressor.cancel() không có gì để huỷ và work vẫn sẽ
+                // chạy sau đó. Huỷ work làm onStopped bắn và job tự kết thúc.
+                cancelWork(currentJobId);
                 VideoCompressor.cancel();
             }
         }
@@ -117,13 +91,19 @@ public class NativeVideoCompressorPlugin extends Plugin {
         call.resolve(ret);
     }
 
+    /**
+     * Caller báo đã xong việc với kết quả nén - thường là upload xong - nên
+     * worker đang giữ process sống được phép kết thúc.
+     *
+     * Phải gọi trên MỌI nhánh kết thúc của pha upload, kể cả nhánh lỗi. Bỏ sót
+     * một nhánh nghĩa là máy phải nuôi một job rỗng tới khi hết hạn giữ.
+     */
     @PluginMethod
     public void finishUpload(PluginCall call) {
         String jobId = call.getString("jobId");
-        if (jobId != null) {
-            sendToService(VideoCompressionService.ACTION_FINISH, jobId);
-        }
-        call.resolve();
+        JSObject ret = new JSObject();
+        ret.put("released", jobId != null && VideoCompressionWorker.release(jobId));
+        call.resolve(ret);
     }
 
     @PluginMethod
@@ -136,10 +116,6 @@ public class NativeVideoCompressorPlugin extends Plugin {
         }
 
         String jobId = call.getString("jobId", "default");
-        boolean holdForUpload = Boolean.TRUE.equals(call.getBoolean("holdForUpload", false));
-        synchronized (this) {
-            currentJobId = jobId;
-        }
 
         // 1. Chuẩn bị Uri và Tên file xuất ra
         Uri srcUri;
@@ -171,10 +147,7 @@ public class NativeVideoCompressorPlugin extends Plugin {
             }
         }
 
-        Log.d(
-            "NativeVideoCompressor",
-            "====== VIDEO COMPRESSION QUALITY RECEIVED: " + qualityString + "+ video quality: " + videoQuality + " ======"
-        );
+        Log.d(TAG, "====== VIDEO COMPRESSION QUALITY RECEIVED: " + qualityString + "+ video quality: " + videoQuality + " ======");
 
         // 2. Cấu hình thông số nén (Dành riêng cho LightCompressor 1.3.2)
         // Lưu ý: Java phải truyền đủ 9 tham số do thư viện gốc viết bằng Kotlin
@@ -192,38 +165,165 @@ 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(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);
-        serviceIntent.setAction(VideoCompressionService.ACTION_START);
-        serviceIntent.putExtra(VideoCompressionService.EXTRA_JOB_ID, jobId);
+        synchronized (this) {
+            currentJobId = jobId;
+        }
+
+        // 4. Giao pha nén cho WorkManager. Không nén thẳng ở đây: một thread
+        // thường bị đóng băng cùng process ngay khi user rời app, còn process
+        // đang chạy worker thì không. Đây là phương án Google Play chỉ đích
+        // danh khi từ chối foreground service ở version code 32.
+        boolean holdForUpload = Boolean.TRUE.equals(call.getBoolean("holdForUpload", false));
+        CompressionJob job = new CompressionJob(jobId, srcUri, fileName, configuration, storageConfig, call, holdForUpload);
+        VideoCompressionWorker.register(jobId, job);
+
+        OneTimeWorkRequest request = new OneTimeWorkRequest.Builder(VideoCompressionWorker.class)
+            .setInputData(new Data.Builder().putString(VideoCompressionWorker.KEY_JOB_ID, jobId).build())
+            .build();
+
         try {
-            if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
-                getContext().startForegroundService(serviceIntent);
+            WorkManager.getInstance(getContext()).enqueueUniqueWork(workName(jobId), ExistingWorkPolicy.REPLACE, request);
+        } catch (Exception e) {
+            VideoCompressionWorker.unregister(jobId);
+            synchronized (this) {
+                currentJobId = null;
+            }
+            call.reject("Cannot schedule video compression", e);
+        }
+    }
+
+    /**
+     * Một lần nén, chạy bên trong {@link VideoCompressionWorker}.
+     *
+     * Không phải static: nó cần notifyListeners và getContext của plugin đang
+     * sống để bắn progress và trả kết quả về đúng PluginCall.
+     */
+    private final class CompressionJob implements VideoCompressionWorker.Job {
+
+        private final String jobId;
+        private final Uri srcUri;
+        private final String fileName;
+        private final Configuration configuration;
+        private final AppSpecificStorageConfiguration storageConfig;
+        private final PluginCall call;
+        private final boolean holdForUpload;
+
+        /** Mở khi pha nén kết thúc, để worker biết lúc nào được trả về. */
+        private final CountDownLatch done = new CountDownLatch(1);
+
+        /** Mở khi caller gọi finishUpload - chỉ dùng khi holdForUpload. */
+        private final CountDownLatch released = new CountDownLatch(1);
+
+        /** Chốt một-lần cho mọi nhánh kết thúc; PluginCall chỉ được trả lời một lần. */
+        private final AtomicBoolean delivered = new AtomicBoolean(false);
+
+        /** True khi nén xong có kết quả dùng được, tức là có cái để upload. */
+        private volatile boolean compressed = false;
+
+        private boolean started = false;
+        private boolean stopped = false;
+
+        CompressionJob(
+            String jobId,
+            Uri srcUri,
+            String fileName,
+            Configuration configuration,
+            AppSpecificStorageConfiguration storageConfig,
+            PluginCall call,
+            boolean holdForUpload
+        ) {
+            this.jobId = jobId;
+            this.srcUri = srcUri;
+            this.fileName = fileName;
+            this.configuration = configuration;
+            this.storageConfig = storageConfig;
+            this.call = call;
+            this.holdForUpload = holdForUpload;
+        }
+
+        @Override
+        public void run() {
+            synchronized (this) {
+                // stop() đã chạy trước khi worker kịp khởi động: đừng bắt đầu
+                // một lần nén mà không còn ai chờ kết quả.
+                if (!stopped) {
+                    VideoCompressor.start(
+                        getContext(),
+                        Collections.singletonList(srcUri), // Nhận vào một List chứa đường dẫn
+                        false, // isStreamable
+                        null, // sharedStorageConfiguration (Không dùng)
+                        storageConfig, // Cấu hình lưu trữ
+                        configuration, // Cấu hình chất lượng
+                        listener()
+                    );
+                    started = true;
+                }
+            }
+
+            if (!started) {
+                deliverCancelled();
+                return;
+            }
+
+            try {
+                done.await();
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                deliverCancelled();
+                return;
+            }
+
+            // Nén hỏng hoặc bị huỷ thì không có gì để upload - về ngay thay vì
+            // giữ process sống chờ một finishUpload không bao giờ tới.
+            if (!holdForUpload || !compressed) return;
+
+            try {
+                // Có hạn chứ không chờ vô tận: nếu caller chết giữa pha upload
+                // mà không gọi finishUpload, worker sẽ treo tới khi WorkManager
+                // cắt ở phút thứ 10. Về sớm hơn để trả quota job lại cho máy.
+                released.await(HOLD_FOR_UPLOAD_TIMEOUT_MINUTES, TimeUnit.MINUTES);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        }
+
+        @Override
+        public void release() {
+            released.countDown();
+        }
+
+        @Override
+        public void stop() {
+            boolean wasRunning;
+            synchronized (this) {
+                if (stopped) return;
+                stopped = true;
+                wasRunning = started;
+            }
+
+            // Trước mọi thứ khác: worker đang bị cắt, đừng để run() còn ngồi
+            // chờ finishUpload nữa.
+            released.countDown();
+
+            if (wasRunning) {
+                // onCancelled của LightCompressor sẽ mở chốt; không tự gọi
+                // deliverCancelled ở đây để nhánh dọn file tạm vẫn chạy.
+                try {
+                    VideoCompressor.cancel();
+                } catch (Exception e) {
+                    Log.w(TAG, "Could not cancel compression", e);
+                    deliverCancelled();
+                }
             } else {
-                getContext().startService(serviceIntent);
+                // Chưa bắt đầu thì không có callback nào bắn, phải tự kết thúc.
+                deliverCancelled();
             }
-        } catch (Exception e) {
-            synchronized (this) { currentJobId = null; }
-            call.reject("Cannot start foreground video processing", e);
-            return;
         }
 
-        // 4. Bắt đầu nén (Đã cập nhật List Uri và int index)
-        VideoCompressor.start(
-            getContext(),
-            Collections.singletonList(srcUri), // Nhận vào một List chứa đường dẫn
-            false, // isStreamable
-            null, // sharedStorageConfiguration (Không dùng)
-            storageConfig, // Cấu hình lưu trữ
-            configuration, // Cấu hình chất lượng
-            new CompressionListener() {
+        private CompressionListener listener() {
+            return new CompressionListener() {
                 @Override
                 public void onProgress(int i, float v) {
-                    // Notification phải nhúc nhích theo đúng con số mà UI trong
-                    // app đang hiển thị: một notification đứng im là lý do Play
-                    // đánh trượt tiêu chí "user perceptible".
-                    VideoCompressionService.publishProgress(jobId, Math.round(v));
-
                     // Gửi % tiến độ về Javascript để vẽ thanh Progress
                     JSObject ret = new JSObject();
                     ret.put("status", "progress");
@@ -233,13 +333,17 @@ public class NativeVideoCompressorPlugin extends Plugin {
 
                 @Override
                 public void onFailure(int i, @NonNull String failureMessage) {
-                    finishJob(jobId, false);
+                    if (!claim()) return;
                     call.reject("Nén thất bại: " + failureMessage);
                 }
 
                 @Override
                 public void onSuccess(int i, long l, @Nullable String s) {
-                    finishJob(jobId, holdForUpload);
+                    // Phải đặt TRƯỚC claim(): claim() mở chốt `done`, và run()
+                    // đọc `compressed` ngay khi chốt đó mở để quyết định có ở
+                    // lại chờ upload hay không.
+                    compressed = s != null;
+                    if (!claim()) return;
                     // Nén xong, trả kết quả đường dẫn file mới về cho JS
                     JSObject ret = new JSObject();
                     ret.put("success", true);
@@ -256,46 +360,43 @@ public class NativeVideoCompressorPlugin extends Plugin {
 
                 @Override
                 public void onCancelled(int i) {
-                    finishJob(jobId, false);
-                    // 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);
+                    deliverCancelled();
                 }
+            };
+        }
+
+        private void deliverCancelled() {
+            if (!claim()) return;
+            // 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);
+        }
+
+        /** True đúng một lần, cho nhánh kết thúc đầu tiên tới đích. */
+        private boolean claim() {
+            if (!delivered.compareAndSet(false, true)) return false;
+            synchronized (NativeVideoCompressorPlugin.this) {
+                if (jobId.equals(currentJobId)) currentJobId = null;
             }
-        );
+            done.countDown();
+            return true;
+        }
     }
 
-    /** Every terminal callback ends here, so neither is ever left running. */
-    private void finishJob(String jobId, boolean holdForUpload) {
-        sendToService(
-            holdForUpload ? VideoCompressionService.ACTION_UPLOAD : VideoCompressionService.ACTION_FINISH,
-            jobId
-        );
-        synchronized (this) {
-            currentJobId = null;
-        }
+    private String workName(String jobId) {
+        return "video-compression:" + jobId;
     }
 
-    /**
-     * Lệnh gửi vào service, nuốt lỗi có chủ đích.
-     *
-     * startService() từ background bị chặn khi app không còn foreground service
-     * nào chạy - đúng tình huống xảy ra khi service đã tự tắt bằng watchdog rồi
-     * JS mới gọi finishUpload. Ném ra ở đây sẽ biến một lần dọn dẹp vô hại thành
-     * một lần nén báo lỗi cho user.
-     */
-    private void sendToService(String action, String jobId) {
+    /** Best-effort: huỷ một work đã xong là no-op, không đáng để hỏng lời gọi cancel. */
+    private void cancelWork(String jobId) {
         try {
-            Intent intent = new Intent(getContext(), VideoCompressionService.class);
-            intent.setAction(action);
-            intent.putExtra(VideoCompressionService.EXTRA_JOB_ID, jobId);
-            getContext().startService(intent);
+            WorkManager.getInstance(getContext()).cancelUniqueWork(workName(jobId));
         } catch (Exception e) {
-            Log.w("NativeVideoCompressor", "Could not send " + action + " to service", e);
+            Log.w(TAG, "Could not cancel work for " + jobId, e);
         }
     }
 
@@ -308,7 +409,7 @@ public class NativeVideoCompressorPlugin extends Plugin {
                 partial.delete();
             }
         } catch (Exception e) {
-            Log.w("NativeVideoCompressor", "Could not delete cancelled output", e);
+            Log.w(TAG, "Could not delete cancelled output", e);
         }
     }
 }

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

@@ -0,0 +1,120 @@
+package com.atomic.videocompressor;
+
+import android.content.Context;
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import androidx.work.Worker;
+import androidx.work.WorkerParameters;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Giữ pha nén chạy được khi user rời app, không cần foreground service.
+ *
+ * Android 14+ đóng băng process ở trạng thái cached, nên nén bằng một thread
+ * thường sẽ đứng lại ngay khi user chuyển app. Foreground service từng là cách
+ * giữ nó sống, nhưng Google Play từ chối version code 32: use case này được xếp
+ * vào data sync + local processing, không đủ điều kiện cho
+ * FOREGROUND_SERVICE_MEDIA_PROCESSING, và họ chỉ đích danh WorkManager làm
+ * phương án thay thế. Process đang chạy một worker thì không bị đóng băng.
+ *
+ * Worker chỉ là vỏ bọc: việc nén thật do plugin đăng ký qua {@link #register}
+ * ngay trước khi enqueue, vì chỉ plugin mới giữ được PluginCall để trả kết quả.
+ *
+ * Với `holdForUpload`, worker ở lại sau khi nén xong cho tới khi caller gọi
+ * `finishUpload`. Pha upload chạy bằng JS trong webview, và khoảnh khắc worker
+ * kết thúc là khoảnh khắc process thành cached rồi bị đóng băng - đo trên
+ * Android 16: upload chết đúng ~5 giây sau khi worker trả về. Giữ worker sống
+ * xuyên pha upload là cách duy nhất còn lại để nó sống sót, vì foreground
+ * service đã bị Play cấm cho use case này.
+ *
+ * Giới hạn phải biết: WorkManager dừng worker sau 10 phút, tính chung cả nén
+ * lẫn upload. Quá mức đó {@link #onStopped()} huỷ việc đang chạy và caller
+ * nhận lỗi CANCELLED - đổi lại lấy được nhiều thời gian hơn thì phải có
+ * foreground service, thứ không còn được phép ở đây.
+ */
+public class VideoCompressionWorker extends Worker {
+
+    static final String KEY_JOB_ID = "jobId";
+
+    /**
+     * Việc nén do plugin đăng ký, tra theo jobId.
+     *
+     * Static vì worker được WorkManager dựng mới, không nhận được tham chiếu
+     * nào từ phía plugin. Map chỉ có nghĩa trong phạm vi một process: process
+     * chết là WebView chết, không còn ai nhận kết quả nén nữa.
+     */
+    private static final Map<String, Job> pending = new ConcurrentHashMap<>();
+
+    interface Job {
+        /**
+         * Chạy pha nén, và với holdForUpload thì ở lại tới khi caller gọi
+         * finishUpload. Chỉ trả về khi không còn gì phải giữ process sống.
+         */
+        void run();
+
+        /** WorkManager đòi dừng - hết 10 phút, hoặc work bị cancel. */
+        void stop();
+
+        /** Caller báo đã upload xong; worker được phép kết thúc. */
+        void release();
+    }
+
+    static void register(String jobId, Job job) {
+        pending.put(jobId, job);
+    }
+
+    static void unregister(String jobId) {
+        pending.remove(jobId);
+    }
+
+    /**
+     * Thả worker đang giữ process sống cho pha upload của jobId.
+     *
+     * False khi không còn job nào mang id đó - worker đã kết thúc từ trước,
+     * không có gì để thả. Đó là trạng thái bình thường, không phải lỗi.
+     */
+    static boolean release(String jobId) {
+        Job job = pending.get(jobId);
+        if (job == null) return false;
+        job.release();
+        return true;
+    }
+
+    @Nullable
+    private volatile Job running = null;
+
+    public VideoCompressionWorker(@NonNull Context context, @NonNull WorkerParameters params) {
+        super(context, params);
+    }
+
+    @NonNull
+    @Override
+    public Result doWork() {
+        String jobId = getInputData().getString(KEY_JOB_ID);
+        if (jobId == null) return Result.success();
+
+        Job job = pending.get(jobId);
+        // Không còn job: process đã bị kill và WorkManager dựng lại worker ở
+        // process mới. WebView đã chết cùng nó nên không còn ai nhận kết quả -
+        // chạy lại pha nén chỉ tốn pin. Success chứ không retry, để WorkManager
+        // bỏ hẳn work này đi.
+        if (job == null) return Result.success();
+
+        running = job;
+        try {
+            job.run();
+        } finally {
+            running = null;
+            pending.remove(jobId);
+        }
+        return Result.success();
+    }
+
+    @Override
+    public void onStopped() {
+        Job job = running;
+        if (job != null) job.stop();
+        super.onStopped();
+    }
+}

package/dist/docs.json

@@ -17,7 +17,7 @@
         ],
         "returns": "Promise<CompressResult>",
         "tags": [],
-        "docs": "",
+        "docs": "Compress one video and resolve with the path of the result.\n\nAndroid: the work runs inside a WorkManager worker, which keeps the\nprocess out of the frozen cached state while the user is away — there is\nno foreground service and no notification, because Google Play classes\nthis use case as data sync plus local processing and rejects\n`FOREGROUND_SERVICE_MEDIA_PROCESSING` for it. WorkManager stops a worker\nafter 10 minutes, so a compress that runs longer rejects with\n{@link CANCELLED}.",
         "complexTypes": [
           "CompressResult",
           "CompressOptions"
@@ -43,19 +43,9 @@
         ],
         "slug": "cancel"
       },
-      {
-        "name": "initialize",
-        "signature": "() => Promise<{ success: boolean; message?: string; }>",
-        "parameters": [],
-        "returns": "Promise<{ success: boolean; message?: string | undefined; }>",
-        "tags": [],
-        "docs": "",
-        "complexTypes": [],
-        "slug": "initialize"
-      },
       {
         "name": "finishUpload",
-        "signature": "(options: { jobId: string; }) => Promise<void>",
+        "signature": "(options: { jobId: string; }) => Promise<{ released: boolean; }>",
         "parameters": [
           {
             "name": "options",
@@ -63,12 +53,22 @@
             "type": "{ jobId: string; }"
           }
         ],
-        "returns": "Promise<void>",
+        "returns": "Promise<{ released: boolean; }>",
         "tags": [],
-        "docs": "Báo rằng phần upload đi kèm `holdForUpload` đã xong (thành công hay thất\nbại đều phải gọi) để Android hạ foreground service xuống.\n\nNo-op trên web và iOS.",
+        "docs": "Release the worker that `holdForUpload` kept alive for this job.\n\nCall it on every terminal branch of the upload, success or failure. A\nmissed call leaves the device feeding an idle job until the hold expires.\n`released` is false when no job by that id was still being held, which is\nthe normal outcome of a late or duplicate call, not an error.",
         "complexTypes": [],
         "slug": "finishupload"
       },
+      {
+        "name": "initialize",
+        "signature": "() => Promise<{ success: boolean; message?: string; }>",
+        "parameters": [],
+        "returns": "Promise<{ success: boolean; message?: string | undefined; }>",
+        "tags": [],
+        "docs": "",
+        "complexTypes": [],
+        "slug": "initialize"
+      },
       {
         "name": "addListener",
         "signature": "(eventName: 'onProgress', listenerFunc: (info: { status: string; percent?: number; }) => void) => Promise<PluginListenerHandle>",
@@ -91,29 +91,6 @@
           "PluginListenerHandle"
         ],
         "slug": "addlisteneronprogress-"
-      },
-      {
-        "name": "addListener",
-        "signature": "(eventName: 'onCancelRequested', listenerFunc: () => void) => Promise<PluginListenerHandle>",
-        "parameters": [
-          {
-            "name": "eventName",
-            "docs": "",
-            "type": "'onCancelRequested'"
-          },
-          {
-            "name": "listenerFunc",
-            "docs": "",
-            "type": "() => void"
-          }
-        ],
-        "returns": "Promise<PluginListenerHandle>",
-        "tags": [],
-        "docs": "Android: user đã bấm \"Huỷ\" trên notification của foreground service.\n\nPha nén được plugin tự huỷ trước khi event này bắn, nhưng pha upload chạy\ntrong JS nên không ai dừng hộ được - caller phải tự abort request đang\nchạy. Bỏ qua event này nghĩa là nút Huỷ không thật sự huỷ, và Play đánh\ntrượt tiêu chí \"can be terminated or stopped by the user\".",
-        "complexTypes": [
-          "PluginListenerHandle"
-        ],
-        "slug": "addlisteneroncancelrequested-"
       }
     ],
     "properties": []
@@ -180,7 +157,7 @@
         {
           "name": "holdForUpload",
           "tags": [],
-          "docs": "Android: giữ foreground service sống sau khi nén xong, để phần upload do\nJS chạy tiếp theo không bị hệ thống giết khi user rời app.\n\nBật cờ này là một lời hứa: caller PHẢI gọi {@link NativeVideoCompressorPlugin.finishUpload}\nkhi upload kết thúc, kể cả ở nhánh lỗi. Không gọi thì service chỉ còn\nwatchdog dọn hộ sau 15 phút, và trong 15 phút đó user nhìn thấy một\nnotification nói rằng app đang làm việc trong khi nó không làm gì cả.\n\nKhông có tác dụng trên web và iOS.",
+          "docs": "Android only: keep the background worker alive after the compress ends,\nuntil `finishUpload({ jobId })` is called.\n\nThe upload runs as JavaScript in the webview, and the moment the worker\nreturns the process becomes cached and is frozen — measured on Android 16,\nan in-flight upload dies about five seconds later. Set this whenever the\ncompressed file is about to be uploaded, and always pair it with a\n`finishUpload` in a `finally`.",
           "complexTypes": [],
           "type": "boolean | undefined"
         }