capacitor-native-video-compressor 1.2.0 → 2.1.0

package/README.md

@@ -164,7 +164,7 @@ 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';
+import { NativeVideoCompressor, CANCELLED, STORAGE_FULL, TOO_LARGE_FOR_WEB } from 'capacitor-native-video-compressor';
 
 const jobId = crypto.randomUUID();
 
@@ -179,6 +179,13 @@ try {
     // The user asked for this — no error toast, no retry prompt.
     return;
   }
+  if (error.code === TOO_LARGE_FOR_WEB) {
+    // Web only: WebCodecs is unavailable or failed, and the file is over the 200 MB ffmpeg.wasm limit.
+    // Upload the original, or ask for a shorter clip.
+  }
+  if (error.code === STORAGE_FULL) {
+    // Web only: the browser storage quota is full. Retryable once space is freed.
+  }
   throw error;
 }
 
@@ -205,7 +212,7 @@ 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):
+The `quality` parameter determines the output resolution and compression ratio. Each tier caps the **short** side of the displayed video (the height of a landscape video, the width of a portrait one); the long side follows the aspect ratio. A source smaller than the tier is never upscaled. On Android both sides are rounded to multiples of 16, so 540 becomes 528.
 
 | Preset      | Target Resolution | Best For                                  |
 | ----------- | ----------------- | ----------------------------------------- |
@@ -216,7 +223,7 @@ The `quality` parameter determines the output resolution and compression ratio.
 | `360P`      | ~ 360p            | Very small files                          |
 | `VERY_LOW`  | ~ 240p            | Extreme compression, noticeably pixelated |
 
-> **Note on Web Platform**: On Web, lower qualities also aggressively reduce the Audio Bitrate (down to 48kbps for VERY_LOW) to maximize space savings. On Native, audio maintains steady quality.
+> **Bitrate**: The video bitrate never goes above the source's own bitrate, so a lean source is not inflated; the Web ffmpeg fallback is the exception, as it uses CRF only (iOS and Web WebCodecs allow 1.5× the source for HEVC, VP9 and AV1, which need less than H.264 for the same picture). On Web, the ffmpeg fallback lowers the audio bitrate with the tier (down to 48 kbps for VERY_LOW). On iOS, AAC audio is capped at the source rate and snapped down to 64, 96 or 128 kbps.
 
 ### Platform Differences for `sourcePath`
 
