react-native-skia-webgpu-video 0.1.0-beta.3 → 0.1.0

package/README.md

@@ -4,10 +4,10 @@
 
 <p align="center">
   <a href="https://github.com/batical/react-native-skia-webgpu-video/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/batical/react-native-skia-webgpu-video/actions/workflows/ci.yml/badge.svg?branch=main" /></a>
-  <a href="https://www.npmjs.com/package/react-native-skia-webgpu-video"><img alt="npm" src="https://img.shields.io/npm/v/react-native-skia-webgpu-video/beta" /></a>
-  <a href="#status"><img alt="Status: beta" src="https://img.shields.io/badge/status-beta-f59e0b" /></a>
-  <img alt="React Native Skia 3.7.1" src="https://img.shields.io/badge/Skia-3.7.1-38bdf8" />
-  <img alt="React Native WebGPU 0.17.0" src="https://img.shields.io/badge/WebGPU-0.17.0-a78bfa" />
+  <a href="https://www.npmjs.com/package/react-native-skia-webgpu-video"><img alt="npm" src="https://img.shields.io/npm/v/react-native-skia-webgpu-video" /></a>
+  <a href="#status"><img alt="Status: stable" src="https://img.shields.io/badge/status-stable-22c55e" /></a>
+  <img alt="React Native Skia 3.10.0" src="https://img.shields.io/badge/Skia-3.10.0-38bdf8" />
+  <img alt="React Native WebGPU 0.21.3" src="https://img.shields.io/badge/WebGPU-0.21.3-a78bfa" />
   <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-34d399" /></a>
 </p>
 
@@ -27,7 +27,7 @@ A new Skia 3 / WebGPU frame-interop layer, written from scratch with explicit re
 - **Audio compositions** with clip audio, separate tracks, and per-item volume.
 - **Custom GPU processing** through an export frame processor and an optional WebGPU resource scope.
 
