capacitor-video-transcoder 0.0.0-stage → 0.0.1

package/CapacitorVideoTranscoder.podspec

@@ -0,0 +1,18 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapacitorVideoTranscoder'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.frameworks = 'AVFoundation', 'CoreMedia', 'CoreVideo'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+end

package/Package.swift

@@ -0,0 +1,39 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+// The plugin is two modules: VideoTranscoderCore, the transcoder itself on AVFoundation alone, and VideoTranscoderPlugin, the
+// Capacitor bridge to it. The core has a package of its own as well, ios/Package.swift, so that its tests run with `swift test`
+// on a Mac, where the bridge (which needs UIKit through Capacitor) does not build.
+let package = Package(
+    name: "CapacitorVideoTranscoder",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "CapacitorVideoTranscoder",
+            targets: ["VideoTranscoderPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "VideoTranscoderCore",
+            path: "ios/Sources/VideoTranscoderCore"),
+        .target(
+            name: "VideoTranscoderPlugin",
+            dependencies: [
+                "VideoTranscoderCore",
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/VideoTranscoderPlugin"),
+        .testTarget(
+            name: "VideoTranscoderCoreTests",
+            dependencies: ["VideoTranscoderCore"],
+            path: "ios/Tests/VideoTranscoderCoreTests"),
+        .testTarget(
+            name: "VideoTranscoderPluginTests",
+            dependencies: ["VideoTranscoderPlugin", "VideoTranscoderCore"],
+            path: "ios/Tests/VideoTranscoderPluginTests")
+    ]
+)

package/README.md

@@ -1,3 +1,239 @@
-# Temporary Holding Version
+# capacitor-video-transcoder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turn a video from the phone's camera or gallery into an MP4 that every web browser plays, on iOS and Android, from a Capacitor app.
+
+A phone records what suits the phone: HEVC, often 10-bit HDR, 4K, in a `.mov` on iOS. A browser on another computer may play none
+of that. This plugin writes a small, plain MP4 instead, with the platform's own hardware encoder: AVFoundation on iOS, Media3
+Transformer on Android. No FFmpeg, nothing to license, nothing large added to the app.
+
+What comes out:
+
+- H.264 video, High profile where the encoder offers it, 8-bit 4:2:0, tagged BT.709
+- an HDR source (HLG or PQ) tone-mapped to SDR, so it does not look washed out
+- AAC audio: an AAC track is copied as it is, anything else is encoded, keeping mono as mono and stereo as stereo
+- the longer side at most `maxSize` (1280 by default), the aspect ratio kept, both sides even
+- cut at `maxDurationMs` (30 seconds by default)
+- `moov` before `mdat` ("faststart"), so playback starts before the whole file has downloaded
+- a portrait video stored the way the phone stored it, with its rotation as track metadata, so players show it upright
+- a video bitrate you choose (1.8 Mbit/s by default)
+
+## Install
+
+```bash
+npm install capacitor-video-transcoder
+npx cap sync
+```
+
+Requires Capacitor 8. Android 8.0 (API 26) or newer, iOS 15 or newer. On iOS the plugin is a Swift package; CocoaPods works too.
+Android adds [Media3 Transformer](https://developer.android.com/media/media3/transformer); iOS uses system frameworks only.
+
+## Use
+
+```typescript
+import { VideoTranscoder } from 'capacitor-video-transcoder';
+
+const progress = await VideoTranscoder.addListener('progress', ({ progress }) => {
+  console.log(`${Math.round(progress * 100)}%`);
+});
+try {
+  const video = await VideoTranscoder.transcode({ source: picked.path });
+  // video.path is an MP4 in the cache directory: upload it, then delete it
+  console.log(video.width, video.height, video.durationMs, video.size);
+} catch (error) {
+  if ((error as { code?: string }).code !== 'CANCELLED') throw error;
+} finally {
+  await progress.remove();
+}
+```
+
+`source` is an absolute path or a `file://` URL. On Android it can also be the `content://` URI a picker returns: the plugin
+reads it in place, so there is no need to copy the video into the app first.
+
+Stop a running transcode with `cancel()`. The `transcode` call then rejects with `CANCELLED`, and no file is left behind.
+
+One transcode runs at a time. A second call while one is running rejects with `BUSY`.
+
+### Replacing an FFmpeg command
+
+The defaults match what this FFmpeg command does, which is a common way to make a phone video safe for a browser:
+
+```
+ffmpeg -i in.mov -vcodec libx264 -vf scale=w=1280:h=1280:force_original_aspect_ratio=decrease \
+  -pix_fmt yuv420p -c:a aac -ss 00:00 -to 00:30 -movflags +faststart out.mp4
+```
+
+The differences: this plugin also tags the colour as BT.709 and tone-maps HDR (that command leaves HDR colour values in an SDR
+file), keeps an AAC track as it is instead of re-encoding it, and asks the encoder for an average bitrate rather than a quality
+level, so file sizes are predictable.
+
+## How each platform does it
+
+**iOS.** `AVAssetReader` decodes the video into 8-bit 4:2:0 frames converted to BT.709 (this is where HDR is tone-mapped), and
+`AVAssetWriter` encodes them with the H.264 encoder at the size and bitrate asked for, writing the source track's transform as the
+output track's transform. An AAC audio track is passed through; any other is decoded and encoded to AAC with the source's channel
+count (more than two channels are mixed down to stereo) and sample rate. `shouldOptimizeForNetworkUse` puts the `moov` box first.
+
+**Android.** Media3 `Transformer` with H.264 and AAC as the output formats, a `Presentation` effect that scales to fit, a clipping
+configuration for the length, `HDR_MODE_TONE_MAP_HDR_TO_SDR_USING_OPEN_GL` for HDR, and Media3's own MP4 muxer with streamable
+output for the `moov` box. Transformer copies an AAC track without decoding it, and picks H.264 High when the encoder has it. HDR
+tone-mapping needs Android 10 (API 29) or newer; an HDR video on an older phone is rare, and fails with `FAILED`.
+
+<docgen-index>
+
+* [`transcode(...)`](#transcode)
+* [`cancel()`](#cancel)
+* [`addListener('progress', ...)`](#addlistenerprogress-)
+* [`removeAllListeners()`](#removealllisteners)
+* [Interfaces](#interfaces)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### transcode(...)
+
+```typescript
+transcode(options: TranscodeOptions) => Promise<TranscodeResult>
+```
+
+Transcode a video into an MP4 that web browsers play:
+
+- H.264 video (High profile where the encoder offers it), 8-bit 4:2:0, tagged
+  BT.709; an HDR source (HLG or PQ) is tone-mapped to SDR
+- AAC audio: an AAC source track is copied as it is, anything else is
+  encoded; a video without sound gets no audio track
+- the longer side at most `maxSize`, cut at `maxDurationMs`
+- the index (`moov`) before the media data, so playback can start before
+  the whole file has downloaded
+- a portrait video keeps its rotation as track metadata, the way a phone
+  records it, so players show it upright
+
+One runs at a time: a second call while one is running rejects with `BUSY`.
+On the web it rejects with the `UNIMPLEMENTED` code.
+
+| Param         | Type                                                          |
+| ------------- | ------------------------------------------------------------- |
+| **`options`** | <code><a href="#transcodeoptions">TranscodeOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#transcoderesult">TranscodeResult</a>&gt;</code>
+
+--------------------
+
+
+### cancel()
+
+```typescript
+cancel() => Promise<void>
+```
+
+Stop the running `transcode`, which then rejects with `CANCELLED` and leaves
+no file behind. Resolves straight away, and does nothing when none is
+running. On the web it rejects with the `UNIMPLEMENTED` code.
+
+--------------------
+
+
+### addListener('progress', ...)
+
+```typescript
+addListener(eventName: 'progress', listenerFunc: (event: TranscodeProgress) => void) => Promise<PluginListenerHandle>
+```
+
+Listen to the progress of the running `transcode`.
+
+| Param              | Type                                                                                |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'progress'</code>                                                             |
+| **`listenerFunc`** | <code>(event: <a href="#transcodeprogress">TranscodeProgress</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### removeAllListeners()
+
+```typescript
+removeAllListeners() => Promise<void>
+```
+
+Remove every listener of this plugin.
+
+--------------------
+
+
+### Interfaces
+
+
+#### TranscodeResult
+
+| Prop             | Type                | Description                                                                                                           |
+| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **`path`**       | <code>string</code> | The absolute path of the MP4 that was written.                                                                        |
+| **`uri`**        | <code>string</code> | The same file as a `file://` URL.                                                                                     |
+| **`width`**      | <code>number</code> | The width of the video as a player shows it, upright: the rotation the output carries as metadata is already applied. |
+| **`height`**     | <code>number</code> | The height of the video as a player shows it, upright.                                                                |
+| **`durationMs`** | <code>number</code> | The length of the output, in milliseconds.                                                                            |
+| **`size`**       | <code>number</code> | The size of the output file, in bytes.                                                                                |
+
+
+#### TranscodeOptions
+
+| Prop                | Type                | Description                                                                                                                                                                                                                                                                                                                | Default              |
+| ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| **`source`**        | <code>string</code> | The video to transcode: an absolute path or a `file://` URL. On Android it can also be a `content://` URI, such as the one a system picker returns; it is read in place, without a copy.                                                                                                                                   |                      |
+| **`destination`**   | <code>string</code> | Where to write the MP4: an absolute path or a `file://` URL. A file that is already there is replaced, and missing directories are created. When it is left out, a new file is created in the app's cache directory (Android) or temporary directory (iOS). The app owns that file and deletes it when it is done with it. |                      |
+| **`maxSize`**       | <code>number</code> | The longest side of the output, in pixels. A larger video is scaled down to fit, keeping its aspect ratio; a smaller one keeps its size. Both sides are rounded down to an even number, as H.264 4:2:0 needs. A whole number, at least 16.                                                                                 | <code>1280</code>    |
+| **`maxDurationMs`** | <code>number</code> | The longest the output may be, in milliseconds. A longer video is cut at this point; a shorter one is kept whole. A whole number, at least 1.                                                                                                                                                                              | <code>30000</code>   |
+| **`videoBitrate`**  | <code>number</code> | The average video bitrate the encoder is asked for, in bits per second. A whole number, at least 1.                                                                                                                                                                                                                        | <code>1800000</code> |
+
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+
+#### TranscodeProgress
+
+| Prop           | Type                | Description                                                                                                          |
+| -------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **`progress`** | <code>number</code> | How far the running `transcode` is, from 0 to 1. It only grows, and the last event before the promise resolves is 1. |
+
+</docgen-api>
+
+## Checked on phones
+
+The example app run on a Pixel 10a (Android 16) and an iPhone 16 (iOS 27), on three phone recordings and the three test clips, with
+every output read back with `ffprobe`: H.264 High, `yuv420p`, BT.709 primaries, transfer and matrix, AAC LC, `moov` before `mdat`,
+the rotation of the source kept, and the size, length and bitrate asked for.
+
+| Source | Android output | iOS output |
+| --- | --- | --- |
+| iPhone HEVC 10-bit HLG, 1920x1080 rotated, 35 s, AAC stereo | 1280x720 rotated (720x1280 shown), 30.0 s, 7.7 MB, 3.5 s | 1280x720 rotated, 30.0 s, 7.2 MB, 2.8 s |
+| Android HEVC, 1920x1080 rotated, 12 s, AAC stereo | 1280x720 rotated, 12.0 s, 3.3 MB, 1.7 s | 1280x720 rotated, 12.0 s, 2.9 MB, 1.1 s |
+| H.264 1920x1080, 10 s, AAC mono | 1280x720, 10.0 s, 2.7 MB, 1.5 s | 1280x720, 10.0 s, 2.3 MB, 0.9 s |
+| PCM stereo 16 kHz (test clip) | AAC stereo 16 kHz | AAC stereo 16 kHz |
+| no audio (test clip) | no audio track | no audio track |
+
+Times are the whole call, as JavaScript saw it. Cancelling, `BUSY`, a `content://` URI on Android, the default destination and the
+error codes were checked in the same runs.
+
+## Tests
+
+| What | Where it runs | Command |
+| --- | --- | --- |
+| The TypeScript: the bridge calls, the web fallback, and that the API, both platforms and this README agree | Node | `npm test` |
+| The option parsing and size arithmetic of the Kotlin | JVM (no device) | `npm run test:android` |
+| The Swift core: option parsing, size arithmetic, and end-to-end transcodes of the clips in `test/fixtures` read back with AVFoundation | a Mac, `swift test` (no simulator) | `npm run test:core` |
+| The same Swift tests and the bridge's own tests | an iOS simulator | `npm run test:ios` |
+| The example app, built with the plugin installed | Gradle, Xcode | `npm run example:android:build`, `npm run example:ios:build` |
+
+`test/fixtures/make-fixtures.sh` writes the test clips with FFmpeg. The example app in `example-app/` transcodes every video it finds
+in its `in/` folder when it starts, and writes the results to `out/`: it is how the plugin is checked on a phone.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,68 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxCoreKTXVersion = project.hasProperty('androidxCoreKTXVersion') ? rootProject.ext.androidxCoreKTXVersion : '1.17.0'
+    // Media3 Transformer, pinned exactly: scripts/check-pins.mjs reads this line and moves it when a release is out.
+    media3Version = project.hasProperty('media3Version') ? rootProject.ext.media3Version : '1.11.1'
+}
+
+buildscript {
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace = "io.github.maximbelov.videotranscoder"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 26
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+kotlin {
+    jvmToolchain(21)
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.core:core-ktx:$androidxCoreKTXVersion"
+    implementation "androidx.media3:media3-transformer:$media3Version"
+    implementation "androidx.media3:media3-effect:$media3Version"
+    implementation "androidx.media3:media3-common:$media3Version"
+    implementation "androidx.media3:media3-muxer:$media3Version"
+    testImplementation "junit:junit:$junitVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/kotlin/io/github/maximbelov/videotranscoder/TranscodeOptions.kt

@@ -0,0 +1,122 @@
+package io.github.maximbelov.videotranscoder
+
+import java.net.URI
+import java.net.URISyntaxException
+
+/** The `code` a call is rejected with: the names are the ones `src/definitions.ts` documents. */
+enum class ErrorCode { INVALID_ARGUMENT, NOT_FOUND, NO_VIDEO, BUSY, CANCELLED, FAILED }
+
+class TranscodeException(val code: ErrorCode, message: String) : Exception(message)
+
+/** Where the source video is: a file, or a `content://` URI read through the content resolver. */
+sealed class SourceLocation {
+    data class File(val path: String) : SourceLocation()
+
+    data class Content(val uri: String) : SourceLocation()
+}
+
+/** What a `transcode` call asked for, checked and with the defaults filled in. Pure Kotlin, so it is tested on the JVM. */
+data class TranscodeOptions(
+    val source: SourceLocation,
+    /** An absolute path, or `null` when the call named none: a new file in the cache directory is used. */
+    val destination: String? = null,
+    val maxSize: Int = DEFAULT_MAX_SIZE,
+    val maxDurationMs: Long = DEFAULT_MAX_DURATION_MS,
+    val videoBitrate: Int = DEFAULT_VIDEO_BITRATE,
+) {
+    companion object {
+        const val DEFAULT_MAX_SIZE = 1280
+        const val DEFAULT_MAX_DURATION_MS = 30_000L
+        const val DEFAULT_VIDEO_BITRATE = 1_800_000
+        const val MINIMUM_MAX_SIZE = 16
+
+        /** The options of a call, read one key at a time through [get], which answers `null` for a key that is absent or null. */
+        fun parse(get: (String) -> Any?): TranscodeOptions {
+            val source = get("source") as? String
+            if (source.isNullOrEmpty()) {
+                throw invalid("source is required: an absolute path, a file:// URL or a content:// URI")
+            }
+            val destination =
+                when (val value = get("destination")) {
+                    null -> null
+                    is String -> filePath(value, "destination")
+                    else -> throw invalid("destination must be a string")
+                }
+            return TranscodeOptions(
+                source = sourceLocation(source),
+                destination = destination,
+                maxSize = wholeNumber(get("maxSize"), "maxSize", MINIMUM_MAX_SIZE, DEFAULT_MAX_SIZE),
+                maxDurationMs = wholeNumber(get("maxDurationMs"), "maxDurationMs", 1, DEFAULT_MAX_DURATION_MS.toInt()).toLong(),
+                videoBitrate = wholeNumber(get("videoBitrate"), "videoBitrate", 1, DEFAULT_VIDEO_BITRATE),
+            )
+        }
+
+        fun sourceLocation(value: String): SourceLocation =
+            if (value.startsWith("content://")) {
+                if (value.length <= "content://".length) throw invalid("source is not a content:// URI: $value")
+                SourceLocation.Content(value)
+            } else {
+                SourceLocation.File(filePath(value, "source"))
+            }
+
+        /** An absolute path or a `file://` URL as an absolute path. Anything else (a relative path, `http://`) is refused. */
+        fun filePath(value: String, name: String): String {
+            var path = value
+            if (value.startsWith("file://")) {
+                path =
+                    try {
+                        URI(value).path
+                    } catch (e: URISyntaxException) {
+                        null
+                    } ?: value.removePrefix("file://").removePrefix("localhost")
+            }
+            if (!path.startsWith("/") || path.length < 2) {
+                throw invalid("$name must be an absolute path or a file:// URL, not $value")
+            }
+            return path
+        }
+
+        /** A file as a `file:///` URL, with the escapes a URL needs. */
+        fun fileUrl(file: java.io.File): String = file.absoluteFile.toURI().toString().replaceFirst("file:/", "file:///")
+
+        private fun wholeNumber(value: Any?, name: String, minimum: Int, fallback: Int): Int {
+            if (value == null) return fallback
+            if (value !is Number) throw invalid("$name must be a number")
+            val double = value.toDouble()
+            if (double.isNaN() || double.isInfinite() || Math.rint(double) != double || double > Int.MAX_VALUE) {
+                throw invalid("$name must be a whole number, not $value")
+            }
+            if (double < minimum) throw invalid("$name must be at least $minimum, not $value")
+            return double.toInt()
+        }
+
+        private fun invalid(message: String) = TranscodeException(ErrorCode.INVALID_ARGUMENT, message)
+    }
+}
+
+/** The arithmetic of the output. Pure, so it is tested without a video. */
+object Geometry {
+    /**
+     * The size that fits a video into [maxSize] on its longer side, keeping the aspect ratio and never scaling up. Both sides are
+     * rounded down to an even number (H.264 4:2:0 halves them for the chroma planes), and are at least 2. Integer arithmetic, so
+     * 1920x1080 into 1280 is exactly 1280x720.
+     */
+    fun outputSize(width: Int, height: Int, maxSize: Int): Pair<Int, Int> {
+        val w = maxOf(Math.abs(width), 1).toLong()
+        val h = maxOf(Math.abs(height), 1).toLong()
+        val longer = maxOf(w, h)
+        val limit = maxOf(maxSize, 2).toLong()
+        fun fit(side: Long): Int {
+            val scaled = if (longer > limit) side * limit / longer else side
+            return maxOf(2L, scaled / 2 * 2).toInt()
+        }
+        return fit(w) to fit(h)
+    }
+
+    /** A stored size as a player shows it, with the rotation applied. */
+    fun displayedSize(width: Int, height: Int, rotationDegrees: Int): Pair<Int, Int> =
+        if (Math.floorMod(rotationDegrees, 180) == 0) width to height else height to width
+
+    /** A percentage from Media3 as progress from 0 to 1, held below 1 until the file is finished. */
+    fun progress(percent: Int): Double = (percent.coerceIn(0, 100) / 100.0).coerceAtMost(0.99)
+}