@@ -229,9 +236,9 @@ The `quality` parameter determines the output resolution and compression ratio.
 
 * [`compressVideo(...)`](#compressvideo)
 * [`cancel(...)`](#cancel)
+* [`finishUpload(...)`](#finishupload)
 * [`initialize()`](#initialize)
 * [`addListener('onProgress', ...)`](#addlisteneronprogress-)
-* [`addListener('onCancelRequested', ...)`](#addlisteneroncancelrequested-)
 * [Interfaces](#interfaces)
 
 </docgen-index>
@@ -245,6 +252,16 @@ The `quality` parameter determines the output resolution and compression ratio.
 compressVideo(options: CompressOptions) => Promise<CompressResult>
 ```
 
+Compress one video and resolve with the path of the result.
+
+Android: the work runs inside a WorkManager worker, which keeps the
+process out of the frozen cached state while the user is away — there is
+no foreground service and no notification, because Google Play classes
+this use case as data sync plus local processing and rejects
+`FOREGROUND_SERVICE_MEDIA_PROCESSING` for it. WorkManager stops a worker
+after 10 minutes, so a compress that runs longer rejects with
+{@link CANCELLED}.
+
 | Param         | Type                                                        |
 | ------------- | ----------------------------------------------------------- |
 | **`options`** | <code><a href="#compressoptions">CompressOptions</a></code> |
@@ -276,6 +293,31 @@ thread (native), and none of them watch an AbortSignal.
 --------------------
 
 
+### finishUpload(...)
+
+```typescript
+finishUpload(options: { jobId: string; }) => Promise<{ released: boolean; }>
+```
+
+Release the worker that `holdForUpload` kept alive for this job.
+
+Call it on every terminal branch of the upload, success or failure. A
+missed call leaves the device feeding an idle job until the hold expires.
+`released` is false when no job by that id was still being held, which is
+the normal outcome of a late or duplicate call, not an error.
+
+Web: deletes the compressed output instead, so call it only once the File
+is no longer needed (not before a retry).
+
+| Param         | Type                            |
+| ------------- | ------------------------------- |
+| **`options`** | <code>{ jobId: string; }</code> |
+
+**Returns:** <code>Promise&lt;{ released: boolean; }&gt;</code>
+
+--------------------
+
+
 ### initialize()
 
 ```typescript
@@ -303,29 +345,6 @@ addListener(eventName: 'onProgress', listenerFunc: (info: { status: string; perc
 --------------------
 
 
-### addListener('onCancelRequested', ...)
-
-```typescript
-addListener(eventName: 'onCancelRequested', listenerFunc: () => void) => Promise<PluginListenerHandle>
-```
-
-Android: user đã bấm "Huỷ" trên notification của foreground service.
-
-Pha nén được plugin tự huỷ trước khi event này bắn, nhưng việc caller định
-làm với kết quả nén - upload chẳng hạn - thì không ai dừng hộ được, nên
-caller phải tự abort. Bỏ qua event này nghĩa là nút Huỷ không thật sự huỷ,
-và Play đánh trượt tiêu chí "can be terminated or stopped by the user".
-
-| Param              | Type                             |
-| ------------------ | -------------------------------- |
-| **`eventName`**    | <code>'onCancelRequested'</code> |
-| **`listenerFunc`** | <code>() =&gt; void</code>       |
-
-**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
-
---------------------
-
-
 ### Interfaces
 
 
@@ -339,12 +358,13 @@ và Play đánh trượt tiêu chí "can be terminated or stopped by the user".
 
 #### CompressOptions
 
-| 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. |
+| 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.                                                                                         |
+| **`holdForUpload`** | <code>boolean</code>                                                            | Android only: keep the background worker alive after the compress ends, until `finishUpload({ jobId })` is called. The upload runs as JavaScript in the webview, and the moment the worker returns the process becomes cached and is frozen — measured on Android 16, an in-flight upload dies about five seconds later. Set this whenever the compressed file is about to be uploaded, and always pair it with a `finishUpload` in a `finally`. |
 
 
 #### CancelResult

package/android/build.gradle

@@ -3,6 +3,7 @@ ext {
     androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
     androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    androidxWorkVersion = project.hasProperty('androidxWorkVersion') ? rootProject.ext.androidxWorkVersion : '2.10.0'
 }
 
 buildscript {
@@ -21,10 +22,9 @@ android {
     namespace = "com.atomic.videocompressor"
     compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
     defaultConfig {
-        // 35, không phải 24: foreground service của pha nén khai mediaProcessing,
-        // type chỉ tồn tại từ API 35. Dưới mức đó hệ thống đọc ra "type unknown"
-        // và startForeground() ném InvalidForegroundServiceTypeException.
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 35
+        // 24 trở lại: mức 35 trước đây chỉ để đáp ứng foreground service type
+        // mediaProcessing, thứ đã gỡ hẳn. WorkManager chạy từ API 21.
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
         targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
         versionCode 1
         versionName "1.0"
@@ -60,4 +60,6 @@ dependencies {
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
     implementation 'com.github.AbedElazizShe:LightCompressor:1.3.2'
+    // Giữ process khỏi bị đóng băng trong lúc nén, thay cho foreground service.
+    implementation "androidx.work:work-runtime:$androidxWorkVersion"
 }

package/android/src/main/AndroidManifest.xml

@@ -1,20 +1,11 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
-    <!-- Chỉ mediaProcessing: service sống đúng bằng pha nén, là use case duy
-         nhất ở đây thực sự chạy khi user rời app. Không khai dataSync nữa, vì
-         pha upload chạy bằng JS trong webview nên nó đứng lại ngay khi app
-         xuống nền - giữ foreground service cho nó là khai một việc không diễn
-         ra, và Play xét FGS theo use case chứ không theo số service.
+    <!-- Cố ý rỗng. Google Play xếp "nén rồi upload video do user chọn" vào data
+         sync + local processing chứ không phải media transcoding, nên
+         FOREGROUND_SERVICE_MEDIA_PROCESSING bị từ chối ở version code 32 kèm
+         yêu cầu chuyển sang WorkManager.
 
-         mediaProcessing chỉ có từ API 35, và ở đây không còn type nào để hạ
-         xuống, nên minSdk của plugin là 35 (xem android/build.gradle). -->
-    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROCESSING" />
-    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
-
-    <application>
-        <service
-            android:name="com.atomic.videocompressor.VideoCompressionService"
-            android:foregroundServiceType="mediaProcessing"
-            android:exported="false" />
-    </application>
+         Pha nén giờ chạy trong VideoCompressionWorker, thứ WorkManager tự
+         quản lý - không service nào để khai, và mọi permission plugin từng
+         thêm vào app (FOREGROUND_SERVICE, FOREGROUND_SERVICE_MEDIA_PROCESSING,
+         POST_NOTIFICATIONS) đều đã gỡ. Đừng thêm lại. -->
 </manifest>

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

@@ -1,11 +1,141 @@
 package com.atomic.videocompressor;
 
-import com.getcapacitor.Logger;
+import java.util.regex.Pattern;
 
+/**
+ * Output size, bitrate and leftover-file rules for one compress, kept free of
+ * android.* so they run as plain JVM unit tests. Same ladder as iOS
+ * (NativeVideoCompressorPlugin.swift) and the web QUALITY_LADDER.
+ */
 public class NativeVideoCompressor {
 
-    public String echo(String value) {
-        Logger.info("Echo", value);
-        return value;
+    /**
+     * LightCompressor 1.3.2 getMediaPath copies any source it can't resolve
+     * through MediaStore `_data` (file:// and Photo Picker URIs) to
+     * `dataDir/<System.currentTimeMillis()>` and never deletes it.
+     */
+    private static final Pattern SOURCE_COPY_NAME = Pattern.compile("\\d{13}");
+
+    static boolean isSourceCopyName(String name) {
+        return name != null && SOURCE_COPY_NAME.matcher(name).matches();
+    }
+
+    /**
+     * A copy older than `cutoff` (process start, or "now" on a WebView reload
+     * when every job is orphaned) can't belong to a live job.
+     */
+    static boolean isStaleSourceCopy(String name, long lastModified, long cutoff) {
+        return isSourceCopyName(name) && lastModified < cutoff;
+    }
+
+    /**
+     * Factors LightCompressor 1.3.2 applies to the source bitrate when no
+     * explicit bitrate is given (CompressorUtils.getBitrate), in VideoQuality
+     * order VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH.
+     */
+    static final double[] SOURCE_FACTORS = { 0.1, 0.2, 0.3, 0.4, 0.6 };
+
+    static final class Target {
+
+        final int shortSide;
+        final long bitrate;
+
+        Target(int shortSide, long bitrate) {
+            this.shortSide = shortSide;
+            this.bitrate = bitrate;
+        }
+    }
+
+    static Target target(String quality) {
+        if (quality == null) quality = "MEDIUM";
+        switch (quality) {
+            case "VERY_HIGH":
+                return new Target(1080, 4_500_000);
+            case "HIGH":
+                return new Target(720, 2_500_000);
+            case "LOW":
+                return new Target(480, 1_000_000);
+            case "360P":
+                return new Target(360, 700_000);
+            case "VERY_LOW":
+                return new Target(240, 400_000);
+            default:
+                return new Target(540, 1_500_000);
+        }
+    }
+
+    /**
+     * {width, height} in the track's coded orientation, or null for an empty
+     * track. `shortSide` caps the shorter side and the long side keeps the
+     * aspect ratio. A 90/270 rotation only swaps the sides, and LightCompressor
+     * swaps explicit dimensions itself for those, so coded order is right.
+     * Unlike iOS, both sides are multiples of 16 (so 540 becomes 528). The long
+     * side follows the aligned short side and rounds to the nearest 16, so the
+     * aspect ratio drifts less than flooring each side on its own would.
+     */
+    static int[] outputSize(int width, int height, int shortSide) {
+        int sourceShort = Math.min(width, height);
+        if (sourceShort <= 0) return null;
+        int sourceLong = Math.max(width, height);
+        int outShort = align16(Math.min(shortSide, sourceShort));
+        long nearestLong = Math.round(((double) sourceLong * outShort) / sourceShort / 16) * 16;
+        int outLong = (int) Math.max(16, Math.min(nearestLong, align16(sourceLong)));
+        return width >= height ? new int[] { outLong, outShort } : new int[] { outShort, outLong };
+    }
+
+    // Some MediaTek and older Qualcomm AVC encoders fail configure or draw green
+    // edges off 16-pixel macroblocks; LightCompressor's own sizing aligns for that.
+    // Floor so it never upscales.
+    private static int align16(double value) {
+        return Math.max(16, (int) (value / 16) * 16);
+    }
+
+    static final class BitratePlan {
+
+        /** Whole Mbps for Configuration.videoBitrateInMbps, or null to scale the source instead. */
+        final Integer mbps;
+
+        /** Index into SOURCE_FACTORS when mbps is null. */
+        final int sourceFactorIndex;
+
+        BitratePlan(Integer mbps, int sourceFactorIndex) {
+            this.mbps = mbps;
+            this.sourceFactorIndex = sourceFactorIndex;
+        }
+    }
+
+    /**
+     * LightCompressor 1.3.2 only takes whole Mbps or a fixed fraction of the
+     * source bitrate, so pick whichever lands closest to the target, never
+     * above the source. Null when the source bitrate is unknown.
+     */
+    static BitratePlan bitrate(long target, long source) {
+        if (source <= 0) return null;
+        BitratePlan best = null;
+        long bestDistance = Long.MAX_VALUE;
+        long bestBps = 0;
+
+        // Down to 1, not just floor/ceil of the target: a source below the
+        // target should get the largest whole Mbps it still fits.
+        for (long mbps = target / 1_000_000 + 1; mbps >= 1; mbps--) {
+            long bps = mbps * 1_000_000;
+            if (bps > source) continue;
+            long distance = Math.abs(bps - target);
+            if (distance < bestDistance || (distance == bestDistance && bps < bestBps)) {
+                best = new BitratePlan((int) mbps, -1);
+                bestDistance = distance;
+                bestBps = bps;
+            }
+        }
+        for (int i = 0; i < SOURCE_FACTORS.length; i++) {
+            long bps = Math.round(source * SOURCE_FACTORS[i]);
+            long distance = Math.abs(bps - target);
+            if (distance < bestDistance || (distance == bestDistance && bps < bestBps)) {
+                best = new BitratePlan(null, i);
+                bestDistance = distance;
+                bestBps = bps;
+            }
+        }
+        return best;
     }
 }