-> **Beta.** The Skia 3.7.0 / WebGPU 0.17.0 build has run on an iPhone 15 Pro and a Pixel 8a (export speed, pixel checks); 3.7.1, which only changes iOS presentation on ProMotion displays, passed the native tests, smoke runs and the Pixel pixel check. Not yet qualified: memory over long sessions (last checked on 3.0.6), HDR, audible output and A/V synchronization; two 4K cases have known issues. See [status](#status) before adopting this in production.
+> **0.1.0.** The Skia 3.9.1 / WebGPU 0.21.0 build has run on an iPhone 15 Pro and a Pixel 8a: export speed, preview frame accuracy, pixel and color checks, native and instrumented tests, smoke runs. Not yet qualified: memory over long sessions (last checked on 3.0.6), HDR, audible output and A/V synchronization. A few 4K cases have known issues. See [status](#status) before adopting this in production.
 
 ## Installation
 
@@ -37,8 +37,8 @@ A new Skia 3 / WebGPU frame-interop layer, written from scratch with explicit re
 | --- | --- |
 | React Native | `0.86.2` tested; declared peer range `>=0.83 <0.87` |
 | React | `19.2.3` tested |
-| React Native Skia | **`react-native-skia@3.7.1`** |
-| React Native WebGPU | **`react-native-webgpu@0.17.0`** (both resolve `react-native-webgpu-dawn@157.0.0`) |
+| React Native Skia | **`react-native-skia@3.10.0`** |
+| React Native WebGPU | **`react-native-webgpu@0.21.3`** (both resolve `react-native-webgpu-dawn@158.0.0`) |
 | Reanimated / Worklets | **`4.5.3` / `0.11.3`** |
 | Native runtime | New Architecture and Hermes |
 | Android | API **28+**, Vulkan 1.1 (declared as a required feature by Skia) |
@@ -49,11 +49,9 @@ On ProMotion iPhones, add `CADisableMinimumFrameDurationOnPhone` (Boolean, `YES`
 
 ### Install
 
-The beta is published on npm under the `beta` tag:
-
 ```sh
-npm install --save-exact react-native-skia@3.7.1 react-native-webgpu@0.17.0 react-native-reanimated@4.5.3 react-native-worklets@0.11.3
-npm install --save-exact react-native-skia-webgpu-video@beta
+npm install --save-exact react-native-skia@3.10.0 react-native-webgpu@0.21.3 react-native-reanimated@4.5.3 react-native-worklets@0.11.3
+npm install --save-exact react-native-skia-webgpu-video
 ```
 
 Each version requires exact Skia and WebGPU versions (its peer dependencies). The [GitHub releases](https://github.com/batical/react-native-skia-webgpu-video/releases) attach the same package archive, installable by URL. To build it from source instead, run `npm ci`, `npm run build` and `npm pack` in a clone, then `npm install` the resulting `.tgz`.
@@ -205,27 +203,27 @@ This budget covers **tracked video resources**, not all memory held by codecs, S
 
 | Step | iOS | Android |
 | --- | --- | --- |
-| Decode | AVFoundation, IOSurface-backed buffers, no extra copy (`alwaysCopiesSampleData = NO`): the decoder's NV12 (`framePixelFormat: 'yuv'`, the default), or BGRA converted by VideoToolbox (`'rgba'`) | API 29+, 8-bit SDR H.264/HEVC at the encoded size: `ImageReader` YUV buffers (the default). Otherwise, or with `'rgba'`: EGL render into an RGBA AHardwareBuffer (or a CPU scoped-copy fallback) |
-| Into Skia, preview | NV12: a YUV→RGB render pass into a reusable texture. BGRA: a WebGPU blit into it. Then an owned Graphite snapshot | WebGPU blit (YUV→RGB, crop and rotation in one pass), then an owned Graphite snapshot |
+| Decode | AVFoundation, IOSurface-backed buffers, no extra copy (`alwaysCopiesSampleData = NO`): the decoder's NV12 (`framePixelFormat: 'yuv'`, the default), or BGRA converted by VideoToolbox (`'rgba'`) | API 29+, 8-bit SDR H.264/HEVC: `ImageReader` YUV buffers (the default), at any frame size, capped or explicit sizes included. Otherwise, or with `'rgba'`: EGL render into an RGBA AHardwareBuffer (or a CPU scoped-copy fallback) |
+| Into Skia, preview | NV12: a YUV→RGB render pass into a texture of the frame's producer. BGRA: a WebGPU blit into it. The Skia image wraps that texture, without a copy | WebGPU blit (YUV→RGB, crop, rotation and scaling to the frame's size in one pass) into a texture of the frame's producer, which the Skia image wraps without a copy |
 | Into Skia, export | NV12: converted into a per-clip texture, as on Android. BGRA: sampled in place through the frame's IOSurface, no copy | Same as preview |
-| Export output | Skia draws into the encoder's CVPixelBuffer (IOSurface) | Skia draws into an AHardwareBuffer lent by the encoder; EGL samples it into the codec Surface after its sync-fd |
+| Export output | Skia draws into the encoder's CVPixelBuffer (IOSurface) | Skia draws into one of two textures of the library's, which a GPU copy puts into the codec's input Surface, through a WebGPU canvas context on it (Vulkan swapchain): no EGL. Before each present, the frame time is set on the window and its dataspace reset, so the codec writes Rec.709 limited range as it did with EGL |
 | Fallback | CPU readback, with a warning | CPU readback, with a warning |
 
-Every path waits for checked GPU completion before releasing source frames or handing a buffer to the encoder. Scaled, HDR and 10-bit Android sources keep the EGL decode path.
+Every path gives source frames back only once the GPU is done with them: exports wait for checked GPU completion; the preview submits its draws and imports without waiting on the UI thread, and hands decoder buffers back when the GPU reports them done (waiting instead when the memory budget cannot hold them). Android's export waits for a frame's GPU work once it has decoded the next frame, so the GPU draws one frame while the CPU decodes the next, and it reports each frame's duration to Android's performance hints (ADPF, Android 13 and later), which raise the CPU and, from Android 15, the GPU capacity the export gets. On Android, OpenGL remains in two places: the CPU readback fallback draws into the codec Surface through EGL, and HDR and 10-bit sources (or `framePixelFormat: 'rgba'`) keep the EGL decode path.
 
 ### Frame pixel format
 
 `framePixelFormat` chooses how a composition's frames are decoded, for its preview and its export:
 
 ```ts
-const composition = { duration, items, framePixelFormat: 'yuv' }; // 'auto' (default) | 'yuv' | 'rgba'
+const composition = { duration, items, framePixelFormat: 'yuv' }; // 'auto' (default) | 'yuv' | 'rgba' (deprecated)
 ```
 
 - `yuv`: the decoder's own YUV 4:2:0 buffers, converted to RGB on the GPU when a frame is drawn. A decoded frame takes 1.5 bytes a pixel instead of 4 (12.4 MB instead of 33.2 MB in 4K), so the decoder keeps more frames ahead in the same memory.
-- `rgba`: frames converted to RGB as they are decoded (iOS: by VideoToolbox; Android: by an OpenGL pass), which an iOS GPU export samples in place.
-- `auto`: `yuv`, on both platforms.
+- `rgba` (**deprecated**, still supported): frames converted to RGB as they are decoded (iOS: by VideoToolbox; Android: by an OpenGL pass). It no longer has an advantage. Exports run as fast in `yuv` (a 120-clip montage on an iPhone 15 Pro: 7.7 s in `yuv`, 7.8 s in `rgba`), and `yuv` renders the same colors. A 4K60 preview keeps fewer frames on screen in `rgba` (about 235 of 360 on an iPhone 15 Pro, against 355 in `yuv`), and frames take 2.7 times the memory. Use `auto`.
+- `auto`: `yuv`, on both platforms. Android keeps HDR and 10-bit tracks in RGBA whatever the setting.
 
-Both convert with the frame's own YCbCr matrix and range, HDR tone mapped to Rec.709 by the platform. One difference: on iOS, `rgba` also converts a file tagged with other primaries or another SDR transfer function (Display P3, sRGB) to Rec.709, as AVFoundation does; `yuv`, like Android in both formats, takes its samples as Rec.709. Camera footage (Rec.709 or HLG) renders the same in both. See the [measurements](docs/FRAME_PIXEL_FORMAT.md) before choosing.
+Both convert with the frame's own YCbCr matrix and range, HDR tone mapped to Rec.709 by the platform. On iOS, both also convert files tagged Display P3 or sRGB to Rec.709, as AVFoundation does. Android takes SDR samples as Rec.709 in both formats. See the [measurements](docs/FRAME_PIXEL_FORMAT.md) before choosing.
 
 For advanced exports, `createFrameProcessor` supports asynchronous preparation at each composition timestamp. The optional `react-native-skia-webgpu-video/gpu` entry point provides a resource scope whose asynchronous disposal waits for tracked work. See the [WebGPU cube example](examples/webgpu-overlay.ts).
 
@@ -233,33 +231,40 @@ These are integration building blocks. Three.js adapters, Core ML models, and au
 
 ## Benchmarks
 
-Release builds, 3 repetitions per case, deterministic workloads from catalog `2026-10-07.1`, median export wall time. Raw evidence: [iOS device](benchmark/ios-device-370-ab.json), [Android device](benchmark/android-device-370-ab.json); protocol and limits in the [verification report](migration/skia-3.7.0/verification.md). Earlier campaigns: [3.6.1](migration/skia-3.6.1/verification.md), [3.4.4](migration/skia-3.4.4/verification.md).
+Release builds, 3 repetitions per case, deterministic workloads from catalog `2026-10-07.1` (plus two 4K → 4K exports added for beta.4), median export wall time. Protocol, raw results and Perfetto analysis in the [3.7.4 verification report](migration/skia-3.7.4/verification.md). Earlier campaigns: [3.7.0](migration/skia-3.7.0/verification.md), [3.6.1](migration/skia-3.6.1/verification.md), [3.4.4](migration/skia-3.4.4/verification.md).
 
-Skia 3.7.0 / WebGPU 0.17.0 move Graphite and Dawn from 154.3.0 to 157.0.0. Export speed is unchanged on both devices; the gains of this release are in on-screen canvases (below).
+Beta.4 (Skia 3.7.4 / WebGPU 0.19.0) exports a third faster on Android, up to 45% on 4K sources, and leaves iOS unchanged. 0.1.0 (Skia 3.9.1 / WebGPU 0.21.0) leaves export times unchanged on both phones, within ±4% ([3.9.1 verification](migration/skia-3.9.1/verification.md)).
 
-**iPhone 15 Pro (iOS 27.0.1)**, four alternating series off the charger (a first series on a wireless charger ran hot and is not used). Same per-frame profile and same output bytes in both versions:
+**Pixel 8a (Android 17)**, thermal state nominal, medians of 9 repetitions for beta.3 and 6 for beta.4:
 
-| Export case | 3.6.1 | 3.7.0 |
+| Export case | beta.3 (Skia 3.7.1) | beta.4 (Skia 3.7.4) |
 | --- | --- | --- |
-| HEVC 1080p, rotated, 180 frames | 734 ms | 731 ms |
-| H.264 640×360, 60 frames | 173–211 ms | 168–171 ms |
-| 8 × 4K clips scaled to 1280, 360 frames | 2.74–2.78 s | 2.73–2.79 s |
-
-**Pixel 8a (Android 17)**:
-
-| Export case | 3.6.1 | 3.7.0 |
+| 8 × 4K clips at native size, 1080 output, 360 frames | 9.8 s | **7.0 s** (−29%) |
+| 8 × 4K clips scaled to 1280 | 12.7 s | **7.0 s** (−45%) |
+| 3 simultaneous 4K clips, 150 frames | 5.6 s | **3.5 s** (−39%) |
+| H.264 720p, rotated, 180 frames | 3.07 s | **1.82 s** (−41%) |
+| HEVC 1080p, rotated, 180 frames | 3.12 s | **2.08 s** (−33%) |
+| H.264 / HEVC 640×360, 60 frames | 1.25 / 1.27 s | **0.85 / 0.85 s** (−32 / −33%) |
+| One 4K clip exported at 4K, H.264 / HEVC, 900 frames | 25.3 / 25.8 s | **23.0 / 22.3 s** (−9 / −13%) |
+
+Where the time went:
+- **Export renders straight into the codec's input Surface through WebGPU**: no EGL and no lent buffer. Exports of 1080p and below gain 10–17% on their own.
+- **The GPU draws a frame while the CPU decodes the next one.** The export used to wait for the GPU after every frame, then leave it idle while decoding. Mali's frequency governor then kept the GPU at its lowest clock, which made the first 3.7.4 build 24% *slower* than 3.7.1 on 8 native 4K clips.
+- **The export thread reports its frames to Android's performance hints (ADPF)**: it gets faster cores and, from Android 15, more GPU capacity. 15–29% on most cases.
+- **`maxLongSide` and `resolution` keep the codec's YUV buffers**, scaled by the WebGPU conversion instead of an OpenGL render pass. Decoding 8 × 4K clips capped at 1280 takes 8.7 ms per frame instead of 17.
+- A 4K → 4K export is now limited by the hardware encoder.
+
+**iPhone 15 Pro (iOS 27.0.1)**: unchanged, since these changes are Android-only. Three alternating series, Skia 3.7.1 against 3.7.4, off the charger, with the same output bytes:
+
+| Export case | Skia 3.7.1 | Skia 3.7.4 |
 | --- | --- | --- |
-| HEVC 1080p, rotated, 180 frames | 3.02 s | 2.92 s |
-| H.264 640×360, 60 frames | 1.18 s | 1.23 s |
-| 8 × 4K clips at native size, 360 frames | 10.0 s | 9.8 s |
-| 3 simultaneous 4K clips, 150 frames | 5.8 s | 5.6 s |
-| 8 × 4K clips scaled to 1280 (EGL decode) | 12.2 s | 12.5 s |
-
-The native 4K rows compare with the 3.6.1 run of October 16. Files exported from `ImageReader`-decoded clips are up to 5.7% smaller with 3.7.0 while sampled pixels still match CPU decoding within ±1; the cause is not yet confirmed ([verification](migration/skia-3.7.0/verification.md#pixel-8a)).
+| HEVC 1080p, rotated, 180 frames | 730 ms | 737–749 ms |
+| H.264 640×360, 60 frames | 177 ms | 185–217 ms |
+| 8 × 4K clips scaled to 1280, 360 frames | 2.69 s | 2.68–2.74 s |
 
 **Smoother canvases on Android 10.** Dawn 157 asks for three swapchain images instead of two on Android. On Android 10, a canvas no longer makes the main thread wait for the previous frame's buffer: upstream measured 407 → 65 ms of `dequeueBuffer` wait per ~1.9 s trace for one opaque canvas on a Mi MIX 3. Skia 3.6.3 also keeps the render pool one frame ahead of the display: on a 120 Hz Pixel 8, an opaque `SurfaceView` canvas went from 66 to 110 presented frames per second. The swapchain change applies to every Skia and WebGPU canvas and the render pool change to Skia canvases, video previews included, with no code change. We did not measure them ourselves (no Android 10 device); see the [audit](migration/skia-3.7.0/upstream-audit.md#canvas-plus-fluide-sur-android-10).
 
-Pass `onProfile` to an export to see where the time goes on your own compositions. On the Pixel, a native-size HEVC 1080p frame spends about 2.8 ms decoding, 3.3 ms importing, 1.7 ms waiting for the GPU and 3.8 ms encoding; on the iPhone the whole frame takes under 4 ms.
+Pass `onProfile` to an export to see where the time goes on your own compositions. On the Pixel, a native-size HEVC 1080p frame spends about 2.5 ms decoding, 1.9 ms importing, 0.8 ms waiting for the GPU and 3.7 ms encoding (beta.3: 2.8, 3.3, 1.7 and 3.8 ms); on the iPhone the whole frame takes under 4 ms.
 
 Reproduce on your devices with the example app: `node scripts/test-ios-device-ab-run.mjs` (iPhone) and `node scripts/test-android-device-run.mjs` (Android); see the [benchmark guide](docs/BENCHMARKS.md).
 
@@ -267,12 +272,12 @@ Reproduce on your devices with the example app: `node scripts/test-ios-device-ab
 
 | Area | Current evidence |
 | --- | --- |
-| Frame accuracy | At 60 Hz, the preview draws the frame due at 99–100% of vsyncs in 30, 24 and 60 fps on both phones, and 97–100% in 4K with `yuv` frames on the Pixel 8a. On a warm iPhone at 120 Hz: 73–95% in 1080p, 77–90% in 4K 60 fps. Every exported frame holds the right source frame, in both frame pixel formats ([beta.3 verification](docs/VERIFICATION_0.1.0-beta.3.md)). |
-| iOS | iPhone 15 Pro: 61/61 benchmark cases pass with `yuv` frames, including the three that stopped on the video memory budget with BGRA; 56/58 native XCTests pass, the other two being opt-in diagnostics ([beta.3 verification](docs/VERIFICATION_0.1.0-beta.3.md)). |
-| Android | Pixel 8a: CPU vs GPU decode comparison 10/10 cases (max channel error 1, including rotation, portrait and 4K); export checks of a color pattern and of a decoded rotated clip match CPU readback. With Dawn 157 the errors stay within ±1, as with 3.6.1 ([verification](migration/skia-3.7.0/verification.md#pixels)). Instrumented tests: 126/127 on beta.3 (the failure is a known 4K throughput test, see the [verification](docs/VERIFICATION_0.1.0-beta.3.md#tests-natifs)). |
-| JavaScript / types | 237 tests in 11 suites, typecheck, package tests and 122 benchmark-harness tests pass; CI runs them on every pull request. |
+| Frame accuracy | At 60 Hz, the preview draws the frame due at 99–100% of vsyncs in 30, 24 and 60 fps on both phones, and 97–100% in 4K with `yuv` frames on the Pixel 8a. On an iPhone 15 Pro at 120 Hz with Skia 3.9.1: 99.7–100% of the frames read back are exact, and a 4K 60 fps preview shows 355–358 of its 360 frames at about 120 draws/s. Every exported frame holds the right source frame, in both frame pixel formats ([beta.3](docs/VERIFICATION_0.1.0-beta.3.md) and [3.9.1](migration/skia-3.9.1/verification.md) verifications). |
+| iOS | iPhone 15 Pro: 61/61 benchmark cases pass with `yuv` frames, including the three that stopped on the video memory budget with BGRA ([beta.3 verification](docs/VERIFICATION_0.1.0-beta.3.md)). With Skia 3.9.1: 56/58 native XCTests pass, the other two being opt-in diagnostics. The smoke profile passes, and the frame-sync profile matches Skia 3.8.1's 43/58, with all 16 exports frame-exact ([3.9.1 verification](migration/skia-3.9.1/verification.md)). |
+| Android | Pixel 8a, Skia 3.9.1: CPU vs GPU decode comparison 10/10 cases (max channel error 1, including rotation, portrait and 4K); export checks of a color pattern and of a decoded rotated clip match CPU readback, now read back asynchronously. The EGL-free export writes Rec.709, limited range ([3.7.4](migration/skia-3.7.4/verification.md) and [3.9.1](migration/skia-3.9.1/verification.md) verifications). Instrumented tests: 126/127. The failure, a 4K preview throughput test, fails the same way on Skia 3.8.1. |
+| JavaScript / types | 247 tests in 11 suites, typecheck, package tests and 122 benchmark-harness tests pass; CI runs them on every pull request. |
 | Image / audio fidelity | Sampled SDR pixels and an exported color pattern are checked on Android; iOS exported files have the same byte size as with 3.0.6. Whole-image fidelity, HDR, audible output and A/V synchronization remain unqualified. |
-| Known issues | On Pixel 8a: a seek while playing a 4K sequence leaves the clock stalled, a paused seek into a 120-clip lazy montage does not show its frame, and Android 17 reports a missing file in words the harness does not recognize; all three predate beta.3. An iOS export with `yuv` frames spends 2–4 ms more per frame than with `rgba`. With `ImageReader`, 1:1 exports are 5–16% larger files for matching sampled pixels. |
+| Known issues | On Pixel 8a: a seek while playing a 4K sequence leaves the clock stalled, a paused seek into a 120-clip lazy montage does not show its frame, and Android 17 reports a missing file in words the harness does not recognize; all three predate beta.3. On iPhone, a 4K 60 fps preview with the deprecated `rgba` frames shows only about 235 of 360 frames: its 33 MB buffers keep a GPU wait to stay within the memory budget. With `ImageReader`, 1:1 exports are 5–16% larger files for matching sampled pixels. |
 | Long sessions | Not yet re-run since 3.0.6; the 3.0.6 results below are the latest. |
 
 ### Earlier results (Skia 3.0.6)

package/android/BUILD_VALIDATION.md

@@ -1,6 +1,6 @@
 # Android validation and frame ownership
 
-The Android example in `../example/android` pins React Native 0.86.2, Skia 3.7.1, WebGPU 0.17.0, the shared `react-native-webgpu-dawn` 157.0.0 (chrome-m157) and Graphite Android 157.0.0; Gradle needs `node` to resolve that Dawn package. Export renders into encoder-lent AHardwareBuffers (`android/cpp/EncoderTargets.cpp`) sampled into the codec Surface by EGL, with CPU readback as the fallback. On API 29+, 8-bit SDR H.264/HEVC clips decoded at their encoded size go through an `ImageReader`, whose YUV buffers WebGPU converts, crops and rotates; since 3.6.1 each buffer is imported once, and exports sample the converted frame in place. The 3.7.0 build was assembled and run on a Pixel 8a on 2026-10-19 ([verification](../migration/skia-3.7.0/verification.md)), after the 3.6.1 build of 2026-10-16 ([verification](../migration/skia-3.6.1/verification.md)) and the 3.4.4 build of 2026-10-14/15 ([verification](../migration/skia-3.4.4/verification.md)); the evidence below is from Skia 3.0.6 / WebGPU 0.12.1 / Graphite 154.1.0. It uses Java 17, Gradle 9.3.1, Android SDK 36 and NDK 27.1.12297006. The library requires API 28; a consuming application with a lower minimum receives an explicit Gradle configuration error. The default example ABI is arm64-v8a; `RNSKV_ANDROID_ABI` selects another ABI for the validation script.
+The Android example in `../example/android` pins React Native 0.86.2, Skia 3.10.0, WebGPU 0.21.3, the shared `react-native-webgpu-dawn` 158.0.0 (chrome-m158) and Graphite Android 158.0.0; Gradle needs `node` to resolve that Dawn package. Since WebGPU 0.19.0, export renders straight into the codec's input Surface through a WebGPU canvas context on it (`MakeWebGPUCanvasContextFromNativeWindow`, Vulkan swapchain), with no EGL; CPU readback, drawn into the Surface by EGL, stays the fallback. On API 29+, 8-bit SDR H.264/HEVC clips go through an `ImageReader`, whose YUV buffers WebGPU converts, crops, rotates and scales to the frame's size (capped or explicit sizes included since the 3.7.4 migration); since 3.6.1 each buffer is imported once, and exports sample the converted frame in place. The 3.7.0 build was assembled and run on a Pixel 8a on 2026-10-19 ([verification](../migration/skia-3.7.0/verification.md)), after the 3.6.1 build of 2026-10-16 ([verification](../migration/skia-3.6.1/verification.md)) and the 3.4.4 build of 2026-10-14/15 ([verification](../migration/skia-3.4.4/verification.md)); the evidence below is from Skia 3.0.6 / WebGPU 0.12.1 / Graphite 154.1.0. It uses Java 17, Gradle 9.3.1, Android SDK 36 and NDK 27.1.12297006. The library requires API 28; a consuming application with a lower minimum receives an explicit Gradle configuration error. The default example ABI is arm64-v8a; `RNSKV_ANDROID_ABI` selects another ABI for the validation script.
 
 Run `android/scripts/validate.sh build` from the repository. It assembles the example Debug and unsigned Release APKs, library AAR, standalone instrumentation APK and JVM tests. Release uses the installed `hermes-compiler` package, and both native and Metro build concurrency are bounded to two workers. The Release APK is unsigned: device installation requires signing a separate local qualification artifact. The project supplies no publishing or release signing configuration.
 

package/android/CMakeLists.txt

@@ -42,6 +42,8 @@ add_library(${PACKAGE_NAME}
         cpp/VideoCompositionFramesExtractorSyncHostObject.cpp
         cpp/VideoEncoderHostObject.h
         cpp/VideoEncoderHostObject.cpp
+        cpp/ExportHintSession.h
+        cpp/ExportHintSession.cpp
         cpp/VideoPlayerHostObject.h
         cpp/VideoPlayerHostObject.cpp
         cpp/VideoPlayer.h
@@ -54,8 +56,6 @@ add_library(${PACKAGE_NAME}
         cpp/NativeRgbaBuffer.cpp
         cpp/NativeHardwareBuffer.h
         cpp/NativeHardwareBuffer.cpp
-        cpp/EncoderTargets.h
-        cpp/EncoderTargets.cpp
 )
 
 # Specifies a path to native header files.
@@ -90,6 +90,7 @@ target_link_libraries(
         -lGLESv2
         -lEGL
         -landroid
+        -lnativewindow
 )
 
 

package/android/cpp/ExportHintSession.cpp

@@ -0,0 +1,114 @@
+#include "ExportHintSession.h"
+#include <android/performance_hint.h>
+#include <dlfcn.h>
+#include <time.h>
+#include <unistd.h>
+#include <algorithm>
+#include <type_traits>
+
+namespace RNSkiaVideo {
+
+namespace {
+int64_t nanos(clockid_t clock) {
+  timespec now{};
+  clock_gettime(clock, &now);
+  return static_cast<int64_t>(now.tv_sec) * 1'000'000'000 + now.tv_nsec;
+}
+
+/**
+ * The NDK's performance hint functions, resolved at run time: the library
+ * supports Android 9, hint sessions exist from Android 13, and work durations
+ * with a GPU part from Android 15. Null where missing.
+ */
+struct Hints {
+  APerformanceHintManager* (*getManager)() = nullptr;
+  APerformanceHintSession* (*createSession)(APerformanceHintManager*,
+                                            const int32_t*, size_t,
+                                            int64_t) = nullptr;
+  int (*reportActual)(APerformanceHintSession*, int64_t) = nullptr;
+  void (*closeSession)(APerformanceHintSession*) = nullptr;
+  AWorkDuration* (*createWork)() = nullptr;
+  void (*releaseWork)(AWorkDuration*) = nullptr;
+  void (*setWorkStart)(AWorkDuration*, int64_t) = nullptr;
+  void (*setWorkTotal)(AWorkDuration*, int64_t) = nullptr;
+  void (*setWorkCpu)(AWorkDuration*, int64_t) = nullptr;
+  void (*setWorkGpu)(AWorkDuration*, int64_t) = nullptr;
+  int (*reportWork)(APerformanceHintSession*, AWorkDuration*) = nullptr;
+
+  bool sessions() const {
+    return getManager && createSession && reportActual && closeSession;
+  }
+  bool workDurations() const {
+    return createWork && releaseWork && setWorkStart && setWorkTotal &&
+           setWorkCpu && setWorkGpu && reportWork;
+  }
+};
+
+const Hints& hints() {
+  static const Hints functions = [] {
+    Hints found;
+    void* library = dlopen("libandroid.so", RTLD_NOW);
+    if (library == nullptr) return found;
+    const auto resolve = [library](auto& function, const char* name) {
+      function = reinterpret_cast<std::remove_reference_t<decltype(function)>>(
+          dlsym(library, name));
+    };
+    resolve(found.getManager, "APerformanceHint_getManager");
+    resolve(found.createSession, "APerformanceHint_createSession");
+    resolve(found.reportActual, "APerformanceHint_reportActualWorkDuration");
+    resolve(found.closeSession, "APerformanceHint_closeSession");
+    resolve(found.createWork, "AWorkDuration_create");
+    resolve(found.releaseWork, "AWorkDuration_release");
+    resolve(found.setWorkStart, "AWorkDuration_setWorkPeriodStartTimestampNanos");
+    resolve(found.setWorkTotal, "AWorkDuration_setActualTotalDurationNanos");
+    resolve(found.setWorkCpu, "AWorkDuration_setActualCpuDurationNanos");
+    resolve(found.setWorkGpu, "AWorkDuration_setActualGpuDurationNanos");
+    resolve(found.reportWork, "APerformanceHint_reportActualWorkDuration2");
+    return found;
+  }();
+  return functions;
+}
+} // namespace
+
+ExportHintSession::ExportHintSession(int frameRate)
+    : targetNanos(1'000'000'000LL / (std::max(frameRate, 1) * 4LL)) {}
+
+ExportHintSession::~ExportHintSession() {
+  if (session != nullptr) hints().closeSession(session);
+}
+
+void ExportHintSession::frameDone() {
+  const auto& functions = hints();
+  const auto now = nanos(CLOCK_MONOTONIC);
+  const auto cpu = nanos(CLOCK_THREAD_CPUTIME_ID);
+  if (session == nullptr) {
+    if (unavailable) return;
+    // The calling thread is the export's: it decodes, draws and encodes.
+    auto* manager = functions.sessions() ? functions.getManager() : nullptr;
+    const int32_t thread = gettid();
+    session = manager != nullptr
+                  ? functions.createSession(manager, &thread, 1, targetNanos)
+                  : nullptr;
+    unavailable = session == nullptr;
+  } else if (functions.workDurations()) {
+    const auto total = std::max<int64_t>(now - lastNanos, 1);
+    const auto threadCpu = std::clamp<int64_t>(cpu - lastCpuNanos, 0, total);
+    // The thread waits out the rest of the frame, mostly for the GPU: given
+    // as GPU time, which lets Android raise the GPU clock as well.
+    auto* work = functions.createWork();
+    if (work != nullptr) {
+      functions.setWorkStart(work, lastNanos);
+      functions.setWorkTotal(work, total);
+      functions.setWorkCpu(work, threadCpu);
+      functions.setWorkGpu(work, total - threadCpu);
+      functions.reportWork(session, work);
+      functions.releaseWork(work);
+    }
+  } else {
+    functions.reportActual(session, std::max<int64_t>(now - lastNanos, 1));
+  }
+  lastNanos = now;
+  lastCpuNanos = cpu;
+}
+
+} // namespace RNSkiaVideo

package/android/cpp/ExportHintSession.h

@@ -0,0 +1,35 @@
+#pragma once
+
+#include <cstdint>
+
+struct APerformanceHintSession;
+
+namespace RNSkiaVideo {
+
+/**
+ * Tells Android (ADPF) how long the export takes to make each frame, so that
+ * it gives the export thread, and on Android 15 and later the GPU, the
+ * capacity it needs. An export runs as fast as it can rather than at its frame
+ * rate: frames are measured against a quarter of their real-time budget.
+ * Best effort: before Android 13, or on a device without hint sessions,
+ * nothing happens.
+ */
+class ExportHintSession {
+public:
+  explicit ExportHintSession(int frameRate);
+  ~ExportHintSession();
+  ExportHintSession(const ExportHintSession&) = delete;
+  ExportHintSession& operator=(const ExportHintSession&) = delete;
+
+  /** On the export thread, once a frame went to the encoder. */
+  void frameDone();
+
+private:
+  int64_t targetNanos;
+  APerformanceHintSession* session = nullptr;
+  bool unavailable = false;
+  int64_t lastNanos = 0;
+  int64_t lastCpuNanos = 0;
+};
+
+} // namespace RNSkiaVideo

package/android/cpp/VideoEncoderHostObject.cpp

@@ -1,49 +1,36 @@
 #include "RNSVCheckedSizes.h"
 #include "VideoEncoderHostObject.h"
-#include "NativeHardwareBuffer.h"
-#include <EGL/egl.h>
+#include <android/data_space.h>
+#include <android/native_window_jni.h>
+#include <dlfcn.h>
 #include <fbjni/ByteBuffer.h>
 #include <cmath>
 #include <limits>
-#include <unistd.h>
 
 namespace RNSkiaVideo {
 using namespace facebook::jni;
 
 namespace {
-/** Makes the encoder's EGL context current; restores the caller's (or none). */
-class ScopedEncoderContext {
-public:
-  explicit ScopedEncoderContext(const global_ref<VideoEncoder>& encoder)
-      : display(eglGetCurrentDisplay()), context(eglGetCurrentContext()),
-        draw(eglGetCurrentSurface(EGL_DRAW)), read(eglGetCurrentSurface(EGL_READ)) {
-    encoder->makeGLContextCurrent();
-  }
-  ~ScopedEncoderContext() {
-    if (context != EGL_NO_CONTEXT) {
-      eglMakeCurrent(display, draw, read, context);
-    } else if (auto current = eglGetCurrentDisplay(); current != EGL_NO_DISPLAY) {
-      eglMakeCurrent(current, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
-    }
-  }
-  ScopedEncoderContext(const ScopedEncoderContext&) = delete;
-  ScopedEncoderContext& operator=(const ScopedEncoderContext&) = delete;
-
-private:
-  EGLDisplay display;
-  EGLContext context;
-  EGLSurface draw;
-  EGLSurface read;
+struct JSurface : JavaClass<JSurface> {
+  static constexpr auto kJavaDescriptor = "Landroid/view/Surface;";
 };
 
-/** Sync-fds handed over by JS; each is closed exactly once. */
-struct OwnedFences {
-  std::vector<int> fds;
-  ~OwnedFences() {
-    for (int fd : fds)
-      if (fd >= 0) close(fd);
-  }
-};
+/**
+ * Sets the presentation time of the next buffer queued to a window, as
+ * eglPresentationTimeANDROID does: the codec reads it as the frame's time.
+ * libnativewindow exports it on Android 10 and later, though the NDK does not
+ * declare it (it is in the LL-NDK); null where it is missing.
+ */
+using SetBuffersTimestamp = int32_t (*)(ANativeWindow*, int64_t);
+SetBuffersTimestamp setBuffersTimestamp() {
+  static const auto function = []() -> SetBuffersTimestamp {
+    void* library = dlopen("libnativewindow.so", RTLD_NOW);
+    return library == nullptr ? nullptr
+                              : reinterpret_cast<SetBuffersTimestamp>(dlsym(
+                                    library, "ANativeWindow_setBuffersTimestamp"));
+  }();
+  return function;
+}
 } // namespace
 
 local_ref<VideoEncoder>
@@ -79,12 +66,6 @@ void VideoEncoder::prepare() const {
   prepareMethod(self());
 }
 
-void VideoEncoder::makeGLContextCurrent() const {
-  static const auto makeGLContextCurrentMethod =
-      getClass()->getMethod<void()>("makeGLContextCurrent");
-  makeGLContextCurrentMethod(self());
-}
-
 void VideoEncoder::encodeFrameRgba(alias_ref<JByteBuffer> pixels, jint width,
                                    jint height, jint bytesPerRow, jdouble time) const {
   static const auto method =
@@ -92,9 +73,21 @@ void VideoEncoder::encodeFrameRgba(alias_ref<JByteBuffer> pixels, jint width,
   method(self(), pixels, width, height, bytesPerRow, time);
 }
 
-void VideoEncoder::encodeTexture(jint texture, jdouble time) const {
-  static const auto method = getClass()->getMethod<void(jint, jdouble)>("encodeTexture");
-  method(self(), texture, time);
+local_ref<jobject> VideoEncoder::getInputSurface() const {
+  static const auto method =
+      getClass()->getMethod<JSurface::javaobject()>("getInputSurface");
+  auto surface = method(self());
+  return make_local(static_cast<jobject>(surface.get()));
+}
+
+jlong VideoEncoder::beginWindowFrame(jdouble time) const {
+  static const auto method = getClass()->getMethod<jlong(jdouble)>("beginWindowFrame");
+  return method(self(), time);
+}
+
+void VideoEncoder::endWindowFrame(jlong timeUs) const {
+  static const auto method = getClass()->getMethod<void(jlong)>("endWindowFrame");
+  method(self(), timeUs);
 }
 
 void VideoEncoder::release() const {
@@ -112,11 +105,11 @@ VideoEncoderHostObject::VideoEncoderHostObject(
     std::string& outPath, int width, int height, int frameRate, int bitRate,
     std::optional<std::string> encoderName, std::optional<std::string> codec,
     alias_ref<VideoComposition> composition, int audioSampleRate,
-    int audioChannelCount, int audioBitRate)
-    : width(width), height(height) {
+    int audioChannelCount, int audioBitRate) {
   framesExtractor = make_global(VideoEncoder::create(
       outPath, width, height, frameRate, bitRate, encoderName, codec,
       composition, audioSampleRate, audioChannelCount, audioBitRate));
+  hints = std::make_unique<ExportHintSession>(frameRate);
 }
 
 VideoEncoderHostObject::~VideoEncoderHostObject() {
@@ -128,8 +121,7 @@ VideoEncoderHostObject::getPropertyNames(jsi::Runtime& rt) {
   std::vector<jsi::PropNameID> result;
   result.push_back(jsi::PropNameID::forUtf8(rt, std::string("prepare")));
   result.push_back(jsi::PropNameID::forUtf8(rt, std::string("encodeFrame")));
-  result.push_back(jsi::PropNameID::forUtf8(rt, std::string("acquireFrameBuffer")));
-  result.push_back(jsi::PropNameID::forUtf8(rt, std::string("releaseFrameBuffer")));
+  result.push_back(jsi::PropNameID::forUtf8(rt, std::string("acquireInputWindow")));
   result.push_back(jsi::PropNameID::forUtf8(rt, std::string("finishWriting")));
   result.push_back(jsi::PropNameID::forUtf8(rt, std::string("dispose")));
   return result;
@@ -155,39 +147,31 @@ jsi::Value VideoEncoderHostObject::get(jsi::Runtime& runtime,
           auto frame = arguments[0].asObject(runtime);
           const auto kindValue = frame.getProperty(runtime, "kind");
           const auto kind = kindValue.isString() ? kindValue.asString(runtime).utf8(runtime) : "";
-          if (kind == "native-buffer") {
-            // A lent buffer Skia rendered into; its sync-fds are ours to close.
-            OwnedFences fences;
-            const auto fenceValues = frame.getProperty(runtime, "fences");
-            if (fenceValues.isObject()) {
-              auto array = fenceValues.asObject(runtime).asArray(runtime);
-              for (size_t i = 0; i < array.size(runtime); ++i) {
-                auto value = array.getValueAtIndex(runtime, i);
-                if (!value.isBigInt()) throw jsi::JSError(runtime, "Encoder fences must be sync-fd BigInts");
-                // WebGPU reports an already signaled fence as -1, as a uint32.
-                fences.fds.push_back(static_cast<int>(
-                    static_cast<uint32_t>(value.asBigInt(runtime).getUint64(runtime))));
-              }
-            }
-            const auto pointerValue = frame.getProperty(runtime, "nativeBuffer");
-            if (!pointerValue.isBigInt() || !targets)
-              throw jsi::JSError(runtime, "Encoder frame buffer is not the one lent");
-            const auto* buffer = reinterpret_cast<const AHardwareBuffer*>(
-                static_cast<uintptr_t>(pointerValue.asBigInt(runtime).getUint64(runtime)));
+          if (kind == "window") {
+            // The GPU export rendered the frame into the canvas context of the
+            // input window: `present` queues it, with the time set here.
+            if (window == nullptr)
+              throw jsi::JSError(runtime, "Encoder input window was not acquired");
+            auto present = frame.getProperty(runtime, "present");
+            if (!present.isObject() || !present.asObject(runtime).isFunction(runtime))
+              throw jsi::JSError(runtime, "A window frame needs its present function");
             const auto time = checkedMediaSeconds(arguments[1].asNumber());
-            ScopedEncoderContext scope(framesExtractor);
-            const auto texture = targets->beginEncode(buffer, fences.fds);
-            try {
-              framesExtractor->encodeTexture(static_cast<jint>(texture), time);
-            } catch (...) {
-              targets->finishEncode();
-              throw;
-            }
-            targets->finishEncode();
+            const auto timeUs = framesExtractor->beginWindowFrame(time);
+            // The swapchain tags its buffers sRGB, full range, and the codec
+            // would encode and label the file so. Unknown, as EGL leaves it,
+            // lets the codec use its default: Rec.709, limited range. Set for
+            // every frame, as a recreated swapchain tags the window again.
+            if (ANativeWindow_setBuffersDataSpace(window, ADATASPACE_UNKNOWN) != 0)
+              throw jsi::JSError(runtime, "Cannot set the encoder frame dataspace");
+            if (setBuffersTimestamp()(window, static_cast<int64_t>(timeUs) * 1000) != 0)
+              throw jsi::JSError(runtime, "Cannot set the encoder frame time");
+            present.asObject(runtime).asFunction(runtime).call(runtime);
+            framesExtractor->endWindowFrame(timeUs);
+            hints->frameDone();
             return jsi::Value::undefined();
           }
           if (kind != "rgba") {
-            throw jsi::JSError(runtime, "Android encoder accepts RGBA pixels or a lent hardware buffer");
+            throw jsi::JSError(runtime, "Android encoder accepts RGBA pixels or a window frame");
           }
           const auto checkedInteger = [&](const char* name) -> int {
             const auto value = frame.getProperty(runtime, name).asNumber();
@@ -234,7 +218,7 @@ jsi::Value VideoEncoderHostObject::get(jsi::Runtime& runtime,
           framesExtractor->encodeFrameRgba(javaPixels, width, height, stride, checkedMediaSeconds(arguments[1].asNumber()));
           return jsi::Value::undefined();
         });
-  } else if (propName == "acquireFrameBuffer") {
+  } else if (propName == "acquireInputWindow") {
     return getFunction(
         runtime, propName, 0,
         [this](jsi::Runtime& runtime, const jsi::Value& thisValue,
@@ -243,22 +227,17 @@ jsi::Value VideoEncoderHostObject::get(jsi::Runtime& runtime,
           if (released.test() || !prepared || finished) {
             throw jsi::JSError(runtime, "Encoder not prepared");
           }
-          // The buffers are imported by the same Dawn device as decoded AHBs.
-          if (!NativeHardwareBuffer::isEnabled()) {
-            throw jsi::JSError(runtime, "Android GPU export requires AHardwareBuffer interop");
+          // Without it, every frame would carry the time it was queued at.
+          if (setBuffersTimestamp() == nullptr) {
+            throw jsi::JSError(runtime, "Encoder frame times need Android 10 or later");
           }
-          if (!targets) targets = std::make_unique<EncoderTargets>(width, height);
-          auto* buffer = targets->lend();
-          return jsi::BigInt::fromUint64(runtime, reinterpret_cast<uintptr_t>(buffer));
-        });
-  } else if (propName == "releaseFrameBuffer") {
-    return getFunction(
-        runtime, propName, 0,
-        [this](jsi::Runtime& runtime, const jsi::Value& thisValue,
-               const jsi::Value* arguments, size_t count) -> jsi::Value {
-          std::lock_guard<std::recursive_mutex> lock(encoderMutex);
-          if (targets) targets->giveBack();
-          return jsi::Value::undefined();
+          if (window == nullptr) {
+            auto surface = framesExtractor->getInputSurface();
+            window = ANativeWindow_fromSurface(Environment::current(), surface.get());
+            if (window == nullptr)
+              throw jsi::JSError(runtime, "Cannot get the encoder input window");
+          }
+          return jsi::BigInt::fromUint64(runtime, reinterpret_cast<uintptr_t>(window));
         });
   } else if (propName == "prepare") {
     return getFunction(
@@ -300,16 +279,12 @@ jsi::Value VideoEncoderHostObject::get(jsi::Runtime& runtime,
 void VideoEncoderHostObject::release() {
   std::lock_guard<std::recursive_mutex> lock(encoderMutex);
   if (!released.test_and_set()) {
-    if (targets && !targets->empty()) {
-      // GL names belong to the encoder context; free them before it goes.
-      // Otherwise the destructor still releases buffers and reservations.
-      try {
-        ScopedEncoderContext scope(framesExtractor);
-        targets->clear();
-      } catch (...) {
-      }
+    // A canvas context presenting to the window holds its own reference.
+    if (window != nullptr) {
+      ANativeWindow_release(window);
+      window = nullptr;
     }
-    targets.reset();
+    hints.reset();
     framesExtractor->release();
     framesExtractor = nullptr;
   }