react-native-skia-webgpu-video 0.1.0-beta.2 → 0.1.0-beta.4

package/LICENSE

@@ -1,7 +1,6 @@
 MIT License
 
 Copyright (c) 2026 Sebastien Hecart
-Portions Copyright (c) 2024 Azzapp
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,8 +6,8 @@
   <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" />
+  <img alt="React Native Skia 3.7.4" src="https://img.shields.io/badge/Skia-3.7.4-38bdf8" />
+  <img alt="React Native WebGPU 0.19.0" src="https://img.shields.io/badge/WebGPU-0.19.0-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.
+> **Beta.** The Skia 3.7.4 / WebGPU 0.19.0 build has run on an iPhone 15 Pro and a Pixel 8a (export speed, pixel 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; two 4K cases have known issues. See [status](#status) before adopting this in production.
 
 ## Installation
 
@@ -37,20 +37,22 @@ 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.7.4`** |
+| React Native WebGPU | **`react-native-webgpu@0.19.0`** (both resolve `react-native-webgpu-dawn@157.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) |
 
 A native rebuild is required. Expo Go cannot load this module. Skia and WebGPU now share Dawn through the `react-native-webgpu-dawn` npm package: `node` must be on the `PATH` during `pod install` and Gradle builds, and both packages must resolve the same version of it. For iOS, use the deployment target required by your React Native and Skia versions; the example targets iOS 16.4 or later.
 
+On ProMotion iPhones, add `CADisableMinimumFrameDurationOnPhone` (Boolean, `YES`) to your app's `Info.plist`: without it, iOS holds every frame callback of the app, the preview's included, at 60 Hz. On Android 15 and later, a playing preview asks the display for its highest refresh rate itself.
+
 ### 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@3.7.4 react-native-webgpu@0.19.0 react-native-reanimated@4.5.3 react-native-worklets@0.11.3
 npm install --save-exact react-native-skia-webgpu-video@beta
 ```
 
@@ -203,13 +205,27 @@ This budget covers **tracked video resources**, not all memory held by codecs, S
 
 | Step | iOS | Android |
 | --- | --- | --- |
-| Decode | AVFoundation, BGRA IOSurface-backed buffers, no extra copy (`alwaysCopiesSampleData = NO`) | API 29+, 8-bit SDR H.264/HEVC at the encoded size: `ImageReader` YUV buffers. Otherwise: EGL render into an RGBA AHardwareBuffer (or a CPU scoped-copy fallback) |
-| Into Skia, preview | WebGPU blit into a reusable texture, then an owned Graphite snapshot | WebGPU blit (YUV→RGB, crop and rotation in one pass), then an owned Graphite snapshot |
-| Into Skia, export | Sampled in place through the frame's IOSurface: no copy, no per-clip GPU wait | 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 |
+| 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 reusable texture. BGRA: a WebGPU blit into it. Then an owned Graphite snapshot | WebGPU blit (YUV→RGB, crop, rotation and scaling to the frame's size in one pass), then an owned Graphite snapshot |
+| 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 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 waits for checked GPU completion before releasing source frames. 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'
+```
+
+- `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.
+
+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.
 
 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).
 
@@ -217,33 +233,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.
 
-**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).
 
@@ -251,11 +274,12 @@ Reproduce on your devices with the example app: `node scripts/test-ios-device-ab
 
 | Area | Current evidence |
 | --- | --- |
-| iOS | iPhone 15 Pro: all export cases above passed in every run (72/72), with output sizes identical to 3.6.1 ([verification](migration/skia-3.7.0/verification.md)). Native XCTests were last run on the simulator with 3.6.1 (50/50); the iOS native sources have not changed since. |
-| 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 were last run on 3.4.4 (97/102; the 5 failures predate it). |
-| JavaScript / types | 217 tests in 10 suites, typecheck, package tests and 112 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 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 ([beta.3 verification](docs/VERIFICATION_0.1.0-beta.3.md)). With Skia 3.7.4: 56/58 native XCTests pass, the other two being opt-in diagnostics, and the smoke profile passes in 8 of 9 runs. The one failure, a preview frame import refused right after a launch on a locked phone, did not come back ([3.7.4 verification](migration/skia-3.7.4/verification.md#reste-à-faire)). |
+| Android | Pixel 8a, beta.4: 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. The EGL-free export writes the same bytes as beta.3's (Rec.709, limited range) ([3.7.4 verification](migration/skia-3.7.4/verification.md)). Instrumented tests: 126/127; the failure, a 4K preview throughput test, fails the same way on beta.3. |
+| JavaScript / types | 238 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 | A 4K lazy composition seek times out in 1 of 3 runs on Pixel 8a, and three simultaneous 4K clips stop on the video memory budget during iPhone playback; both happen before and after this release. With `ImageReader`, 1:1 exports are 5–16% larger files for matching sampled pixels; with 3.7.0 they are up to 5.7% smaller than with 3.6.1, cause not confirmed. |
+| 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. |
 | 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)
@@ -273,6 +297,10 @@ The eight-clip 4K lifecycle case remained memory intensive: sampled peaks reache
 
 A subsequent export-worklet fix reduces repeated-session allocation overhead. In matched two-montage Release runs, memory after 60 seconds idle fell from **426 to 258 MiB physical footprint on iPhone 15 Pro**, and from **738 to 577 MiB PSS on Pixel 8a**. These are different platform metrics, not a cross-device comparison. Six consecutive iPhone workloads and four Android workloads passed with flatter or decreasing late-run readings; bounded tests do not prove zero leaks. See the [native memory investigation](docs/NATIVE_MEMORY_INVESTIGATION_306.md) for checkpoints and limits.
 
+## Built with it
+
+No projects listed yet. Using this library in an app or an open-source project? [Share it in Show and tell](https://github.com/batical/react-native-skia-webgpu-video/discussions/22) and it may be featured here.
+
 ## Development
 
 ```sh

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.7.4, WebGPU 0.19.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. 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/VideoComposition.cpp

@@ -150,6 +150,18 @@ VideoComposition::fromJSIObject(jsi::Runtime& runtime,
   auto composition = VideoComposition::create(duration, items);
   composition->setFieldValue(VideoComposition::javaClassStatic()->getField<jboolean>(
       "hardwareBufferEnabled"), static_cast<jboolean>(NativeHardwareBuffer::isEnabled()));
+  if (jsComposition.hasProperty(runtime, "framePixelFormat")) {
+    auto formatProp = jsComposition.getProperty(runtime, "framePixelFormat");
+    std::string format = formatProp.isString() ? formatProp.asString(runtime).utf8(runtime) : "";
+    if (!formatProp.isUndefined() && format != "auto" && format != "yuv" && format != "rgba")
+      throw jsi::JSError(runtime, "framePixelFormat must be 'auto', 'yuv' or 'rgba'");
+    // 'auto' and 'yuv' are the same on Android: YUV wherever the track allows.
+    if (format == "rgba") {
+      composition->setFieldValue(
+          VideoComposition::javaClassStatic()->getField<jboolean>("rgbaFrames"),
+          (jboolean)JNI_TRUE);
+    }
+  }
   if (jsComposition.hasProperty(runtime, "lazyDecoders")) {
     auto lazyProp = jsComposition.getProperty(runtime, "lazyDecoders");
     if (lazyProp.isBool() && lazyProp.getBool()) {

package/android/cpp/VideoCompositionFramesExtractor.cpp

@@ -54,6 +54,12 @@ jlong VideoCompositionFramesExtractor::getCurrentPosition() const {
   return getCurrentPositionMethod(self());
 }
 
+jlong VideoCompositionFramesExtractor::getPresentedPosition() const {
+  static const auto getPresentedPositionMethod =
+      getClass()->getMethod<jlong()>("getPresentedPosition");
+  return getPresentedPositionMethod(self());
+}
+
 jlong VideoCompositionFramesExtractor::getFramesVersion() const {
   static const auto getFramesVersionMethod =
       getClass()->getMethod<jlong()>("getFramesVersion");

package/android/cpp/VideoCompositionFramesExtractor.h

@@ -33,6 +33,7 @@ public:
   jboolean getIsPlaying() const;
 
   jlong getCurrentPosition() const;
+  jlong getPresentedPosition() const;
 
   jlong getFramesVersion() const;
 

package/android/cpp/VideoCompositionFramesExtractorHostObject.cpp

@@ -172,7 +172,7 @@ jsi::Value VideoCompositionFramesExtractorHostObject::get(
   } else if (propName == "currentTime") {
     std::lock_guard<std::recursive_mutex> lock(playerMutex);
     return {released.test() ? 0
-                            : (double)player->getCurrentPosition() / 1000000.0};
+                            : (double)player->getPresentedPosition() / 1000000.0};
   } else if (propName == "framesVersion") {
     std::lock_guard<std::recursive_mutex> lock(playerMutex);
     return {released.test() || !prepared.test()