Bump version to 0.1.2

Add stream_identity.h defining JELLYFRAME_STREAM_USER_AGENT ("Jellyframe") and apply it to both the mpv (user-agent) and FFmpeg (user_agent) HTTP options so streaming requests identify themselves consistently.

Update the recovery test to identify the video request by its connection instead of the User-Agent header, since the user agent is no longer a reliable differentiator.

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+* @Cuteminded @LexiMallow
+
+.py @Cuteminded

.github/workflows/build-linux.yml

@@ -25,16 +25,13 @@ jobs:
         include:
           - arch: x86_64
             runner: ubuntu-24.04
-            preset: Linux x64 OpenXR
-            vulkan_preset: Linux x64 Vulkan
+            preset: Linux x64
           - arch: arm64
             runner: ubuntu-24.04-arm
-            preset: Linux ARM64 OpenXR
-            vulkan_preset: Linux ARM64 Vulkan
+            preset: Linux ARM64
     env:
       ARCH: ${{ matrix.arch }}
       EXPORT_PRESET: ${{ matrix.preset }}
-      VULKAN_EXPORT_PRESET: ${{ matrix.vulkan_preset }}
     defaults:
       run:
         shell: bash
@@ -47,8 +44,7 @@ jobs:
       - name: Install build dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install --no-install-recommends -y \
-            build-essential cmake pkg-config python3 curl unzip libmpv-dev patchelf
+          sudo apt-get install --no-install-recommends -y build-essential cmake pkg-config python3 curl unzip libmpv-dev patchelf libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
 
       - name: Build PC video plugin
         run: |
@@ -79,24 +75,24 @@ jobs:
         run: |
           output="dist/linux-${ARCH}"
           mkdir -p "$output"
-          godot --headless --xr-mode off --path . --export-release "$EXPORT_PRESET" "$output/jellyframe-opengl.${ARCH}"
-          godot --headless --xr-mode off --path . --export-release "$VULKAN_EXPORT_PRESET" "$output/jellyframe-vulkan.${ARCH}"
+          godot --headless --xr-mode off --path . --export-release "$EXPORT_PRESET" "$output/jellyframe.${ARCH}"
 
       - name: Verify Linux export files
         run: |
           output="dist/linux-${ARCH}"
-          test -s "$output/jellyframe-opengl.${ARCH}"
-          test -s "$output/jellyframe-vulkan.${ARCH}"
+          test -s "$output/jellyframe.${ARCH}"
           test -s "$output/jellyframe_mpv.linux.${ARCH}.so"
-          chmod +x "$output/jellyframe-opengl.${ARCH}" "$output/jellyframe-vulkan.${ARCH}"
+          chmod +x "$output/jellyframe.${ARCH}"
+
+      - name: Verify exported renderer settings
+        run: timeout 30 godot --headless --xr-mode off --main-pack "dist/linux-${ARCH}/jellyframe.${ARCH}" --script tests/test_export_renderer.gd
 
       - name: Copy Linux licenses and installation guide
         run: |
           output="dist/linux-${ARCH}"
           cp -r "build/linux/${ARCH}/licenses" "$output/"
-          cp "build/linux/${ARCH}/build-info.txt" "$output/"
           cp LICENSE "$output/licenses/jellyframe.txt"
-          cp INSTALLATION.md "$output/README.md"
+          cp LICENSING.md "$output/licenses/"
 
       - name: Check Linux decoder dependencies
         run: |
@@ -107,7 +103,7 @@ jobs:
             exit 1
           fi
 
-      - name: Package OpenGL and Vulkan AppImages
+      - name: Package Linux AppImage
         run: bash tools/package-linux-appimages.sh "$ARCH"
 
       - name: Package Linux build with system libraries
@@ -127,20 +123,11 @@ jobs:
           retention-days: 14
           archive: false
 
-      - name: Upload OpenGL AppImage
+      - name: Upload Linux AppImage
         uses: actions/upload-artifact@v7
         with:
-          name: ${{ steps.date.outputs.date }}-jellyframe-linux-${{ matrix.arch }}-opengl-appimage
-          path: dist/jellyframe-linux-${{ matrix.arch }}-opengl.AppImage
-          if-no-files-found: error
-          retention-days: 14
-          archive: false
-
-      - name: Upload Vulkan AppImage
-        uses: actions/upload-artifact@v7
-        with:
-          name: ${{ steps.date.outputs.date }}-jellyframe-linux-${{ matrix.arch }}-vulkan-appimage
-          path: dist/jellyframe-linux-${{ matrix.arch }}-vulkan.AppImage
+          name: ${{ steps.date.outputs.date }}-jellyframe-linux-${{ matrix.arch }}-appimage
+          path: dist/jellyframe-linux-${{ matrix.arch }}.AppImage
           if-no-files-found: error
           retention-days: 14
           archive: false

.github/workflows/build-windows.yml

@@ -57,20 +57,26 @@ jobs:
       - name: Export Windows build
         run: |
           New-Item -ItemType Directory -Force dist/windows | Out-Null
-          & $env:GODOT --headless --xr-mode off --path . --export-release 'Windows SteamVR' dist/windows/jellyframe.exe
+          & $env:GODOT --headless --xr-mode off --path . --export-release 'Windows' dist/windows/jellyframe.exe
           if ($LASTEXITCODE -ne 0) { throw 'Windows export failed.' }
 
       - name: Verify Windows export files
         run: |
-          foreach ($file in 'jellyframe.exe', 'jellyframe.pck', 'jellyframe_mpv.dll', 'libmpv-2.dll') {
+          foreach ($file in 'jellyframe.exe', 'jellyframe.pck', 'jellyframe_mpv.dll', 'libmpv-2.dll', 'avcodec-62.dll', 'avformat-62.dll', 'avutil-60.dll', 'swscale-9.dll', 'swresample-6.dll') {
             if (-not (Test-Path "dist/windows/$file")) { throw "Export is missing $file." }
           }
 
+      - name: Verify exported renderer settings
+        run: |
+          & $env:GODOT --headless --xr-mode off --main-pack dist/windows/jellyframe.pck --script tests/test_export_renderer.gd
+          if ($LASTEXITCODE -ne 0) { throw 'Windows renderer settings check failed.' }
+
       - name: Copy Windows licenses
         run: |
           New-Item -ItemType Directory -Force dist/windows/licenses | Out-Null
-          Copy-Item build/desktop/deps/godot-cpp-godot-4.5-stable/LICENSE.md dist/windows/licenses/godot-cpp.txt
-          Copy-Item native/pc/THIRD_PARTY.md dist/windows/licenses/
+          Copy-Item build/desktop/deps/godot-cpp-godot-4.5-stable/LICENSE.md dist/windows/licenses/godot-cpp.md
+          Copy-Item LICENSING.md dist/windows/licenses/
+          Copy-Item build/desktop/deps/ffmpeg-n8.1.3-18-g46d899d7a0-win64-gpl-shared-8.1/LICENSE.txt dist/windows/licenses/ffmpeg.txt
 
       - name: Upload Windows build
         uses: actions/upload-artifact@v7

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Jellyframe
 
-You can contribute bug fixes, playback improvements, VR controls, tests, or documentation, or report problems you find while using Jellyframe.
+Contributions can include bug fixes, playback improvements, VR controls, tests, and documentation. Reports of problems you find while using Jellyframe are also welcome.
 
 Read the [README](README.md) for the project's scope and current limitations, and [Build from source](DEVELOPMENT.md) for setup, build commands, tests, and the code layout.
 
@@ -10,31 +10,32 @@ Search the repository's issues before opening a new one. Include:
 
 - The Jellyframe build or commit you used.
 - Your operating system, headset, and OpenXR runtime, where applicable.
+- Your GPU and the OpenGL or Vulkan renderer used for PC playback.
 - Your Jellyfin server version.
 - Steps to reproduce the problem, what you expected, and what happened.
 - Relevant logs or screenshots.
 
-For playback problems, include the container format, video and audio codecs, resolution, and whether the video is 2D or side-by-side 3D, along with whether Jellyfin played the file directly or converted it during playback, if you know.
+For playback problems, include the container format, video and audio codecs, resolution, frame rate, HDR format, and stereo or panoramic layout. If you know whether Jellyfin played the file directly or converted it, include that too.
 
 Remove passwords, access tokens, and private server details from logs before posting them. A short sample you have permission to share can help reproduce a playback problem.
 
 ## Propose a feature
 
-Before implementing a large change, open an issue explaining what you want to do in the app, what gets in the way, and how the change would help, including any platform or headset requirements.
+Before implementing a large change, open an issue. Explain what you want to do in the app, what gets in the way, and how the change would help. Include any platform or headset requirements.
 
 Small fixes and documentation corrections can go straight into a pull request.
 
 ## Make a change
 
-Fork the repository and create a branch for your change, keeping each pull request focused on one problem so reviewers can understand and test it.
+Fork the repository and create a branch for your change. Keep each pull request focused on one problem so reviewers can understand and test it.
 
-Follow the style of the surrounding code, use clear names, and keep functions small, adding comments only when the code cannot explain the reason for a decision. Write code, comments, and documentation in English.
+Follow the style of the surrounding code. Use clear names and keep functions small. Add comments when the code cannot explain the reason for a decision. Write code, comments, and documentation in English.
 
 Update the documentation when you change setup steps, controls, or app behaviour. Keep generated builds, downloaded dependencies, credentials, and local editor settings out of your commits.
 
 ## Test your change
 
-Run the checks that cover the code you changed, using the [development guide](DEVELOPMENT.md) to find the core, HTTP, decoder, streaming, and headset tests. Add a regression test when it can reproduce the bug or check the new behaviour.
+Run the checks that cover the code you changed. The [development guide](DEVELOPMENT.md) lists the core, HTTP, decoder, streaming, and headset tests. Add a regression test when it can reproduce the bug or check the new behaviour.
 
 Desktop preview with `--xr-mode off` can check layout and library navigation, but cannot verify VR comfort, tracking, controller behaviour, stereo output, or video playback. Decoder and streaming tests check playback without a headset and cannot verify how it looks or behaves in VR.
 
@@ -52,6 +53,4 @@ Explain the problem and what your change does, link any related issue, and list
 
 ## Licence
 
-Submit code contributions under the project's GPL-3.0-only licence, and include the licence, attribution, and source of any new assets or dependencies. See [Licence and attribution](LICENSING.md) and the full [licence text](LICENSE).
-
-Thank you for contributing to Jellyframe.
+Submit code contributions under the project's GPL-3.0-only licence. Include the licence, attribution, and source of any new assets or dependencies. See [Licence and attribution](LICENSING.md) and the full [licence text](LICENSE).

DEVELOPMENT.md

@@ -1,28 +1,18 @@
-# Build from source
+# Development
 
-Jellyframe uses Godot and OpenXR, with an Android video plugin and a shared libmpv video plugin for Windows and Linux.
+Jellyframe uses Godot 4.7.2 and OpenXR. Install Godot and its matching export templates before building. Run the commands below from the project root, with `godot` on your `PATH`.
 
-## Android build requirements
+Build the native video plugin for your platform before importing the project. Close Jellyframe before rebuilding the plugin.
+
+## Build the Quest APK
+
+### Requirements
 
-- Godot 4.7.2 with matching Android export templates.
 - JDK 17.
 - Android SDK platforms 35 and 36, with build tools 36.1.0.
 - Gradle 8.10.2.
 
-The Android plugin compiles against Godot's 4.5.1 Android API and uses the Compatibility renderer because video playback requires an external OpenGL texture. Jellyframe uses a fixed Android codec profile and does not check which codecs the headset can decode, while Windows and Linux use libmpv for PC VR playback.
-
-## Build the Quest APK
-
-To build a Quest 3 debug APK, open **Actions > Build Android APK > Run workflow**, which builds the native video plugin, exports the APK, and checks its signature. The workflow needs no repository secrets and keeps the APK artifact for 14 days.
-
-Each workflow run creates a new debug signing key, so an installed APK signed with a different key must be uninstalled before you can install the new build. Uninstalling removes saved settings and sign-in, and these APKs are test builds rather than store releases.
-
-To build locally:
-
-1. Install the build requirements and accept the Android SDK licences.
-2. Set the Android SDK and Java SDK paths in Godot's editor settings.
-3. Select Project > Install Android Build Template.
-4. Run the build script with the paths to your installed tools:
+Set the Android SDK and Java SDK paths in Godot's editor settings, accept the Android SDK licences, and select **Project > Install Android Build Template**.
 
 On Linux, install `curl`, `unzip`, and `sha256sum`, then run:
 
@@ -32,7 +22,7 @@ export ANDROID_HOME='/path/to/android-sdk'
 GODOT='/path/to/godot' GRADLE='/path/to/gradle' bash tools/build-android.sh
 ```
 
-If `godot` and `gradle` are on your `PATH`, omit the `GODOT` and `GRADLE` overrides. The script also accepts `ANDROID_SDK_ROOT` when `ANDROID_HOME` is unset. The Android workflow uses this Bash script.
+Omit `GODOT` and `GRADLE` if both tools are on your `PATH`. The script also accepts `ANDROID_SDK_ROOT` when `ANDROID_HOME` is unset.
 
 On Windows, use PowerShell:
 
@@ -42,93 +32,89 @@ On Windows, use PowerShell:
   -AndroidSdk 'C:/tools/android-sdk' -JavaHome 'C:/tools/jdk-17'
 ```
 
-The script creates `dist/jellyframe-android.apk` for installation on your headset and downloads Godot OpenXR Vendors 5.1.0 for Quest passthrough support. It checks the archive's SHA-256 checksum and includes the vendor licences in the APK, keeping the downloaded addon in the ignored `addons/godotopenxrvendors` directory.
+The scripts build the Android plugin and export `dist/jellyframe-android.apk`. They download and verify Godot OpenXR Vendors for Quest passthrough support.
 
-## Build and test on Windows
+To build through GitHub Actions, select **Actions > Build Android APK > Run workflow**. Each run creates a new debug signing key. If it differs from the installed APK's key, uninstall the old build first. Uninstalling removes saved settings and sign-in.
 
-To build the Windows SteamVR app locally, install Godot 4.7.2 with matching export templates and Python 3.12. Build the PC plugin before importing or exporting the project:
+## Build on Windows
+
+Install Python 3.12, then build the PC plugin and export the app:
 
 ```powershell
 ./tools/build-pc-video.ps1 -Python 'C:/path/to/python.exe'
 New-Item -ItemType Directory -Force dist/windows
 godot --headless --xr-mode off --path . --editor --import --quit
-godot --headless --xr-mode off --path . --export-release 'Windows SteamVR' dist/windows/jellyframe.exe
+godot --headless --xr-mode off --path . --export-release 'Windows' dist/windows/jellyframe.exe
 ```
 
-The plugin build script downloads pinned CMake, LLVM-MinGW, godot-cpp, and libmpv archives into `build/desktop`, verifies their checksums, and generates `addons/jellyframe_mpv` without requiring a system-wide compiler installation. Close running Jellyframe instances before rebuilding; Git ignores the generated plugin, and Android exports exclude it.
+The plugin script downloads pinned build tools and libraries into `build/desktop`, verifies their checksums, and generates `addons/jellyframe_mpv`. You do not need a system-wide compiler installation.
 
-The Windows workflow builds the plugin, exports the app, verifies the output files, and uploads the build. Tests run separately using the commands below. Build commands disable OpenXR, while the exported app keeps it enabled. The workflow needs no repository secrets, and GitHub keeps its build artifacts for 14 days.
+The output is in `dist/windows`. Keep all exported files together. Include the third-party licences when distributing a build, following the copy steps in the [Windows workflow](.github/workflows/build-windows.yml).
 
-After building the PC plugin, run its decoder tests without a headset:
+## Build on Linux x64 or ARM64
 
-```powershell
-godot --headless --xr-mode off --path . --script tests/test_pc_video.gd
-python tests/test_pc_streaming.py --godot 'C:/path/to/godot_console.exe'
-```
-
-With SteamVR and your headset running, test the stereo screen and controllers:
-
-```powershell
-godot --path . --script tests/test_steamvr_video.gd
-```
-
-The headset test loops a labelled stereo clip for two minutes so you can close one eye at a time to check the LEFT and RIGHT labels, then press A or B to open the playback controls. The decoder tests cover resume, pause, seeking, completion, reopening, and errors.
-
-Import `project.godot` into Godot, or run:
-
-```powershell
-godot --path . --xr-mode off
-```
-
-Connect to your Jellyfin server to browse your library in desktop mode, which does not save sessions or play videos.
-
-## Build Linux x64 or ARM64
-
-Build natively on the target architecture with Godot 4.7.2 and matching export templates. On Ubuntu, install the build dependencies:
+Build natively on the target architecture. On Ubuntu 24.04, install the dependencies and build the PC plugin:
 
 ```sh
-sudo apt-get install build-essential cmake pkg-config python3 curl unzip libmpv-dev
+sudo apt-get install build-essential cmake pkg-config python3 curl unzip libmpv-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
 bash tools/build-pc-video.sh
 godot --headless --xr-mode off --path . --editor --import --quit
 ```
 
-The script detects x64 or ARM64, downloads and verifies the godot-cpp bindings, and builds the matching plugin in `addons/jellyframe_mpv` using the system libmpv development package. Close Jellyframe before rebuilding its plugin.
+The script detects x64 or ARM64 and generates `addons/jellyframe_mpv`. It downloads and verifies godot-cpp, and uses the system libmpv and FFmpeg development packages. FFmpeg 6 or newer is required.
 
-For x64:
+Export for x64:
 
 ```sh
 mkdir -p dist/linux-x86_64
-godot --headless --xr-mode off --path . --export-release 'Linux x64 OpenXR' dist/linux-x86_64/jellyframe-opengl.x86_64
-godot --headless --xr-mode off --path . --export-release 'Linux x64 Vulkan' dist/linux-x86_64/jellyframe-vulkan.x86_64
+godot --headless --xr-mode off --path . --export-release 'Linux x64' dist/linux-x86_64/jellyframe.x86_64
 ```
 
-For ARM64:
+Export for ARM64:
 
 ```sh
 mkdir -p dist/linux-arm64
-godot --headless --xr-mode off --path . --export-release 'Linux ARM64 OpenXR' dist/linux-arm64/jellyframe-opengl.arm64
-godot --headless --xr-mode off --path . --export-release 'Linux ARM64 Vulkan' dist/linux-arm64/jellyframe-vulkan.arm64
+godot --headless --xr-mode off --path . --export-release 'Linux ARM64' dist/linux-arm64/jellyframe.arm64
 ```
 
-The OpenXR presets select OpenGL Compatibility. The Vulkan presets select the Mobile renderer and Vulkan through custom feature tags. Both executables embed their own resources and share the native decoder library in the output folder.
+Keep the executable and native decoder `.so` file together.
 
-**Build Linux** uses native `ubuntu-24.04` and `ubuntu-24.04-arm` runners. Each job builds its plugin, exports the OpenGL and Vulkan apps, checks output files and decoder dependencies, and packages a system-libraries archive plus separate OpenGL and Vulkan AppImages. Tests run separately using the commands below. The system-libraries artifact is a tar archive that preserves Linux executable permissions; GitHub keeps them for 14 days, and the workflow needs no repository secrets.
+### Package an AppImage
 
-To package AppImages after exporting and copying the licenses into `dist/linux-<arch>`, install `patchelf` and run:
+Install `patchelf`. Copy the licences into the export folder as shown below for x64. Replace `x86_64` with `arm64` for an ARM64 build.
 
 ```sh
+cp -r build/linux/x86_64/licenses dist/linux-x86_64/
+cp LICENSE dist/linux-x86_64/licenses/jellyframe.txt
+cp LICENSING.md dist/linux-x86_64/licenses/
 bash tools/package-linux-appimages.sh x86_64
-# On an ARM64 build machine:
-bash tools/package-linux-appimages.sh arm64
 ```
 
-The packager reuses the decoder library bundler, includes its license notices and package manifest, and leaves graphics drivers and OpenXR to the host. It downloads appimagetool 1.9.1 for the selected architecture, verifies its SHA-256 checksum, and runs it without requiring FUSE. appimagetool downloads its AppImage runtime during packaging, so packaging requires network access. Outputs are `dist/jellyframe-linux-<arch>-opengl.AppImage` and `dist/jellyframe-linux-<arch>-vulkan.AppImage`.
+The packager bundles decoder libraries and licence notices. It needs network access to download appimagetool and its AppImage runtime. The output is `dist/jellyframe-linux-<arch>.AppImage`. The host supplies graphics drivers and OpenXR.
 
-The decoder and headset tests in [Build and test on Windows](#build-and-test-on-windows) also work on Linux, where you should use `python3` for the HTTP streaming test and pass the path to your Linux Godot executable.
+## Run the app during development
+
+Import `project.godot` into Godot, or launch the desktop library preview:
+
+```sh
+godot --path . --xr-mode off
+```
+
+Desktop preview supports sign-in and library browsing. Use a headset for video playback in the app.
+
+Windows and Linux default to Vulkan and fall back to OpenGL if Vulkan cannot initialize. To select OpenGL manually:
+
+```sh
+godot --path . --rendering-method gl_compatibility
+```
+
+For VR, connect your headset and start its OpenXR runtime before launching. See [installation](INSTALLATION.md) for runtime setup and [usage](USAGE.md) for controls.
 
 ## Run the core and HTTP tests
 
-```powershell
+Build the native plugin and import the project before running tests:
+
+```sh
 godot --headless --xr-mode off --path . --editor --import --quit
 godot --headless --xr-mode off --path . --script tests/test_core.gd
 godot --headless --xr-mode off --path . --script tests/test_360_video.gd
@@ -136,17 +122,96 @@ godot --headless --xr-mode off --path . --script tests/test_http.gd
 godot --headless --xr-mode off --path . --script tests/test_autoplay.gd
 godot --headless --xr-mode off --path . --script tests/test_player_return.gd
 godot --headless --xr-mode off --path . --script tests/test_player_tooltips.gd
+godot --headless --xr-mode off --path . --script tests/test_player_loading.gd
+godot --headless --xr-mode off --path . --script tests/test_photos.gd
 ```
 
+## Test PC video
+
+These tests work on Windows and Linux. The examples use Windows paths. On Linux, use `python3` and replace the executable paths. The Python video tests need FFmpeg. Keep `ffprobe` beside the FFmpeg executable for the buffering tests.
+
+### Decoder and streaming
+
+```powershell
+godot --headless --xr-mode off --path . --script tests/test_pc_video.gd
+python tests/test_pc_streaming.py --godot 'C:/path/to/godot_console.exe'
+```
+
+### GPU playback and transitions
+
+Run these with a graphics context:
+
+```powershell
+godot --xr-mode off --rendering-method gl_compatibility --path . --script tests/test_pc_gpu_video.gd
+godot --xr-mode off --rendering-method mobile --rendering-driver vulkan --path . --script tests/test_pc_gpu_video.gd
+godot --xr-mode off --rendering-method gl_compatibility --path . --script tests/test_pc_video_transitions.gd
+godot --xr-mode off --rendering-method mobile --rendering-driver vulkan --path . --script tests/test_pc_video_transitions.gd
+godot --xr-mode off --rendering-method mobile --rendering-driver vulkan --path . --script tests/test_pc_yuv_material.gd
+python tests/test_pc_vulkan.py --godot 'C:/path/to/godot_console.exe' --ffmpeg 'C:/path/to/ffmpeg.exe'
+python tests/test_pc_hdr.py --godot 'C:/path/to/godot_console.exe' --ffmpeg 'C:/path/to/ffmpeg.exe'
+python tests/test_pc_streaming.py --godot 'C:/path/to/godot_console.exe' --vulkan
+```
+
+The transition test checks the black screen before playback and after stopping, then checks that a reopened video becomes visible. The Vulkan and HDR tests generate video fixtures and check color conversion, including HDR-to-SDR tone mapping.
+
+PC Vulkan playback uploads the decoded YUV planes and samples them directly in the video material. Color conversion and HDR tone mapping run while drawing the screen or panorama, without a full-resolution RGBA intermediate texture. Hardware frames still pass through system memory before upload. OpenGL and software playback use the RGB material path. The YUV material test checks decoder padding, rotation, and stereo eye boundaries.
+
+### Performance
+
+Use a video long enough for the sample plus one second of warm-up:
+
+```powershell
+godot --xr-mode off --rendering-method mobile --rendering-driver vulkan --path . --script tests/test_pc_video_performance.gd -- --video='C:/videos/8k.mp4' --seconds=20 --minimum-fps=57
+```
+
+The test reports presentation rate, dropped frames, decoder and transfer timings, and main-loop frame times. It does not measure SteamVR performance.
+
+### Buffering and recovery
+
+Supply a video with audio and at least 20 seconds of content:
+
+```powershell
+python tests/test_pc_video_recovery.py --godot 'C:/path/to/godot_console.exe' --ffmpeg 'C:/path/to/ffmpeg.exe' --video 'C:/videos/8k-with-audio.mp4'
+python tests/test_pc_video_recovery.py --godot 'C:/path/to/godot_console.exe' --ffmpeg 'C:/path/to/ffmpeg.exe' --video 'C:/videos/8k-with-audio.mp4' --expect-buffer-free
+```
+
+The first command checks recovery, audio synchronization, and a manual pause during interrupted delivery. The second checks that read-ahead absorbs a short interruption without buffering. Omitting `--video` generates a 4K HEVC fixture and requires FFmpeg's NVIDIA NVENC encoder.
+
+### Headset playback
+
+Start SteamVR and connect your headset, then run:
+
+```sh
+godot --rendering-method mobile --rendering-driver vulkan --path . --script tests/test_steamvr_video.gd
+```
+
+The test loops a labelled stereo clip for two minutes. Close one eye at a time to check the LEFT and RIGHT labels. Press A to open playback controls. When signed in, press B to browse the library during playback. Replace the Vulkan arguments with `--rendering-method gl_compatibility` to test OpenGL.
+
+Desktop and headless tests do not verify headset tracking, controller behavior, stereo output, or playback performance in VR.
+
+### Playback logs
+
+To record a Vulkan playback log, run the exported app with SteamVR active:
+
+```powershell
+New-Item -ItemType Directory -Force logs | Out-Null
+$env:JELLYFRAME_VIDEO_STATS = '1'
+.\dist\windows\jellyframe.exe --rendering-method mobile --rendering-driver vulkan --log-file (Join-Path $PWD 'logs/vulkan-playback.log')
+```
+
+Set `JELLYFRAME_PC_RENDERER=software` to force the software fallback for troubleshooting. Remove access tokens and private server details before sharing logs.
+
 ## Check 180° and 360° rendering
 
-To render synthetic panoramas, check top-bottom eye selection, and check that the view behind a 180° video stays dark on desktop:
-
-```powershell
+```sh
 godot --xr-mode off --path . --script tests/capture_360.gd
 ```
 
-The check tests the PC shader with a generated texture and saves panorama and settings previews in `dist`, without enabling desktop video playback. It cannot validate headset tracking, Android textures, or stereo output in a headset.
+This renders synthetic panoramas to check top-bottom eye selection and the dark area behind a 180° video. It saves previews in `dist` and does not test Android textures or headset stereo output.
+
+## GitHub Actions
+
+The [Android](.github/workflows/build-android.yml), [Windows](.github/workflows/build-windows.yml), and [Linux](.github/workflows/build-linux.yml) workflows build and upload their platform packages. They need no repository secrets and keep artifacts for 14 days. Run the playback tests separately with the commands above.
 
 ## Code layout
 
@@ -154,5 +219,5 @@ The check tests the PC shader with a generated texture and saves panorama and se
 - `scripts/vr` handles environments, controller pointing, and recentering.
 - `scripts/player` selects Android playback or PC VR playback.
 - `native/android` contains the Android decoder.
-- `native/pc` contains the libmpv PC decoder.
+- `native/pc` contains the libmpv OpenGL renderer and FFmpeg Vulkan decoder.
 - `scripts/core` contains screen settings and stereo geometry.

INSTALLATION.md

@@ -1,59 +1,67 @@
 # Install and start Jellyframe
 
-## What you need
+Download the package for your platform from **Assets** on the [latest release page](https://github.com/Cuteminded/jellyframe/releases/latest).
 
-- Access to a Jellyfin server and an account on that server.
-- For Quest, a Quest 3 with developer mode and USB debugging enabled, plus a computer to install the app.
-- For Windows or Linux, a computer and a headset with a compatible OpenXR runtime.
+You need a Jellyfin server and an account to use the app. To build Jellyframe yourself, follow the [build instructions](DEVELOPMENT.md).
 
-The initial Jellyfin compatibility target is version 10.11.6. Use HTTPS when connecting to a server outside your home network.
+## Quest 3
 
-## Try it on Quest 3
+Enable developer mode and USB debugging on your headset. Install Android's `adb` tool on your computer and download `jellyframe-android.apk`.
 
-Download a test APK from a successful **Build Android APK** run in the repository's **Actions** tab by opening **Artifacts**, downloading `jellyframe-android-debug-<run number>`, and extracting the ZIP. To build the APK yourself, follow the [build instructions](DEVELOPMENT.md).
-
-After downloading or building the APK, connect your headset to your computer, approve USB debugging in the headset, and install it with Android's `adb` tool:
+Connect your headset to your computer by USB and approve USB debugging in the headset. Run these commands from the folder containing the APK:
 
 ```powershell
 adb devices
-adb install -r dist/jellyframe-android.apk
+adb install -r jellyframe-android.apk
 ```
 
-Open Jellyframe from Unknown Sources in your headset, enter your Jellyfin server address, and sign in with your account or Quick Connect. Select a library and choose a title to watch.
+Open Jellyframe from **Unknown Sources** in your headset.
 
-## Try it on Windows with SteamVR
+## Windows with SteamVR
 
-Open **Actions > Build Windows > Run workflow** in the repository, then download `jellyframe-windows-<run number>` from **Artifacts** after the build succeeds. Extract the entire ZIP and keep the executable, PCK, and any DLLs together in the same folder.
+Download the Windows ZIP and extract the entire archive. Keep all files together in the extracted folder.
 
-Install SteamVR, connect your headset, and set SteamVR as the active OpenXR runtime in SteamVR's **Settings > OpenXR**. Start SteamVR and run `jellyframe.exe`; Godot uses the active OpenXR runtime, as described in the [Godot Windows PCVR guide](https://www.khronos.org/assets/uploads/developers/presentations/Godot_guide_to_OpenXR_for_Windows_PCVR.pdf).
+Install SteamVR and connect your headset. In SteamVR's **Settings > OpenXR**, set SteamVR as the active OpenXR runtime. Start SteamVR, then run `jellyframe.exe`.
 
-Sign in to Jellyfin and select a title to play it in VR, using the same pause, seek, resume, and side-by-side 3D controls as the Quest build. Keep `jellyframe_mpv.dll` and `libmpv-2.dll` beside the executable.
+If Jellyframe cannot start with Vulkan, try OpenGL from PowerShell in the extracted folder:
 
-## Try it on Linux x64 or ARM64
+```powershell
+.\jellyframe.exe --rendering-method gl_compatibility
+```
 
-Open **Actions > Build Linux > Run workflow** and download an OpenGL or Vulkan AppImage for your computer's architecture, `x86_64` or `arm64`. AppImages replace the bundled-libraries archives and include libmpv and the bundled decoder libraries.
+## Linux x64 or ARM64
 
-Make the downloaded AppImage executable and launch it. For x64 OpenGL:
+Download the AppImage for your computer's architecture, `x86_64` or `arm64`. The builds target Ubuntu 24.04 and need compatible system libraries, graphics drivers, and an OpenXR runtime.
+
+Connect your headset and start your OpenXR runtime. On x64, set SteamVR as the active runtime. Make the AppImage executable and launch it:
 
 ```sh
-chmod +x jellyframe-linux-x86_64-opengl.AppImage
-./jellyframe-linux-x86_64-opengl.AppImage
+chmod +x jellyframe-linux-x86_64.AppImage
+./jellyframe-linux-x86_64.AppImage
 ```
 
-If OpenGL shows a black screen, download and run `jellyframe-linux-x86_64-vulkan.AppImage`. Use the Vulkan AppImage when adding Jellyframe to Steam on SteamOS. For ARM64, use the corresponding `jellyframe-linux-arm64-opengl.AppImage` or `jellyframe-linux-arm64-vulkan.AppImage`.
+For ARM64, replace the filename with `jellyframe-linux-arm64.AppImage`. On SteamOS, add the AppImage to Steam as a non-Steam game.
+
+If Jellyframe cannot start with Vulkan, try OpenGL:
+
+```sh
+./jellyframe-linux-x86_64.AppImage --rendering-method gl_compatibility
+```
 
 If mounting an AppImage fails because FUSE is unavailable, run it with `--appimage-extract-and-run`.
 
-The builds target Ubuntu 24.04. AppImages still need compatible system libraries, graphics drivers, and an OpenXR runtime; they do not guarantee compatibility with older Linux distributions. Start your OpenXR runtime with the headset connected before opening Jellyframe, and set SteamVR as the active runtime on x64. The runtime must support the selected graphics API. SteamVR on ARM64 and standalone Steam Frame support still need headset testing.
+### Use system libraries instead of an AppImage
 
-The `system-libs` archive remains available if you prefer to install libmpv yourself. It contains both renderers. On Ubuntu x64:
+Download the `system-libs` archive for your architecture. On Ubuntu x64, install libmpv, extract the archive, and launch Jellyframe:
 
 ```sh
 sudo apt-get install libmpv2
 tar -xzf jellyframe-linux-x86_64-system-libs.tar.gz
-./jellyframe-opengl.x86_64
+./jellyframe.x86_64
 ```
 
-Keep both executables and the `.so` file together. For ARM64, use `jellyframe-linux-arm64-system-libs.tar.gz` and launch `./jellyframe-opengl.arm64` or `./jellyframe-vulkan.arm64`.
+Keep the executable and the `.so` file together. For ARM64, use `jellyframe-linux-arm64-system-libs.tar.gz` and launch `./jellyframe.arm64`.
 
-Sign in and play a title using the same VR controls as Windows; desktop preview with `--xr-mode off` does not play video.
+## After installation
+
+Follow the [usage guide](USAGE.md) to sign in and play a video. See the [current limitations](README.md#current-limitations) for platform and headset compatibility.

LICENSING.md

@@ -1,9 +1,42 @@
-# Licence and attribution
+# License and attribution
 
-Copyright (c) 2026 Cuteminded.
+Copyright © 2026 Cuteminded.
 
-Jellyframe's code is licensed under the [GNU General Public License, version 3 only](LICENSE), identified as `GPL-3.0-only`, while Godot and Android components retain their own licences.
+Jellyframe's source code is licensed under the [GNU General Public License v3.0 only](LICENSE) (`GPL-3.0-only`).
 
-The player and library buttons use Google's Material Symbols Rounded icons, and the Cinema environment uses Comicaroid's cinema interior under CC BY 4.0.
+## Third-party components
 
-Library artwork comes from your Jellyfin server and is not bundled with Jellyframe.
+Jellyframe uses third-party software and assets under their own licenses:
+
+- Godot and Android components retain their original licenses and copyright notices.
+- Icons in the player and library come from [Google's Material Symbols Rounded](https://github.com/google/material-design-icons).
+- The virtual cinema is based on [Comicaroid's Cinema/Movie Theater Interior](https://sketchfab.com/3d-models/cinemamovie-theater-interior-dcaf6cdebcad4f03879c24186da257ee), licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
+
+## Media artwork
+
+Jellyframe retrieves movie posters, backdrops, and other media artwork from the user's Jellyfin server. It does not include these assets in its source code or distribute them with the app.
+
+# PC playback dependencies
+
+The Windows build includes third-party libraries for video playback and integration with Godot.
+
+The build bundles libmpv from [shinchiro's Windows builds](https://github.com/shinchiro/mpv-winbuild-cmake/releases/tag/20261010), release `20261010`, based on mpv revision `b2c255c13e`. It also links against godot-cpp version `godot-4.5-stable`.
+
+The Vulkan video backend also links against FFmpeg. Windows builds bundle the shared libraries from [BtbN's release of October 19, 2026](https://github.com/BtbN/FFmpeg-Builds/releases/tag/autobuild-2026-10-19-13-06), archive `ffmpeg-n8.1.3-18-g46d899d7a0-win64-gpl-shared-8.1.zip`.
+
+This archive uses FFmpeg revision `46d899d7a0` with GPL components enabled. The exported app includes its GPLv3 license in `licenses/ffmpeg.txt`.
+
+The [build scripts](https://github.com/BtbN/FFmpeg-Builds) describe the configuration and dependency sources. The [FFmpeg source](https://github.com/FFmpeg/FFmpeg/tree/46d899d7a0) is available separately.
+
+Linux builds use distribution FFmpeg libraries. Packaging includes the notices for the bundled libraries.
+
+## Sources and attribution
+
+Sources, build configurations, and license information:
+
+- [libmpv Windows binary release, 20261010](https://github.com/shinchiro/mpv-winbuild-cmake/releases/tag/20261010)
+- [mpv source code and copyright information, b2c255c13e](https://github.com/mpv-player/mpv/tree/b2c255c13e)
+- [Windows decoder build scripts and dependency sources](https://github.com/shinchiro/mpv-winbuild-cmake)
+- [godot-cpp source code, Godot 4.5 stable](https://github.com/godotengine/godot-cpp/tree/godot-4.5-stable)
+
+Each component keeps its own license and copyright notices.

README.md

@@ -1,23 +1,51 @@
 <img src="assets/logo/jellyframe-wordmark.png" alt="Jellyframe" style="width:400px;"/>
+
 Watch your Jellyfin movies and shows on a virtual screen in VR.
 
-Jellyframe is a free, open source app that connects to your Jellyfin server so you can browse your library, choose a title, and position the screen where you want it. Your server supplies the movies and shows.
+Jellyframe is a free, open source app for browsing your Jellyfin library and watching videos in VR. Choose a title and position the screen where you want it. Your Jellyfin server supplies the movies and shows.
+
+> I am still on the reservation queue for Steam Frame and have not received the device yet. 
+>
+> When I do, I will update the documentation and testing status accordingly.
 
 ## From JellyQuest to Jellyframe
 
-This project started as JellyQuest, a Jellyfin VR app for the Quest 3. I renamed it Jellyframe because I plan to switch to Steam Frame, which is now the main target for future development. I do not have a Steam Frame yet, so I cannot test it on the headset, but I am still developing the Quest version under the Jellyframe name.
+This project started as JellyQuest, a Jellyfin VR app for the Quest 3. I renamed it Jellyframe because I plan to switch to Steam Frame.
 
-## What you can do
+I'm still undecided about keeping the name. It ties the app to Steam Frame, even though I want to support other VR platforms too. 
+I haven't come up with a better name yet, so Jellyframe stays for now. 
+Suggestions for a name that isn't tied to a specific platform are welcome.
 
-Browse and search your Jellyfin libraries, watch 2D, side-by-side 3D, 180° and 360° video, and use your controllers to select titles and control playback. Choose a dark background, a cinema, or passthrough on supported devices, and let episodes play automatically in series order.
+I want Jellyframe to work on as many VR platforms as possible, including:
 
-See [Using Jellyframe](USAGE.md) for controls, screen settings, environments, and sign-in behaviour.
+- [SteamVR](https://store.steampowered.com/steamvr)
+- [Android XR](https://www.android.com/intl/en_us/xr/)
+- [Quest headsets running Horizon OS](https://www.meta.com/quest/)
 
-## Get started
+Steam Frame remains the primary development target, with support for other platforms wherever possible.
 
-You need a Jellyfin server and an account on that server; the initial compatibility target is Jellyfin 10.11.6.
+## What has been tested
 
-Follow the [installation guide](INSTALLATION.md) to download a build, install the app, and sign in on Quest 3, Windows with SteamVR, or Linux x64 and ARM64 with OpenXR.
+- Browsing and searching Jellyfin libraries.
+- Selecting titles and controlling playback with controllers.
+- Dark backgrounds, cinema environments, and passthrough on supported devices.
+- 2D, side-by-side and top-bottom 3D, 180° and 360° video.
+- Automatic episode playback in series order.
+- HDR, 1080p, 4K, and 8K video playback.
+
+## Current limitations
+
+- Steam Frame installation and playback remain untested.
+- Linux VR playback was previously tested on a Steam Machine running SteamOS with Vulkan and SteamVR. The new native Vulkan decoder, HDR conversion, and 4K/8K playback still need Linux headset testing.
+- ARM64 and other Linux systems also need headset testing.
+- Native HDR output and display calibration are not implemented.
+- Some files need conversion by your Jellyfin server during playback. This can fail if the server cannot handle the conversion.
+- Audio and subtitle selection, favourites, and collections are not available yet.
+- Manually marking titles as watched and automatically hiding playback controls are planned but not available yet.
+
+## Will it be available in a store?
+
+If we think Jellyframe is ready for a wider release, then yes. I'd be happy to put in the work to make it available on Steam or the Meta Store.
 
 ## Documentation
 
@@ -27,19 +55,6 @@ Follow the [installation guide](INSTALLATION.md) to download a build, install th
 - [Contributing](CONTRIBUTING.md)
 - [Licence and attribution](LICENSING.md)
 
-## Current limitations
-
-- 180° projection and top-bottom 3D still need headset validation.
-- Steam Frame installation and playback remain untested.
-- Linux VR playback has been tested on a Steam Machine running SteamOS, using Vulkan and SteamVR. ARM64 and other Linux systems still need headset testing.
-- CI playback checks run without a headset and do not verify tracking, controller input, or stereo output.
-- Desktop mode only shows the interface. PC video playback requires an active OpenXR session with a connected headset.
-- PC OpenGL builds render video on a worker thread into buffered GPU textures, with software video rendering as a fallback. Decoding can still copy frames through system memory, and Vulkan builds use the software video renderer. High-resolution playback needs performance testing, especially with 8K and full-SBS files.
-- Specific 4K HEVC and HDR videos still need testing; HDR playback relies on your Jellyfin server to convert the video to standard dynamic range with correct colours.
-- Some files need your Jellyfin server to convert the video during playback, which can fail if the server cannot handle the conversion.
-- Audio and subtitle selection, favourites, and collections are not available yet.
-- Marking titles as watched manually and hiding playback controls automatically are planned but not available yet.
-
 ## Licence
 
 Jellyframe uses GPL-3.0-only; see [Licence and attribution](LICENSING.md) for licence terms and third-party credits.

TODO.md

@@ -0,0 +1,111 @@
+# Jellyfin feature checklist
+
+This checklist compares Jellyframe with Jellyfin's user-facing features.
+Implementation does not mean a feature has been tested on every headset.
+
+- Checked items are implemented in the current source. 
+- Unchecked items are missing or incomplete.
+- Hardware validation is tracked separately below. 
+
+## Sign-in and accounts
+
+- [x] Connect to a custom Jellyfin server address.
+- [x] Sign in with a username and password.
+- [x] Sign in with Quick Connect after approval on another device.
+- [x] Restore a saved session without storing the password.
+- [x] Sign out and clear the saved session.
+- [ ] Save multiple servers and switch between them.
+- [ ] Switch between saved user accounts without signing out.
+- [ ] Discover Jellyfin servers on the local network.
+- [ ] Manage account settings and audio/subtitle language preferences.
+
+## Libraries and discovery
+
+- [x] Browse movies, series, and video items with posters and backdrops.
+- [x] Select individual server libraries from the sidebar.
+- [x] Show recently added titles on Home.
+- [x] Show a Continue watching row on Home.
+- [x] Search titles globally or within the selected library.
+- [x] Load more titles while scrolling.
+- [x] Sort libraries by name, rating, date, play count, or runtime, with ascending and descending order.
+- [x] Browse titles in random order.
+- [x] Browse series by season and episode.
+- [x] Display watched indicators and saved playback progress supplied by Jellyfin.
+- [ ] Show a Next up row for series. Automatic playback of the next episode already exists.
+- [ ] Filter by watched status, genre, year, or other metadata.
+- [ ] Add, remove, and browse favourites.
+- [ ] Browse collections.
+- [ ] Browse, create, and play playlists or a user-managed playback queue.
+- [ ] Show recommendations and similar titles.
+- [ ] Open actor or crew pages and browse their other titles.
+
+## Title details and watch history
+
+- [x] Show descriptions, release years, runtimes, ratings, and genres.
+- [x] Show cast and crew portraits, names, and roles.
+- [x] Show studio and video/audio stream information when available.
+- [x] Resume a movie or episode from its saved position.
+- [x] Start a partially watched title from the beginning.
+- [x] Report playback start, progress, pause state, and stop events to Jellyfin.
+- [ ] Manually mark a movie, episode, season, or series as watched or unwatched.
+- [ ] Select between multiple media versions. Playback currently uses the first returned media source.
+- [ ] Browse and play trailers and extras.
+
+## Video playback
+
+- [x] Play supported original video streams through Direct Play.
+- [x] Request server transcoding and play HLS streams.
+- [x] Retry with transcoding after a playback failure in Automatic mode.
+- [x] Choose Automatic, Original full resolution, or Transcoded playback.
+- [x] Choose 720p, 1080p, or 4K transcoding limits before starting playback.
+- [x] Pause, resume, stop, seek on the timeline, and skip backward or forward.
+- [x] Show loading and buffering feedback.
+- [x] Browse the library while the current video continues playing.
+- [x] Play the next available episode automatically after a cancellable countdown.
+- [x] Manually skip intros, credits, recaps, and previews when the server supplies media segments. Requires the Jellyfin 10.10+ API and a segment provider such as Intro Skipper.
+- [ ] Enable Direct Stream/remuxing. Playback requests currently set `EnableDirectStream` to `false`.
+- [ ] Select audio tracks and languages. The audio/subtitle control is disabled.
+- [ ] Display and select embedded or external subtitles. The playback profile currently advertises no subtitle support.
+- [ ] Adjust subtitle appearance and timing.
+- [ ] Browse chapters and jump to a selected chapter.
+- [ ] Change playback speed.
+- [ ] Change playback quality during an active session.
+- [ ] Automatically hide playback controls after inactivity.
+- [ ] Download media for offline playback.
+
+## Other Jellyfin features
+
+These extend beyond Jellyframe's current movie and series focus.
+
+- [x] View photos.
+- [x] Show loading feedback when opening photos from the library and switching photos.
+- [ ] View slideshows.
+- [ ] Read books and comics.
+- [ ] Watch live TV and browse the programme guide.
+- [ ] Join or host SyncPlay sessions.
+- [ ] Receive remote playback commands from other Jellyfin clients.
+
+## Jellyframe VR features
+
+These are Jellyframe features rather than Jellyfin feature gaps.
+
+- [x] Browse and control playback with VR controllers and an on-screen keyboard.
+- [x] Adjust screen width, distance, height, and curvature in supported environments.
+- [x] Choose Void, Cinema, Theatre, or supported-device Passthrough environments.
+- [x] Select 2D, half-SBS, full-SBS, and top-bottom layouts, with an eye-swap option.
+- [x] Select flat-screen, 180-degree, or 360-degree projection, with automatic detection for supported metadata and filenames.
+- [x] Save screen, environment, library sorting, and playback quality settings.
+- [ ] Implement native HDR output and display calibration.
+
+## Hardware validation
+
+- [ ] Verify installation and playback on Steam Frame.
+- [ ] Verify installation and playback on Android XR.
+- [x] Confirm Quest 3 HLS seeking and resume after the timeline fix.
+- [x] Verify top-bottom stereo and eye swapping on Quest 3.
+- [x] Verify stereoscopic 180-degree projection and recentering on Quest 3.
+- [x] Verify Quest 3 HDR content playback.
+- [x] Verify PC OpenGL HDR playback in a headset.
+- [x] Verify photo loading feedback on Quest 3, both from the library and between photos.
+- [ ] Verify ARM64 and other Linux configurations on headsets.
+- [ ] Verify the new native Vulkan decoder, HDR conversion, and 4K/8K playback on Linux with a headset.

USAGE.md

@@ -1,50 +1,154 @@
 # Using Jellyframe
 
-## Browsing and playback
+1. Enter the address you normally use to open Jellyfin, such as `https://jellyfin.example.com`. If someone else runs the server, ask them for the address.
+2. Enter your Jellyfin username and password.
+3. Select **Sign in**.
 
-- Sign in with your Jellyfin username and password or Quick Connect.
-- Browse and search your libraries, view title details, and continue watching.
-- Watch 2D movies and side-by-side 3D videos.
-- Watch equirectangular 180° and 360° videos in 2D, side-by-side 3D, or top-bottom 3D.
-- Resize the screen and adjust its distance, height, and curvature.
-- Recenter the screen in your viewing direction.
-- Watch against a dark background, in a cinema, or with your room visible through passthrough.
-- Use your controllers to select titles, type, pause, and skip through a video, or point at a player control to see its label beneath the buttons.
-- Use the Library button to return to the selected movie or series, keeping the current season open for a series. Selecting the active title returns to playback.
-- When an episode ends, a 5-second countdown appears before the next available episode starts in series order, including across seasons. Cancel the countdown to return to your library.
+To use **Quick Connect**, select it and note the code Jellyframe displays. Open Jellyfin on your phone or computer, sign in, and approve that code using Quick Connect.
 
-Jellyframe supports one server and one user at a time, saves your screen settings, and remembers your sign-in without storing your password. On PC, it stores the sign-in token in `session.cfg` in Godot's local user-data folder.
+Jellyframe remembers your sign-in without saving your password. Select **Sign out** before switching accounts or servers. You can use one server and account at a time.
 
-Default PC session locations:
+## Reset your saved sign-in on PC
 
-| Platform | File |
+If you cannot sign out through the app, remove the saved sign-in file:
+
+1. Close Jellyframe completely.
+2. Find the file for your computer in the table below.
+3. Delete `session.cfg`.
+4. Open Jellyframe again and sign in.
+
+| Computer | Saved sign-in file |
 | --- | --- |
 | Windows | `%APPDATA%\Jellyframe\session.cfg` |
 | Linux | `~/.local/share/Jellyframe/session.cfg` |
 
-Jellyframe reads the 3D format from Jellyfin's metadata or the filename, but you can select half or full side-by-side mode and swap the left and right views in Settings if the picture looks wrong. Top-bottom uses the upper half for the left eye and the lower half for the right eye; format and eye-swap changes are not saved per title.
+To reset the saved app settings as well, delete `settings.cfg` from the same folder while Jellyframe is closed. You will need to enter your server address and choose your settings again. This does not delete movies, shows, or your Jellyfin account.
 
-## 180° and 360° videos
+## Choose something to watch
 
-Start a video, open Settings > Screen, and choose **180°** or **360°** under Video projection, then select **2D**, **Half-SBS**, **Full-SBS**, or **Top-bottom** under Video format to match the file. 180° fills the view in front of you and leaves the view behind you dark, while 360° surrounds you.
+1. Select **Home** to see recently added movies and shows, or choose one of your libraries from the menu.
+2. Browse the titles, or enter a name in the search box and select **Search**.
+3. Select a movie to open its details, then choose **Play movie**. For a series, choose a season and select **Play episode** beside the episode you want.
+4. If you have watched part of a title before, choose **Resume** or **Resume episode** to continue from where you left off.
 
-Look around with your headset to see the scene, use the headset's recenter command to set the forward direction, and press A or B to show the playback controls in front of you.
+On a title's details page, **Play from start** appears beside **Resume** when saved progress is available. It starts the video at the beginning, even if that title is already playing.
 
-Jellyframe selects 360° automatically for filenames with a separate `360`, `360deg`, or `VR360` marker, such as `Beach.360.mp4`, and selects 180° for a separate `180`, `180deg`, or `VR180` marker. It does not infer the projection from video dimensions; files with a separate `TB`, `OU`, `top-bottom`, or `over-under` marker select top-bottom 3D.
+In VR, point your controller at a button and squeeze the trigger to select it. Point at a text box to open the keyboard. Use the thumbstick to scroll through a list.
 
-180° and 360° modes support equirectangular video, but not cubemap or fisheye layouts. The video replaces the chosen environment during playback, and screen size and position controls do not affect it. Select **Screen** to return to the virtual screen; projection overrides apply to the current playback and are not saved per title, so a new title uses automatic detection again.
+## View photos
 
-## Settings and environments
+Select a photo in your library to open it. A "Loading photo..." indicator appears while the image loads. Use the previous and next controls to browse photos; the same indicator appears while another photo is loading. If loading fails, the app returns to the library with an error message so you can try again.
 
-Use the separate settings pages to change library sorting, screen controls, and environments. For library sorting, choose a field and ascending or descending order; Home always shows the newest additions first.
+## Control playback
 
-Choose an environment:
+Press **A** to show the playback controls.
+Press **B** to open or close the library during playback.
+Press **Y** on the left controller to open or close settings.
 
-- Void, the default, gives you a dark background.
-- Cinema uses the detailed cinema interior.
-- Theatre uses the original simple cinema.
-- Passthrough shows your room around the screen and is disabled on unsupported devices.
+| Control | What it does |
+| --- | --- |
+| Play / Pause | Pause the video or continue watching. |
+| Stop | Stop the video and return to your library. |
+| Back 10 seconds | Go back a little to watch something again. |
+| Forward 30 seconds | Skip ahead. |
+| Time bar | Choose a different point in the video. |
+| Settings | Change the screen, background, or playback quality. |
+| Audio and subtitles | Placeholder for future audio-track and subtitle selection. This button is currently disabled. |
+| Hide controls | Remove the controls from your view. Press A to show them again. |
 
-Cinema and Theatre have a fixed front screen with black bars to preserve the video's proportions, while Void and Passthrough let you adjust the screen's size, distance, height, and curvature.
+Press **B** to browse your library while playback continues. Select the title that is already playing to return to the video.
 
-Reset to defaults restores the screen settings and keeps your chosen environment.
+When an episode finishes, a five-second countdown appears before the next available episode starts. Choose **Cancel** during the countdown to return to your library.
+
+### Skip intros and credits
+
+With [Intro Skipper](https://github.com/intro-skipper/intro-skipper) installed on Jellyfin 10.10 or newer, a **Skip intro** or **Skip credits** popup appears at the bottom-right of the video during a detected segment. Point at it and press the trigger to skip, even with the playback controls hidden. When the controls are open, the popup sits just above them. Recap and preview segments also have skip buttons when the server supplies them. Skipping is manual.
+
+The server must finish analyzing the title before timestamps are available. Jellyframe reads Jellyfin's media segments, so other providers using the same API also work. If there are no timestamps or the request fails, playback continues without a skip button. Older plugin-specific APIs are not supported.
+
+## Make the screen comfortable
+
+Open **Settings**, then choose **Screen**. If your chosen background allows screen adjustments, you can change:
+
+- **Width** to make the screen larger or smaller.
+- **Distance** to move it closer or farther away.
+- **Height** to move it up or down.
+- **Curvature** to make it flat or curved around you.
+
+If the screen is facing the wrong way, look in the direction you want to watch and use your headset's recenter command.
+
+**Cinema** and **Theatre** have fixed screens. To move or resize the screen yourself, choose **Void** or **Passthrough** under **Settings > Environment**.
+
+Select **Reset to defaults** on the Screen page to restore the usual screen size and position. This keeps your chosen background and video format. Settings are saved as you change them.
+
+## Choose your surroundings
+
+Open **Settings > Environment** and choose:
+
+| Background | What you see |
+| --- | --- |
+| Void | A dark background with an adjustable screen. This is the default. |
+| Cinema | A detailed cinema with a fixed screen at the front. |
+| Theatre | A simpler cinema with a fixed screen. |
+| Passthrough | Your real room around the video screen, if your headset supports it. |
+
+If your device does not support Passthrough, you cannot select it. In Cinema and Theatre, black bars keep the picture from looking stretched.
+
+## Watch a 3D video
+
+Jellyframe usually chooses the right picture layout automatically. If you see two pictures side by side or one above the other, open **Settings > Screen** and look for **Video format**.
+
+| Option | When to use it |
+| --- | --- |
+| 2D | Ordinary movies and shows without 3D. |
+| Half-SBS | A 3D video that stores the left-eye and right-eye pictures side by side. |
+| Full-SBS | Another side-by-side 3D format, with a wider picture for each eye. |
+| Top-bottom | A 3D video that stores one eye's picture above the other. |
+
+SBS means "side by side". If you do not know which version your video uses, try Half-SBS first. If the picture looks too wide or too narrow, try Full-SBS.
+
+If the depth looks wrong, try **Swap left and right eyes**. These choices are not remembered separately for each title, so another video may need a different setting.
+
+## Watch a 180° or 360° video
+
+These videos let you look around inside the scene instead of watching a normal screen.
+
+1. Start the video.
+2. Open **Settings > Screen**.
+3. Under **Video projection**, choose **180°** for a scene in front of you, or **360°** for a scene that surrounds you.
+4. If the video is also in 3D, choose the matching **Video format** as described above. Otherwise, leave it on **2D**.
+
+Move your head to look around. For a 180° video, the space behind you stays dark. Use your headset's recenter command if the scene faces the wrong direction. Press A to bring up the controls.
+
+The video replaces your chosen background while you watch. Screen width, distance, height, and curvature do not affect these videos. Select **Screen** under Video projection to return to a normal video screen.
+
+Jellyframe can recognize some 180° and 360° videos automatically, but you can change the setting if it chooses incorrectly. A new title uses automatic detection again. Some panoramic video formats are not supported, so changing this setting cannot fix every distorted video.
+
+## Change playback quality
+
+Open **Settings > Playback**. The choice applies to the next video you start.
+
+- **Automatic** plays the original video when possible and asks Jellyfin to convert it when needed. Start with this option if you are unsure.
+- **Original full resolution** keeps the original video quality. Your headset or PC must be able to play the file.
+- **Transcoded** asks your Jellyfin server to convert the video. Choose **720p**, **1080p**, or **4K** under **Transcoded resolution**. This can help with files that will not play smoothly at their original quality.
+
+1080p is the default for converted videos. Choose 720p to use less data, or 4K for more detail when the source video supports it. These are maximum sizes; smaller videos are not enlarged. Higher resolutions need a faster connection and more processing power from your Jellyfin server. Your choice is saved and applies to the next video you start.
+
+Picture quality depends on the video, your device, your connection, and what your Jellyfin server can handle. To use the Windows setup tested with HDR, 4K, and 8K videos, follow the [Windows launch instructions](INSTALLATION.md#try-it-on-windows-with-steamvr).
+
+## Change the order of your library
+
+Open **Settings > Library sorting** and choose how you want titles arranged. **Ascending** means A to Z, lowest to highest, or oldest first. **Descending** reverses that order.
+
+Home always shows the newest additions first. The sort order does not affect Random.
+
+## If something does not look right
+
+- If the controls disappear, press A to show them again.
+- If you cannot resize the screen, choose Void or Passthrough under Settings > Environment, and select Screen under Video projection.
+- If you see two copies of the picture, check Video format under Settings > Screen.
+- If the scene surrounds you when you wanted a normal screen, select Screen under Video projection.
+- If the video pauses with a loading message, it is waiting for more video data. Give it a moment. If this keeps happening, try Automatic or Transcoded under Settings > Playback, then start the video again.
+- Audio-language and subtitle selection are not available yet.
+
+For setup problems, see [Install and start Jellyframe](INSTALLATION.md). The [README](README.md#current-limitations) lists the remaining limitations.

assets/icons/material/chevron_left.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48"><path d="M29 12 17 24l12 12" fill="none" stroke="#fff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg>

assets/icons/material/chevron_left.svg.import

@@ -0,0 +1,43 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://8g8da6x17oy"
+path="res://.godot/imported/chevron_left.svg-10348879aad5ca00a7c102d754890d86.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/icons/material/chevron_left.svg"
+dest_files=["res://.godot/imported/chevron_left.svg-10348879aad5ca00a7c102d754890d86.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1
+svg/scale=1.0
+editor/scale_with_editor_scale=false
+editor/convert_colors_with_editor_theme=false

assets/icons/material/chevron_right.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48"><path d="m19 12 12 12-12 12" fill="none" stroke="#fff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg>

assets/icons/material/chevron_right.svg.import

@@ -0,0 +1,43 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://b3euoqp2obfod"
+path="res://.godot/imported/chevron_right.svg-c99d4ba07ab61f6b832110c3459f3770.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/icons/material/chevron_right.svg"
+dest_files=["res://.godot/imported/chevron_right.svg-c99d4ba07ab61f6b832110c3459f3770.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1
+svg/scale=1.0
+editor/scale_with_editor_scale=false
+editor/convert_colors_with_editor_theme=false

assets/icons/material/subtitles.svg

@@ -0,0 +1 @@
+<svg fill="#ffffff" xmlns="http://www.w3.org/2000/svg" height="48" viewBox="0 -960 960 960" width="48"><!-- Google Material Symbols Rounded, Apache-2.0. Modified display size and fill for Godot. --><path d="M160-160q-33 0-56.5-23.5T80-240v-480q0-33 23.5-56.5T160-800h640q33 0 56.5 23.5T880-720v480q0 33-23.5 56.5T800-160H160Zm0-80h640v-480H160v480Zm0 0v-480 480Zm120-80h240q17 0 28.5-11.5T560-360q0-17-11.5-28.5T520-400H280q-17 0-28.5 11.5T240-360q0 17 11.5 28.5T280-320Zm160-160h240q17 0 28.5-11.5T720-520q0-17-11.5-28.5T680-560H440q-17 0-28.5 11.5T400-520q0 17 11.5 28.5T440-480Zm-160 0q17 0 28.5-11.5T320-520q0-17-11.5-28.5T280-560q-17 0-28.5 11.5T240-520q0 17 11.5 28.5T280-480Zm400 160q17 0 28.5-11.5T720-360q0-17-11.5-28.5T680-400q-17 0-28.5 11.5T640-360q0 17 11.5 28.5T680-320Z"/></svg>

assets/icons/material/subtitles.svg.import

@@ -0,0 +1,43 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://by17fi2gifls"
+path="res://.godot/imported/subtitles.svg-b6bec42b0b1d98546183a5273689fcc2.ctex"
+metadata={
+"vram_texture": false
+}
+
+[deps]
+
+source_file="res://assets/icons/material/subtitles.svg"
+dest_files=["res://.godot/imported/subtitles.svg-b6bec42b0b1d98546183a5273689fcc2.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=false
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1
+svg/scale=1.0
+editor/scale_with_editor_scale=false
+editor/convert_colors_with_editor_theme=false

export_presets.cfg

@@ -6,8 +6,8 @@ advanced_options=false
 dedicated_server=false
 custom_features="quest"
 export_filter="all_resources"
-include_filter="addons/godotopenxrvendors/*LICENSE*,assets/icons/material/LICENSE.txt,assets/icons/material/ATTRIBUTION.md,assets/theatre/ATTRIBUTION.md"
-exclude_filter="assets/cinema.glb,assets/theatre/materials.tres,native/*,android/*,docs/*,tests/*,tools/*,dist/*,build/*,addons/jellyframe_mpv/*,shaders/pc_video.gdshader"
+include_filter="addons/godotopenxrvendors/*LICENSE*"
+exclude_filter="assets/cinema.glb,assets/theatre/materials.tres,native/*,android/*,docs/*,tests/*,tools/*,dist/*,build/*,addons/jellyframe_mpv/*"
 export_path="dist/jellyframe-android.apk"
 script_export_mode=2
 
@@ -24,8 +24,8 @@ architectures/armeabi-v7a=false
 architectures/arm64-v8a=true
 architectures/x86=false
 architectures/x86_64=false
-version/code=1
-version/name="0.1.0"
+version/code=3
+version/name="0.1.2"
 package/unique_name="nu.lizzy.jellyframe"
 package/name="Jellyframe"
 package/signed=true
@@ -46,14 +46,14 @@ screen/support_xlarge=true
 user_data_backup/allow=false
 
 [preset.1]
-name="Windows SteamVR"
+name="Windows"
 platform="Windows Desktop"
 runnable=true
 advanced_options=false
 dedicated_server=false
 custom_features=""
 export_filter="all_resources"
-include_filter="assets/icons/material/LICENSE.txt,assets/icons/material/ATTRIBUTION.md,assets/theatre/ATTRIBUTION.md"
+include_filter=""
 exclude_filter="assets/cinema.glb,assets/theatre/materials.tres,native/*,android/*,docs/*,tests/*,tools/*,dist/*,build/*,addons/jellyframe_video/bin/*"
 export_path="dist/windows/jellyframe.exe"
 script_export_mode=2
@@ -69,16 +69,16 @@ codesign/enable=false
 application/modify_resources=false
 
 [preset.2]
-name="Linux x64 OpenXR"
+name="Linux x64"
 platform="Linux"
 runnable=true
 advanced_options=false
 dedicated_server=false
-custom_features="linux_opengl"
+custom_features=""
 export_filter="all_resources"
-include_filter="assets/icons/material/LICENSE.txt,assets/icons/material/ATTRIBUTION.md,assets/theatre/ATTRIBUTION.md"
+include_filter=""
 exclude_filter="assets/cinema.glb,assets/theatre/materials.tres,native/*,android/*,docs/*,tests/*,tools/*,dist/*,build/*,addons/jellyframe_video/bin/*"
-export_path="dist/linux-x86_64/jellyframe-opengl.x86_64"
+export_path="dist/linux-x86_64/jellyframe.x86_64"
 script_export_mode=2
 
 [preset.2.options]
@@ -90,16 +90,16 @@ texture_format/s3tc_bptc=true
 texture_format/etc2_astc=false
 
 [preset.3]
-name="Linux ARM64 OpenXR"
+name="Linux ARM64"
 platform="Linux"
 runnable=true
 advanced_options=false
 dedicated_server=false
-custom_features="linux_opengl"
+custom_features=""
 export_filter="all_resources"
-include_filter="assets/icons/material/LICENSE.txt,assets/icons/material/ATTRIBUTION.md,assets/theatre/ATTRIBUTION.md"
+include_filter=""
 exclude_filter="assets/cinema.glb,assets/theatre/materials.tres,native/*,android/*,docs/*,tests/*,tools/*,dist/*,build/*,addons/jellyframe_video/bin/*"
-export_path="dist/linux-arm64/jellyframe-opengl.arm64"
+export_path="dist/linux-arm64/jellyframe.arm64"
 script_export_mode=2
 
 [preset.3.options]
@@ -109,45 +109,3 @@ binary_format/architecture="arm64"
 binary_format/embed_pck=true
 texture_format/s3tc_bptc=true
 texture_format/etc2_astc=true
-
-[preset.4]
-name="Linux x64 Vulkan"
-platform="Linux"
-runnable=false
-advanced_options=false
-dedicated_server=false
-custom_features="linux_vulkan"
-export_filter="all_resources"
-include_filter="assets/icons/material/LICENSE.txt,assets/icons/material/ATTRIBUTION.md,assets/theatre/ATTRIBUTION.md"
-exclude_filter="assets/cinema.glb,assets/theatre/materials.tres,native/*,android/*,docs/*,tests/*,tools/*,dist/*,build/*,addons/jellyframe_video/bin/*"
-export_path="dist/linux-x86_64/jellyframe-vulkan.x86_64"
-script_export_mode=2
-
-[preset.4.options]
-custom_template/debug=""
-custom_template/release=""
-binary_format/architecture="x86_64"
-binary_format/embed_pck=true
-texture_format/s3tc_bptc=true
-texture_format/etc2_astc=false
-
-[preset.5]
-name="Linux ARM64 Vulkan"
-platform="Linux"
-runnable=false
-advanced_options=false
-dedicated_server=false
-custom_features="linux_vulkan"
-export_filter="all_resources"
-include_filter="assets/icons/material/LICENSE.txt,assets/icons/material/ATTRIBUTION.md,assets/theatre/ATTRIBUTION.md"
-exclude_filter="assets/cinema.glb,assets/theatre/materials.tres,native/*,android/*,docs/*,tests/*,tools/*,dist/*,build/*,addons/jellyframe_video/bin/*"
-export_path="dist/linux-arm64/jellyframe-vulkan.arm64"
-script_export_mode=2
-
-[preset.5.options]
-custom_template/debug=""
-custom_template/release=""
-binary_format/architecture="arm64"
-binary_format/embed_pck=true
-texture_format/s3tc_bptc=true
-texture_format/etc2_astc=true

native/android/src/main/java/nu/lizzy/jellyframe/video/JellyframeVideo.java

@@ -17,6 +17,7 @@ import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Set;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
 import javax.microedition.khronos.opengles.GL10;
 
 public final class JellyframeVideo extends GodotPlugin {
@@ -34,7 +35,9 @@ public final class JellyframeVideo extends GodotPlugin {
     private volatile boolean prepared;
     private volatile boolean buffering;
     private volatile boolean seeking;
-    private int generation;
+    private final AtomicInteger generation = new AtomicInteger();
+    private volatile int readyGeneration = -1;
+    private int textureGeneration = -1;
 
     public JellyframeVideo(Godot godot) {
         super(godot);
@@ -53,29 +56,34 @@ public final class JellyframeVideo extends GodotPlugin {
     }
 
     @UsedByGodot public void open_video(int textureId, String url, String authorization, int startMs) {
-        Log.i("JellyframeVideo", "Opening video texture " + textureId);
+        int opening = generation.incrementAndGet();
         main.post(() -> {
+            if (opening != generation.get()) return;
             releasePlayer();
-            int opening = generation;
             runOnRenderThread(() -> {
+                if (opening != generation.get()) return;
                 releaseSurface();
                 texture = new SurfaceTexture(textureId);
-                Log.i("JellyframeVideo", "SurfaceTexture created");
+                textureGeneration = opening;
                 texture.setOnFrameAvailableListener(ignored -> {
-                    if (ignored != texture) return;
+                    if (ignored != texture || opening != generation.get()) return;
                     lastFrame = SystemClock.elapsedRealtime();
                     frameAvailable.set(true);
                 });
                 surface = new Surface(texture);
                 Surface output = surface;
                 main.post(() -> {
-                    if (opening == generation) prepare(output, url, authorization, startMs);
+                    if (opening == generation.get()) prepare(output, url, authorization, startMs, opening);
                 });
             });
         });
     }
 
-    private void prepare(Surface output, String url, String authorization, int startMs) {
+    private boolean isCurrent(MediaPlayer current, int opening) {
+        return current == player && opening == generation.get();
+    }
+
+    private void prepare(Surface output, String url, String authorization, int startMs, int opening) {
         try {
             player = new MediaPlayer();
             player.setSurface(output);
@@ -84,8 +92,7 @@ public final class JellyframeVideo extends GodotPlugin {
             headers.put("android-allow-cross-domain-redirect", "0");
             player.setDataSource(getContext(), Uri.parse(url), headers);
             player.setOnPreparedListener(current -> {
-                if (current != player) return;
-                Log.i("JellyframeVideo", "Decoder prepared: " + current.getVideoWidth() + "x" + current.getVideoHeight());
+                if (!isCurrent(current, opening)) return;
                 prepared = true;
                 watchdog.reset(SystemClock.elapsedRealtime());
                 duration = Math.max(0, current.getDuration());
@@ -94,32 +101,32 @@ public final class JellyframeVideo extends GodotPlugin {
                 main.post(pollPlayback);
                 emitSignal("prepared");
             });
-            player.setOnVideoSizeChangedListener((current, width, height) -> emitSignal("video_size", width, height));
+            player.setOnVideoSizeChangedListener((current, width, height) -> {
+                if (isCurrent(current, opening)) emitSignal("video_size", width, height);
+            });
             player.setOnInfoListener((current, what, extra) -> {
-                if (current != player) return true;
+                if (!isCurrent(current, opening)) return true;
                 if (what == MediaPlayer.MEDIA_INFO_BUFFERING_START) {
                     buffering = true;
-                    Log.i("JellyframeVideo", "Buffering started at " + position + " ms");
                 }
                 if (what == MediaPlayer.MEDIA_INFO_BUFFERING_END) {
                     buffering = false;
-                    Log.i("JellyframeVideo", "Buffering ended at " + position + " ms");
                 }
                 if (what == MediaPlayer.MEDIA_INFO_VIDEO_TRACK_LAGGING) Log.w("JellyframeVideo", "Video decoder is falling behind");
                 return false;
             });
             player.setOnSeekCompleteListener(current -> {
-                if (current != player) return;
+                if (!isCurrent(current, opening)) return;
                 seeking = false;
                 watchdog.setPaused(!current.isPlaying(), SystemClock.elapsedRealtime());
             });
             player.setOnCompletionListener(current -> {
-                if (current != player) return;
+                if (!isCurrent(current, opening)) return;
                 main.removeCallbacks(pollPlayback);
                 emitSignal("completed");
             });
             player.setOnErrorListener((current, what, extra) -> {
-                if (current != player) return true;
+                if (!isCurrent(current, opening)) return true;
                 prepared = false;
                 main.removeCallbacks(pollPlayback);
                 emitSignal("failed", "Android could not decode this stream (" + what + ", " + extra + ").");
@@ -136,6 +143,7 @@ public final class JellyframeVideo extends GodotPlugin {
         if (texture != null && frameAvailable.compareAndSet(true, false)) {
             texture.updateTexImage();
             synchronized (transform) { texture.getTransformMatrix(transform); }
+            if (textureGeneration == generation.get()) readyGeneration = textureGeneration;
         }
     }
 
@@ -163,17 +171,9 @@ public final class JellyframeVideo extends GodotPlugin {
 
     @UsedByGodot public int position_ms() { return position; }
     @UsedByGodot public int duration_ms() { return duration; }
+    @UsedByGodot public boolean has_video_frame() { return readyGeneration >= 0 && readyGeneration == generation.get(); }
     @UsedByGodot public boolean is_buffering() { return prepared && (buffering || seeking); }
 
-    @UsedByGodot public String calibration_url() {
-        int resource = getContext().getResources().getIdentifier("stereo_test", "raw", getContext().getPackageName());
-        return "android.resource://" + getContext().getPackageName() + "/" + resource;
-    }
-
-    @UsedByGodot public boolean calibration_requested() {
-        return getActivity() != null && getActivity().getIntent().getBooleanExtra("jellyframe_calibration", false);
-    }
-
     @UsedByGodot public void set_paused(boolean paused) {
         main.post(() -> {
             if (player == null || !prepared) return;
@@ -192,11 +192,13 @@ public final class JellyframeVideo extends GodotPlugin {
         });
     }
 
-    @UsedByGodot public void stop_video() { main.post(this::releasePlayer); }
+    @UsedByGodot public void stop_video() {
+        generation.incrementAndGet();
+        main.post(this::releasePlayer);
+    }
 
     private void releasePlayer() {
         main.removeCallbacks(pollPlayback);
-        generation++;
         prepared = false;
         buffering = false;
         seeking = false;
@@ -206,6 +208,7 @@ public final class JellyframeVideo extends GodotPlugin {
     }
 
     private void releaseSurface() {
+        readyGeneration = -1;
         lastFrame = 0;
         frameAvailable.set(false);
         if (surface != null) { surface.release(); surface = null; }
@@ -215,6 +218,7 @@ public final class JellyframeVideo extends GodotPlugin {
     @Override public void onMainPause() { set_paused(true); }
 
     @Override public void onMainDestroy() {
+        generation.incrementAndGet();
         releasePlayer();
         runOnRenderThread(this::releaseSurface);
     }

native/pc/CMakeLists.txt

@@ -5,6 +5,7 @@ set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(GODOT_CPP_PATH "" CACHE PATH "Path to godot-cpp godot-4.5-stable")
 set(MPV_ROOT "" CACHE PATH "Path to the libmpv development archive")
+set(FFMPEG_ROOT "" CACHE PATH "Path to the FFmpeg shared development archive on Windows")
 if(NOT GODOT_CPP_PATH)
     message(FATAL_ERROR "Set GODOT_CPP_PATH. See tools/build-pc-video.ps1 or tools/build-pc-video.sh.")
 endif()
@@ -25,17 +26,30 @@ if(WIN32)
         IMPORTED_LOCATION "${MPV_LIBRARY}"
         INTERFACE_INCLUDE_DIRECTORIES "${MPV_INCLUDE_DIR}")
     set(MPV_TARGET jellyframe_mpv_dependency)
+    find_path(FFMPEG_INCLUDE_DIR libavcodec/avcodec.h PATHS "${FFMPEG_ROOT}/include" REQUIRED NO_DEFAULT_PATH)
+    foreach(component avcodec avformat avutil swscale)
+        find_library(FFMPEG_${component}_LIBRARY NAMES ${component} PATHS "${FFMPEG_ROOT}/lib" REQUIRED NO_DEFAULT_PATH)
+        list(APPEND FFMPEG_LIBRARIES "${FFMPEG_${component}_LIBRARY}")
+    endforeach()
 elseif(CMAKE_SYSTEM_NAME STREQUAL "Linux")
     find_package(PkgConfig REQUIRED)
     pkg_check_modules(MPV REQUIRED IMPORTED_TARGET mpv>=2.0)
     set(MPV_TARGET PkgConfig::MPV)
+    pkg_check_modules(FFMPEG REQUIRED IMPORTED_TARGET libavcodec>=60 libavformat>=60 libavutil>=58 libswscale>=7)
+    set(FFMPEG_LIBRARIES PkgConfig::FFMPEG)
 else()
     message(FATAL_ERROR "The PC video plugin supports Windows and Linux.")
 endif()
 find_package(Threads REQUIRED)
 
-add_library(jellyframe_mpv SHARED mpv_video.cpp render_worker.cpp render_gl.cpp render_gl_worker.cpp gl_functions.cpp register_types.cpp)
-target_link_libraries(jellyframe_mpv PRIVATE godot-cpp ${MPV_TARGET} Threads::Threads)
+add_library(jellyframe_mpv SHARED
+    mpv_video.cpp render_worker.cpp render_gl.cpp render_gl_worker.cpp
+    gl_functions.cpp register_types.cpp render_vulkan.cpp
+    video_decoder.cpp video_decoder_frames.cpp video_decoder_packets.cpp video_decoder_planes.cpp video_plane.cpp video_sync.cpp)
+target_link_libraries(jellyframe_mpv PRIVATE godot-cpp ${MPV_TARGET} ${FFMPEG_LIBRARIES} Threads::Threads)
+if(WIN32)
+    target_include_directories(jellyframe_mpv PRIVATE "${FFMPEG_INCLUDE_DIR}")
+endif()
 if(WIN32)
     target_sources(jellyframe_mpv PRIVATE shared_gl_context_windows.cpp)
     target_link_libraries(jellyframe_mpv PRIVATE opengl32)

native/pc/THIRD_PARTY.md

@@ -1,14 +0,0 @@
-# PC playback dependencies
-
-The Windows build bundles libmpv from shinchiro's `20261010` build, mpv revision `b2c255c13e`, and links godot-cpp `godot-4.5-stable`.
-
-- [libmpv binary release](https://github.com/shinchiro/mpv-winbuild-cmake/releases/tag/20261010)
-- [mpv source and copyright information](https://github.com/mpv-player/mpv/tree/b2c255c13e)
-- [Windows decoder build scripts and dependency sources](https://github.com/shinchiro/mpv-winbuild-cmake)
-- [godot-cpp source](https://github.com/godotengine/godot-cpp/tree/godot-4.5-stable)
-
-godot-cpp uses the MIT licence, while libmpv and its bundled codec dependencies have their own licences, including GPL components. Redistributors must provide the required copyright notices and corresponding source for the exact decoder build they ship; the links above identify upstream projects and do not replace those obligations.
-
-The Linux builds link against the distribution's libmpv, which you install with its codec dependencies through the distribution's package manager, and do not bundle the Windows decoder. Each Linux artifact records its compile-time libmpv version in `build-info.txt` and includes the godot-cpp licence.
-
-The Windows build script pins download versions and SHA-256 checksums, downloads build tools into the ignored build directory, and does not install them system-wide. The Linux build script verifies the same godot-cpp archive checksum and uses the host's compiler, CMake, Python, and libmpv development package.

native/pc/build_profile.json

@@ -1,3 +1,19 @@
 {
-  "enabled_classes": ["Node", "Image", "ImageTexture", "OS", "DisplayServer", "RenderingServer"]
+  "enabled_classes": [
+    "Node",
+    "Image",
+    "ImageTexture",
+    "OS",
+    "DisplayServer",
+    "RenderingServer",
+    "RenderingDevice",
+    "Texture2DRD",
+    "RDShaderSource",
+    "RDShaderSPIRV",
+    "RDTextureFormat",
+    "RDTextureView",
+    "RDSamplerState",
+    "RDUniform",
+    "RDPipelineSpecializationConstant"
+  ]
 }

native/pc/jellyframe_mpv.gdextension

@@ -9,4 +9,4 @@ linux.x86_64 = "res://addons/jellyframe_mpv/bin/jellyframe_mpv.linux.x86_64.so"
 linux.arm64 = "res://addons/jellyframe_mpv/bin/jellyframe_mpv.linux.arm64.so"
 
 [dependencies]
-windows.x86_64 = { "res://addons/jellyframe_mpv/bin/libmpv-2.dll": "" }
+windows.x86_64 = { "res://addons/jellyframe_mpv/bin/libmpv-2.dll": "", "res://addons/jellyframe_mpv/bin/avcodec-62.dll": "", "res://addons/jellyframe_mpv/bin/avformat-62.dll": "", "res://addons/jellyframe_mpv/bin/avutil-60.dll": "", "res://addons/jellyframe_mpv/bin/swscale-9.dll": "", "res://addons/jellyframe_mpv/bin/swresample-6.dll": "" }

native/pc/mpv_video.cpp

@@ -1,4 +1,5 @@
 #include "mpv_video.h"
+#include "stream_identity.h"
 #include <godot_cpp/classes/image.hpp>
 #include <godot_cpp/classes/os.hpp>
 #include <godot_cpp/classes/display_server.hpp>
@@ -31,8 +32,9 @@ void JellyframeMpv::_bind_methods() {
     ClassDB::bind_method(D_METHOD("position_ms"), &JellyframeMpv::position_ms);
     ClassDB::bind_method(D_METHOD("duration_ms"), &JellyframeMpv::duration_ms);
     ClassDB::bind_method(D_METHOD("is_buffering"), &JellyframeMpv::is_buffering);
-    ClassDB::bind_method(D_METHOD("playback_diagnostics"), &JellyframeMpv::playback_diagnostics);
     ClassDB::bind_method(D_METHOD("rendering_backend"), &JellyframeMpv::rendering_backend);
+    ClassDB::bind_method(D_METHOD("video_shader_parameters"), &JellyframeMpv::video_shader_parameters);
+    ClassDB::bind_method(D_METHOD("playback_diagnostics"), &JellyframeMpv::playback_diagnostics);
     ClassDB::bind_method(D_METHOD("stop_video"), &JellyframeMpv::stop_video);
     ADD_SIGNAL(MethodInfo("prepared"));
     ADD_SIGNAL(MethodInfo("ended"));
@@ -45,22 +47,40 @@ JellyframeMpv::~JellyframeMpv() {
     shutdown();
 }
 
-String JellyframeMpv::initialize() {
+String JellyframeMpv::initialize(int64_t start_ms) {
+    log_video_stats = OS::get_singleton()->get_environment("JELLYFRAME_VIDEO_STATS") == "1";
+    last_diagnostics_time = playback_time_ms();
     player = mpv_create();
     if (!player) return "Could not create the PC video decoder.";
     const bool use_opengl = !software_only &&
         OS::get_singleton()->get_environment("JELLYFRAME_PC_RENDERER") != "software" && hardware_opengl_available();
+    if (!software_only && OS::get_singleton()->get_environment("JELLYFRAME_PC_RENDERER") != "software" &&
+            DisplayServer::get_singleton()->get_name() != "headless" &&
+            RenderingServer::get_singleton()->get_current_rendering_driver_name() == "vulkan") {
+        vulkan_renderer.instantiate();
+        if (vulkan_renderer->start(current_url, current_authorization, start_ms) < 0) {
+            vulkan_renderer->stop();
+            vulkan_renderer.unref();
+        }
+    }
     const char *options[][2] = {
         {"config", "no"}, {"terminal", "no"}, {"load-scripts", "no"},
         {"ytdl", "no"}, {"input-default-bindings", "no"}, {"input-vo-keyboard", "no"},
-        {"vo", "libmpv"}, {"hwdec", use_opengl ? "auto" : "auto-copy"}, {"osd-level", "0"},
+        {"vo", vulkan_renderer.is_valid() ? "null" : "libmpv"},
+        {"hwdec", use_opengl ? "auto" : "auto-copy"}, {"osd-level", "0"},
         {"sub-auto", "no"}, {"audio-file-auto", "no"}, {"keep-open", "no"},
-        {"idle", "yes"}, {"tls-verify", "yes"}
+        {"idle", "yes"}, {"tls-verify", "yes"},
+        {"cache", "yes"}, {"cache-secs", "30"}, {"demuxer-max-bytes", "256MiB"},
+        {"user-agent", JELLYFRAME_STREAM_USER_AGENT}
     };
     for (const auto &option : options) {
         int error = mpv_set_option_string(player, option[0], option[1]);
         if (error < 0) return String("PC decoder option failed: ") + option[0] + ".";
     }
+    if (vulkan_renderer.is_valid() && vulkan_renderer->has_audio()) {
+        int error = mpv_set_option_string(player, "vid", "no");
+        if (error < 0) return "Could not configure the Vulkan playback clock.";
+    }
     int error = mpv_initialize(player);
     if (error >= 0 && use_opengl) {
         gl_renderer.instantiate();
@@ -69,7 +89,7 @@ String JellyframeMpv::initialize() {
             gl_renderer.unref();
         }
     }
-    if (error >= 0 && gl_renderer.is_null()) {
+    if (error >= 0 && gl_renderer.is_null() && vulkan_renderer.is_null()) {
         error = mpv_set_property_string(player, "hwdec", "auto-copy");
         if (error >= 0) error = renderer.start(player);
     }
@@ -86,11 +106,19 @@ String JellyframeMpv::open_video(String url, String authorization, int64_t start
     shutdown();
     current_url = url;
     current_authorization = authorization;
-    String error = initialize();
+    String error = initialize(start_ms);
     if (!error.is_empty()) {
         shutdown();
         return error;
     }
+    if (uses_video_clock()) {
+        position = std::max<int64_t>(0, start_ms);
+        duration = vulkan_renderer->duration_ms();
+        video_clock_origin = playback_time_ms() - position;
+        active = true;
+        set_process(true);
+        return "";
+    }
     auto header = (String("Authorization: ") + authorization).utf8();
     mpv_node entry{};
     entry.format = MPV_FORMAT_STRING;
@@ -114,24 +142,34 @@ String JellyframeMpv::open_video(String url, String authorization, int64_t start
     position = std::max<int64_t>(0, start_ms);
     duration = 0;
     active = true;
-    diagnostics_enabled = OS::get_singleton()->get_environment("JELLYFRAME_PC_DIAGNOSTICS") == "1";
-    diagnostic_time_ms = playback_time_ms();
     set_process(true);
     return "";
 }
 
 void JellyframeMpv::set_paused(bool value) {
     if (!player || !active) return;
+    if (uses_video_clock()) {
+        if (!paused && video_clock_started && !seeking) position = int64_t(playback_time_ms() - video_clock_origin);
+        video_clock_origin = playback_time_ms() - position;
+        paused = value;
+        watchdog.reset(playback_time_ms());
+        return;
+    }
     paused = value;
     watchdog.reset(playback_time_ms());
-    int flag = value;
-    mpv_set_property_async(player, 0, "pause", MPV_FORMAT_FLAG, &flag);
+    apply_audio_pause();
 }
 
 void JellyframeMpv::seek_to(int64_t milliseconds) {
     if (!player || !active) return;
     seeking = true;
+    if (vulkan_renderer.is_valid()) vulkan_renderer->seek(milliseconds);
     watchdog.reset(playback_time_ms());
+    if (uses_video_clock()) {
+        position = std::max<int64_t>(0, milliseconds);
+        video_clock_origin = playback_time_ms() - position;
+        return;
+    }
     auto target = String::num(double(std::max<int64_t>(0, milliseconds)) / 1000.0, 3).utf8();
     const char *command[] = {"seek", target.get_data(), "absolute+exact", nullptr};
     mpv_command_async(player, 0, command);
@@ -141,41 +179,34 @@ int64_t JellyframeMpv::position_ms() const { return position; }
 int64_t JellyframeMpv::duration_ms() const { return duration; }
 
 bool JellyframeMpv::is_buffering() const {
-    return active && (buffering || seeking);
+    return active && (buffering || video_buffering || seeking);
 }
 
-Dictionary JellyframeMpv::playback_diagnostics() const {
-    Dictionary result;
-    if (!player) return result;
-    for (const char *name : {"video-codec", "hwdec-current"}) {
-        char *value = mpv_get_property_string(player, name);
-        result[name] = value ? String::utf8(value) : String("unavailable");
-        mpv_free(value);
-    }
-    for (const char *name : {"container-fps", "decoder-frame-drop-count", "frame-drop-count"}) {
-        double value = 0;
-        result[name] = mpv_get_property(player, name, MPV_FORMAT_DOUBLE, &value) >= 0 ? Variant(value) : Variant();
-    }
-    result["render_backend"] = rendering_backend();
-    result["width"] = texture.is_valid() ? texture->get_width() : frame.width;
-    result["height"] = texture.is_valid() ? texture->get_height() : frame.height;
-    result["cpu_rgba_bytes"] = frame.pixels.size();
-    result["render_call_ms"] = gl_renderer.is_valid() ? gl_renderer->render_call_ms() : double(frame.render_time_us) / 1000.0;
-    result["present_cpu_ms"] = gl_renderer.is_valid() ? gl_renderer->present_cpu_ms() : 0.0;
-    result["upload_cpu_ms"] = upload_cpu_ms;
-    result["uploaded_frames"] = int64_t(uploaded_frames);
-    result["paused"] = paused;
-    result["buffering"] = buffering;
-    result["seeking"] = seeking;
-    return result;
+bool JellyframeMpv::uses_video_clock() const {
+    return vulkan_renderer.is_valid() && !vulkan_renderer->has_audio();
 }
 
 String JellyframeMpv::rendering_backend() const {
     if (!player) return "none";
+    if (vulkan_renderer.is_valid()) return "vulkan";
     return gl_renderer.is_valid() ? "opengl" : "software";
 }
 
+Dictionary JellyframeMpv::playback_diagnostics() const {
+    Dictionary values = vulkan_renderer.is_valid() ? vulkan_renderer->diagnostics() : Dictionary();
+    values["renderer"] = rendering_backend();
+    values["version"] = "vulkan-direct-yuv-1";
+    values["audio_position_ms"] = position;
+    if (vulkan_renderer.is_valid()) {
+        values["video_position_ms"] = vulkan_renderer->timestamp_ms();
+        values["video_buffering"] = video_buffering;
+        values["video_buffer_count"] = int64_t(video_buffer_count);
+    }
+    return values;
+}
+
 void JellyframeMpv::fallback_to_software() {
+    UtilityFunctions::print("PC video: falling back to software. ", playback_diagnostics());
     String url = current_url;
     String authorization = current_authorization;
     int64_t resume_at = position;
@@ -186,18 +217,6 @@ void JellyframeMpv::fallback_to_software() {
     if (was_paused) set_paused(true);
 }
 
-void JellyframeMpv::report_diagnostics() {
-    if (!diagnostics_enabled || !prepared) return;
-    uint64_t now = playback_time_ms();
-    uint64_t elapsed = now - diagnostic_time_ms;
-    if (elapsed < 5000) return;
-    Dictionary result = playback_diagnostics();
-    result["uploaded_fps"] = double(uploaded_frames - diagnostic_frames) * 1000.0 / double(elapsed);
-    UtilityFunctions::print("Jellyframe PC playback: ", result);
-    diagnostic_time_ms = now;
-    diagnostic_frames = uploaded_frames;
-}
-
 void JellyframeMpv::stop_video() {
     shutdown();
 }
@@ -207,8 +226,15 @@ void JellyframeMpv::shutdown() {
     prepared = false;
     paused = false;
     buffering = false;
+    video_buffering = false;
+    video_buffer_count = 0;
     seeking = false;
+    video_clock_started = false;
     set_process(false);
+    if (vulkan_renderer.is_valid()) {
+        vulkan_renderer->stop();
+        vulkan_renderer.unref();
+    }
     if (gl_renderer.is_valid()) {
         gl_renderer->stop();
         gl_renderer.unref();
@@ -218,15 +244,15 @@ void JellyframeMpv::shutdown() {
     player = nullptr;
     texture.unref();
     frame = VideoFrame();
-    uploaded_frames = 0;
-    diagnostic_frames = 0;
-    diagnostic_time_ms = 0;
-    upload_cpu_ms = 0;
     current_url = "";
     current_authorization = "";
 }
 
 bool JellyframeMpv::update_size() {
+    if (vulkan_renderer.is_valid()) {
+        emit_signal("size_changed", vulkan_renderer->width(), vulkan_renderer->height());
+        return vulkan_renderer->width() > 0 && vulkan_renderer->height() > 0;
+    }
     int64_t width = 0;
     int64_t height = 0;
     mpv_get_property(player, "dwidth", MPV_FORMAT_INT64, &width);
@@ -244,6 +270,26 @@ bool JellyframeMpv::update_size() {
 }
 
 bool JellyframeMpv::upload_frame() {
+    if (vulkan_renderer.is_valid()) {
+        vulkan_renderer->set_clock(position);
+        Dictionary previous_parameters = vulkan_renderer->shader_parameters();
+        if (!vulkan_renderer->take_frame()) return false;
+        if (uses_video_clock()) {
+            if (!video_clock_started || seeking) video_clock_origin = playback_time_ms() - position;
+            video_clock_started = true;
+            seeking = false;
+        }
+        Ref<Texture2D> next = vulkan_renderer->shader_parameters()["y_plane"];
+        if (texture != next) {
+            texture = next;
+            emit_signal("size_changed", vulkan_renderer->width(), vulkan_renderer->height());
+            UtilityFunctions::print("PC video: ", playback_diagnostics());
+        }
+        if (!vulkan_renderer->shader_parameters().recursive_equal(previous_parameters, 0)) {
+            emit_signal("texture_changed", texture);
+        }
+        return true;
+    }
     if (gl_renderer.is_valid()) {
         bool received = gl_renderer->take_frame();
         if (received) {
@@ -251,22 +297,18 @@ bool JellyframeMpv::upload_frame() {
                 texture = gl_renderer->get_texture();
                 emit_signal("texture_changed", texture);
             }
-            ++uploaded_frames;
         }
         return received;
     }
     if (!renderer.take_frame(frame)) return false;
-    auto upload_started = std::chrono::steady_clock::now();
     auto image = Image::create_from_data(frame.width, frame.height, false, Image::FORMAT_RGBA8, frame.pixels);
     if (texture.is_null() || texture->get_width() != frame.width || texture->get_height() != frame.height) {
         texture = ImageTexture::create_from_image(image);
         emit_signal("texture_changed", texture);
     } else {
-        texture->update(image);
+        Ref<ImageTexture> image_texture = texture;
+        image_texture->update(image);
     }
-    upload_cpu_ms = double(std::chrono::duration_cast<std::chrono::microseconds>(
-        std::chrono::steady_clock::now() - upload_started).count()) / 1000.0;
-    ++uploaded_frames;
     return true;
 }
 
@@ -287,7 +329,7 @@ void JellyframeMpv::update_property(const mpv_event &event) {
             if (seeking && !value) watchdog.reset(playback_time_ms());
             seeking = value;
         }
-        if (event.reply_userdata == 5) {
+        if (event.reply_userdata == 5 && vulkan_renderer.is_null()) {
             paused = value;
             watchdog.reset(playback_time_ms());
         }
@@ -296,13 +338,30 @@ void JellyframeMpv::update_property(const mpv_event &event) {
 
 void JellyframeMpv::_process(double) {
     if (!player || !active) return;
+    if (vulkan_renderer.is_valid() && vulkan_renderer->error() < 0) { fallback_to_software(); return; }
     if (gl_renderer.is_valid() && gl_renderer->error() < 0) { fallback_to_software(); return; }
-    if (gl_renderer.is_null() && renderer.error() < 0) {
+    if (gl_renderer.is_null() && vulkan_renderer.is_null() && renderer.error() < 0) {
         active = false;
         emit_signal("failed", String("PC video rendering failed: ") + mpv_error_string(renderer.error()));
         return;
     }
-    for (int count = 0; count < 64; ++count) {
+    if (uses_video_clock()) {
+        if (!prepared) {
+            if (!update_size()) { fallback_to_software(); return; }
+            prepared = true;
+            video_clock_origin = playback_time_ms() - position;
+            watchdog.reset(playback_time_ms());
+            emit_signal("prepared");
+            return;
+        }
+        if (!paused && video_clock_started && !seeking) position = int64_t(playback_time_ms() - video_clock_origin);
+        if (!paused && video_clock_started && ((duration > 0 && position >= duration) || (duration == 0 && vulkan_renderer->ended()))) {
+            active = false;
+            emit_signal("ended");
+            return;
+        }
+    }
+    for (int count = 0; !uses_video_clock() && count < 64; ++count) {
         auto *event = mpv_wait_event(player, 0);
         if (event->event_id == MPV_EVENT_NONE) break;
         if (event->event_id == MPV_EVENT_PROPERTY_CHANGE) {
@@ -339,10 +398,18 @@ void JellyframeMpv::_process(double) {
         }
     }
     bool received_frame = upload_frame();
-    report_diagnostics();
-    if (prepared && watchdog.stalled(playback_time_ms(), received_frame, paused, buffering || seeking)) {
-        if (gl_renderer.is_valid()) { fallback_to_software(); return; }
+    update_video_buffering();
+    if (log_video_stats && playback_time_ms() - last_diagnostics_time >= 5000) {
+        last_diagnostics_time = playback_time_ms();
+        UtilityFunctions::print("PC video statistics: ", playback_diagnostics());
+    }
+    if (prepared && watchdog.stalled(playback_time_ms(), received_frame, paused, buffering || video_buffering || seeking)) {
+        if (gl_renderer.is_valid() || vulkan_renderer.is_valid()) { fallback_to_software(); return; }
         active = false;
         emit_signal("failed", "Video playback stalled.");
     }
 }
+
+Dictionary JellyframeMpv::video_shader_parameters() const {
+    return vulkan_renderer.is_valid() ? vulkan_renderer->shader_parameters() : Dictionary();
+}

native/pc/mpv_video.h

@@ -2,6 +2,7 @@
 
 #include "render_worker.h"
 #include "render_gl.h"
+#include "render_vulkan.h"
 #include "playback_watchdog.h"
 #include <godot_cpp/classes/image_texture.hpp>
 #include <godot_cpp/classes/node.hpp>
@@ -17,8 +18,10 @@ public:
     int64_t position_ms() const;
     int64_t duration_ms() const;
     bool is_buffering() const;
-    godot::Dictionary playback_diagnostics() const;
     godot::String rendering_backend() const;
+    godot::Dictionary playback_diagnostics() const;
+    // Vulkan exposes YUV planes; texture_changed carries the luma texture.
+    godot::Dictionary video_shader_parameters() const;
     void stop_video();
     void _process(double delta) override;
 
@@ -26,18 +29,27 @@ protected:
     static void _bind_methods();
 
 private:
-    godot::String initialize();
+    godot::String initialize(int64_t start_ms);
     bool update_size();
     bool upload_frame();
-    void report_diagnostics();
     void fallback_to_software();
     void update_property(const mpv_event &event);
     void shutdown();
+    bool uses_video_clock() const;
+    void update_video_buffering();
+    void apply_audio_pause();
+    bool video_buffering = false;
+    uint64_t video_buffer_count = 0;
+    uint64_t video_clock_origin = 0;
+    bool video_clock_started = false;
+    bool log_video_stats = false;
+    uint64_t last_diagnostics_time = 0;
     mpv_handle *player = nullptr;
     RenderWorker renderer;
     godot::Ref<RenderGl> gl_renderer;
+    godot::Ref<RenderVulkan> vulkan_renderer;
     VideoFrame frame;
-    godot::Ref<godot::ImageTexture> texture;
+    godot::Ref<godot::Texture2D> texture;
     int64_t position = 0;
     int64_t duration = 0;
     bool active = false;
@@ -45,11 +57,6 @@ private:
     bool paused = false;
     bool buffering = false;
     bool seeking = false;
-    bool diagnostics_enabled = false;
-    uint64_t uploaded_frames = 0;
-    uint64_t diagnostic_frames = 0;
-    uint64_t diagnostic_time_ms = 0;
-    double upload_cpu_ms = 0;
     bool software_only = false;
     godot::String current_url;
     godot::String current_authorization;

native/pc/register_types.cpp

@@ -6,6 +6,7 @@ using namespace godot;
 static void initialize(ModuleInitializationLevel level) {
     if (level == MODULE_INITIALIZATION_LEVEL_SCENE) {
         ClassDB::register_internal_class<RenderGl>();
+        ClassDB::register_internal_class<RenderVulkan>();
         ClassDB::register_class<JellyframeMpv>();
     }
 }

native/pc/render_gl.cpp

@@ -2,7 +2,6 @@
 #include <godot_cpp/classes/image.hpp>
 #include <godot_cpp/classes/rendering_server.hpp>
 #include <godot_cpp/variant/callable_method_pointer.hpp>
-#include <chrono>
 #include <future>
 
 using namespace godot;
@@ -121,7 +120,6 @@ int RenderGl::select_ready_slot() {
 }
 
 void RenderGl::present_on_render_thread() {
-    auto started = std::chrono::steady_clock::now();
     std::unique_lock<std::mutex> lock(slots_mutex, std::try_to_lock);
     if (lock.owns_lock() && display_texture) {
         int selected = select_ready_slot();
@@ -149,7 +147,6 @@ void RenderGl::present_on_render_thread() {
             wake.notify_one();
         }
     }
-    present_time_us = std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::steady_clock::now() - started).count();
     queued = false;
 }
 
@@ -183,6 +180,4 @@ void RenderGl::stop() {
 }
 
 int RenderGl::error() const { return render_error; }
-double RenderGl::render_call_ms() const { return double(render_time_us.load()) / 1000.0; }
-double RenderGl::present_cpu_ms() const { return double(present_time_us.load()) / 1000.0; }
 Ref<ImageTexture> RenderGl::get_texture() const { return texture; }

native/pc/render_gl.h

@@ -19,8 +19,6 @@ public:
     bool take_frame();
     void stop();
     int error() const;
-    double render_call_ms() const;
-    double present_cpu_ms() const;
     godot::Ref<godot::ImageTexture> get_texture() const;
 
 protected:
@@ -65,8 +63,6 @@ private:
     std::atomic<bool> dirty{false};
     std::atomic<int> render_error{0};
     std::atomic<uint64_t> dimensions{(uint64_t(1920) << 32) | 1080};
-    std::atomic<int64_t> render_time_us{0};
-    std::atomic<int64_t> present_time_us{0};
     std::array<Slot, 2> slots;
     std::mutex slots_mutex;
     uint64_t next_sequence = 0;

native/pc/render_gl_worker.cpp

@@ -53,9 +53,7 @@ bool RenderGl::render_slot(mpv_render_context *renderer, Slot &slot) {
         {MPV_RENDER_PARAM_BLOCK_FOR_TARGET_TIME, &block},
         {MPV_RENDER_PARAM_INVALID, nullptr}
     };
-    auto started = std::chrono::steady_clock::now();
     int error = mpv_render_context_render(renderer, params);
-    render_time_us = std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::steady_clock::now() - started).count();
     if (error < 0) { render_error = error; return false; }
     void *ready = api.fence(gl::sync_complete, 0);
     api.flush();

native/pc/render_vulkan.cpp

@@ -0,0 +1,181 @@
+#include "render_vulkan.h"
+#include <godot_cpp/classes/rd_texture_format.hpp>
+#include <godot_cpp/classes/rd_texture_view.hpp>
+#include <godot_cpp/classes/rendering_server.hpp>
+#include <godot_cpp/variant/callable_method_pointer.hpp>
+#include <mpv/client.h>
+#include <chrono>
+
+using namespace godot;
+
+void RenderVulkan::run_sync(void (RenderVulkan::*operation)()) {
+    auto *server = RenderingServer::get_singleton();
+    if (server->is_on_render_thread()) { (this->*operation)(); return; }
+    {
+        std::lock_guard<std::mutex> lock(sync_mutex);
+        sync_operation = operation;
+        sync_complete = false;
+    }
+    server->call_on_render_thread(callable_mp(this, &RenderVulkan::dispatch_sync));
+    std::unique_lock<std::mutex> lock(sync_mutex);
+    sync_condition.wait(lock, [this] { return sync_complete; });
+}
+
+void RenderVulkan::dispatch_sync() {
+    (this->*sync_operation)();
+    { std::lock_guard<std::mutex> lock(sync_mutex); sync_complete = true; }
+    sync_condition.notify_one();
+}
+
+void RenderVulkan::initialize_on_render_thread() {
+    device = RenderingServer::get_singleton()->get_rendering_device();
+    if (!device) { render_error = MPV_ERROR_UNSUPPORTED; return; }
+}
+
+int RenderVulkan::start(String url, String authorization, int64_t start_ms) {
+    run_sync(&RenderVulkan::initialize_on_render_thread);
+    if (render_error < 0) return render_error;
+    decoder.set_frame_callback(wakeup, this);
+    int result = decoder.start(url.utf8().get_data(), authorization.utf8().get_data(), start_ms);
+    return result < 0 ? MPV_ERROR_LOADING_FAILED : 0;
+}
+
+void RenderVulkan::destroy_textures() {
+    for (auto &texture : textures) {
+        if (texture.is_valid()) texture->set_texture_rd_rid(RID());
+        texture.unref();
+    }
+    for (auto &plane : planes) {
+        if (plane.is_valid()) device->free_rid(plane);
+        plane = RID();
+    }
+    target_width = target_height = 0;
+}
+
+bool RenderVulkan::create_textures() {
+    destroy_textures();
+    Ref<RDTextureFormat> format;
+    format.instantiate();
+    format->set_texture_type(RenderingDevice::TEXTURE_TYPE_2D);
+    format->set_usage_bits(RenderingDevice::TEXTURE_USAGE_SAMPLING_BIT | RenderingDevice::TEXTURE_USAGE_CAN_UPDATE_BIT);
+    Ref<RDTextureView> view;
+    view.instantiate();
+    for (int index = 0; index < frame.plane_count; ++index) {
+        format->set_format(frame.sample_bytes == 1 ?
+            (index && frame.interleaved ? RenderingDevice::DATA_FORMAT_R8G8_UNORM : RenderingDevice::DATA_FORMAT_R8_UNORM) :
+            (index && frame.interleaved ? RenderingDevice::DATA_FORMAT_R16G16_UNORM : RenderingDevice::DATA_FORMAT_R16_UNORM));
+        format->set_width(index ? (frame.storage_width + 1) / 2 : frame.storage_width);
+        format->set_height(index ? (frame.storage_height + 1) / 2 : frame.storage_height);
+        planes[index] = device->texture_create(format, view);
+        if (!planes[index].is_valid()) return false;
+        textures[index].instantiate();
+        textures[index]->set_texture_rd_rid(planes[index]);
+    }
+    source_width = frame.width;
+    source_height = frame.height;
+    storage_width = frame.storage_width;
+    storage_height = frame.storage_height;
+    target_width = frame.display_width;
+    target_height = frame.display_height;
+    sample_bytes = frame.sample_bytes;
+    interleaved = frame.interleaved;
+    return true;
+}
+
+void RenderVulkan::present_on_render_thread() {
+    if (!stopping && decoder.take_frame(frame) && frame.generation == decoder.current_generation()) {
+        present_frame();
+        presentation_us += std::chrono::duration_cast<std::chrono::microseconds>(std::chrono::steady_clock::now() - presentation_started).count();
+        if (render_error >= 0 && frame.generation == decoder.current_generation()) {
+            const Dictionary parameters = frame_parameters();
+            std::lock_guard<std::mutex> lock(texture_mutex);
+            ready_parameters = parameters;
+            ready_size = Vector2i(frame.display_width, frame.display_height);
+            ready_generation = frame.generation;
+            ready_timestamp = frame.timestamp;
+            ++presented_frames;
+            frame_ready = true;
+        }
+    }
+    queued = false;
+}
+
+void RenderVulkan::wakeup(void *owner) { static_cast<RenderVulkan *>(owner)->queue_frame(); }
+
+void RenderVulkan::queue_frame() {
+    if (stopping || queued.exchange(true)) return;
+    presentation_started = std::chrono::steady_clock::now();
+    RenderingServer::get_singleton()->call_on_render_thread(callable_mp(this, &RenderVulkan::present_on_render_thread));
+}
+
+void RenderVulkan::present_frame() {
+    if ((frame.display_width != target_width || frame.display_height != target_height ||
+            frame.width != source_width || frame.height != source_height || frame.storage_width != storage_width || frame.storage_height != storage_height ||
+            frame.sample_bytes != sample_bytes || frame.interleaved != interleaved) && !create_textures()) {
+        render_error = MPV_ERROR_NOMEM;
+        return;
+    }
+    for (int index = 0; index < frame.plane_count; ++index) {
+        if (device->texture_update(planes[index], 0, frame.planes[index].data()) != OK) {
+            render_error = MPV_ERROR_GENERIC;
+            return;
+        }
+    }
+}
+
+bool RenderVulkan::take_frame() {
+    if (!stopping && render_error >= 0 && !queued && decoder.has_frame()) queue_frame();
+    std::lock_guard<std::mutex> lock(texture_mutex);
+    if (!frame_ready.exchange(false) || ready_generation != decoder.current_generation()) return false;
+    presented_parameters = ready_parameters;
+    presented_size = ready_size;
+    presented_timestamp = ready_timestamp;
+    return true;
+}
+
+Dictionary RenderVulkan::diagnostics() const {
+    Dictionary values = decoder.diagnostics();
+    uint64_t count = presented_frames.load();
+    values["direct_yuv"] = true;
+    values["presented_frames"] = int64_t(count);
+    values["presentation_ms"] = count ? double(presentation_us.load()) / count / 1000.0 : 0;
+    return values;
+}
+
+int RenderVulkan::error() const {
+    return render_error < 0 ? render_error.load() : decoder.error() < 0 ? MPV_ERROR_GENERIC : 0;
+}
+
+void RenderVulkan::destroy_on_render_thread() {
+    if (!device) return;
+    destroy_textures();
+    device = nullptr;
+}
+
+void RenderVulkan::stop() {
+    stopping = true;
+    decoder.stop();
+    run_sync(&RenderVulkan::destroy_on_render_thread);
+    presented_parameters.clear();
+    ready_parameters.clear();
+    frame = VideoPlanes();
+}
+
+Dictionary RenderVulkan::frame_parameters() const {
+    Dictionary values;
+    values["direct_yuv"] = true;
+    values["y_plane"] = textures[0];
+    values["u_plane"] = textures[1];
+    values["v_plane"] = frame.interleaved ? textures[1] : textures[2];
+    values["source_size"] = Vector2(frame.width, frame.height);
+    values["video_rotation"] = frame.rotation;
+    values["interleaved_chroma"] = frame.interleaved;
+    values["chroma_in_alpha"] = frame.interleaved && frame.sample_bytes == 1;
+    values["color_coefficients"] = Vector2(frame.kr, frame.kb);
+    values["full_range"] = frame.full_range;
+    values["transfer"] = frame.transfer;
+    values["sample_scale"] = frame.sample_scale;
+    values["code_max"] = frame.code_max;
+    values["source_peak"] = frame.source_peak;
+    return values;
+}

native/pc/render_vulkan.h

@@ -0,0 +1,71 @@
+#pragma once
+
+#include "video_decoder.h"
+#include <godot_cpp/classes/ref_counted.hpp>
+#include <godot_cpp/classes/rendering_device.hpp>
+#include <godot_cpp/classes/texture2drd.hpp>
+#include <chrono>
+
+class RenderVulkan : public godot::RefCounted {
+    GDCLASS(RenderVulkan, godot::RefCounted)
+public:
+    int start(godot::String url, godot::String authorization, int64_t start_ms);
+    void stop();
+    void set_clock(int64_t milliseconds) { decoder.set_clock(milliseconds); }
+    void seek(int64_t milliseconds) { decoder.seek(milliseconds); frame_ready = false; presented_timestamp = -1; }
+    int64_t timestamp_ms() const { return presented_timestamp; }
+    bool take_frame();
+    int error() const;
+    bool has_audio() const { return decoder.has_audio(); }
+    int width() const { return presented_size.x > 0 ? presented_size.x : decoder.width(); }
+    int height() const { return presented_size.y > 0 ? presented_size.y : decoder.height(); }
+    int64_t duration_ms() const { return decoder.duration_ms(); }
+    bool ended() const { return decoder.ended(); }
+    bool read_ahead_ready() const { return decoder.read_ahead_ready(); }
+    godot::Dictionary diagnostics() const;
+    godot::Dictionary shader_parameters() const { return presented_parameters; }
+protected:
+    static void _bind_methods() {}
+private:
+    void run_sync(void (RenderVulkan::*operation)());
+    void dispatch_sync();
+    void initialize_on_render_thread();
+    void present_on_render_thread();
+    void present_frame();
+    void queue_frame();
+    static void wakeup(void *owner);
+    void destroy_on_render_thread();
+    void destroy_textures();
+    bool create_textures();
+    VideoDecoder decoder;
+    VideoPlanes frame;
+    godot::RenderingDevice *device = nullptr;
+    std::array<godot::Ref<godot::Texture2DRD>, 3> textures;
+    godot::Dictionary ready_parameters;
+    godot::Dictionary presented_parameters;
+    godot::Dictionary frame_parameters() const;
+    godot::Vector2i ready_size;
+    godot::Vector2i presented_size;
+    std::mutex texture_mutex;
+    uint64_t ready_generation = 0;
+    int64_t ready_timestamp = -1;
+    int64_t presented_timestamp = -1;
+    std::array<godot::RID, 3> planes;
+    int target_width = 0;
+    int target_height = 0;
+    int source_width = 0;
+    int source_height = 0;
+    int storage_width = 0;
+    int storage_height = 0;
+    int sample_bytes = 0;
+    bool interleaved = false;
+    std::atomic<int> render_error{0};
+    std::atomic<uint64_t> presented_frames{0}, presentation_us{0};
+    std::atomic<bool> queued{false}, frame_ready{false};
+    std::atomic<bool> stopping{false};
+    std::chrono::steady_clock::time_point presentation_started;
+    std::mutex sync_mutex;
+    std::condition_variable sync_condition;
+    bool sync_complete = false;
+    void (RenderVulkan::*sync_operation)() = nullptr;
+};

native/pc/render_worker.cpp

@@ -67,10 +67,7 @@ void RenderWorker::render_loop(mpv_render_context *renderer) {
             {MPV_RENDER_PARAM_SW_POINTER, frame.pixels.ptrw()},
             {MPV_RENDER_PARAM_INVALID, nullptr}
         };
-        auto render_started = std::chrono::steady_clock::now();
         int result = mpv_render_context_render(renderer, params);
-        frame.render_time_us = std::chrono::duration_cast<std::chrono::microseconds>(
-            std::chrono::steady_clock::now() - render_started).count();
         if (result < 0) {
             render_error = result;
             break;

native/pc/render_worker.h

@@ -13,7 +13,6 @@ struct VideoFrame {
     int width = 0;
     int height = 0;
     godot::PackedByteArray pixels;
-    int64_t render_time_us = 0;
 };
 
 class RenderWorker {

native/pc/stream_identity.h

@@ -0,0 +1,3 @@
+#pragma once
+
+inline constexpr const char *JELLYFRAME_STREAM_USER_AGENT = "Jellyframe";

native/pc/video_decoder.cpp

@@ -0,0 +1,271 @@
+#include "video_decoder.h"
+#include "stream_identity.h"
+extern "C" {
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+#include <libavutil/avutil.h>
+#include <libavutil/hwcontext.h>
+#include <libavutil/display.h>
+#include <libavutil/pixdesc.h>
+#include <libavutil/time.h>
+#include <libswscale/swscale.h>
+}
+#include <algorithm>
+#include <chrono>
+#include <cstring>
+#include <cmath>
+#include <future>
+
+VideoDecoder::~VideoDecoder() { stop(); }
+
+void VideoDecoder::configure_hardware(const AVCodec *decoder) {
+#ifdef _WIN32
+    const AVHWDeviceType devices[] = {AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_D3D11VA};
+#else
+    const AVHWDeviceType devices[] = {AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_CUDA};
+#endif
+    for (auto device_type : devices) {
+        for (int index = 0; ; ++index) {
+            const AVCodecHWConfig *config = avcodec_get_hw_config(decoder, index);
+            if (!config) break;
+            if (config->device_type != device_type || !(config->methods & AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX)) continue;
+            if (av_hwdevice_ctx_create(&codec->hw_device_ctx, device_type, nullptr, nullptr, 0) < 0) continue;
+            hardware_device = av_hwdevice_get_type_name(device_type);
+            hardware_format = config->pix_fmt;
+            hardware_attempted = false;
+            codec->opaque = this;
+            codec->get_format = [](AVCodecContext *context, const AVPixelFormat *formats) {
+                auto *self = static_cast<VideoDecoder *>(context->opaque);
+                if (!self->hardware_attempted) {
+                    self->hardware_attempted = true;
+                    for (auto *format = formats; *format != AV_PIX_FMT_NONE; ++format) {
+                        if (*format == self->hardware_format) return *format;
+                    }
+                }
+                for (auto *format = formats; *format != AV_PIX_FMT_NONE; ++format) {
+                    const AVPixFmtDescriptor *description = av_pix_fmt_desc_get(*format);
+                    if (description && !(description->flags & AV_PIX_FMT_FLAG_HWACCEL)) return *format;
+                }
+                return AV_PIX_FMT_NONE;
+            };
+            return;
+        }
+    }
+}
+
+int VideoDecoder::interrupt(void *owner) {
+    auto *self = static_cast<VideoDecoder *>(owner);
+    int64_t deadline = self->io_deadline.load();
+    return self->stopping || self->seek_interrupt || (deadline && av_gettime_relative() > deadline);
+}
+
+int VideoDecoder::open(const std::string &url, const std::string &authorization) {
+    input = avformat_alloc_context();
+    if (!input) return AVERROR(ENOMEM);
+    input->interrupt_callback = {interrupt, this};
+    AVDictionary *options = nullptr;
+    if (!authorization.empty()) {
+        if (authorization.find_first_of("\r\n") != std::string::npos) return AVERROR(EINVAL);
+        std::string header = "Authorization: " + authorization + "\r\n";
+        av_dict_set(&options, "headers", header.c_str(), 0);
+    }
+    av_dict_set(&options, "tls_verify", "1", 0);
+    av_dict_set(&options, "user_agent", JELLYFRAME_STREAM_USER_AGENT, 0);
+    av_dict_set(&options, "rw_timeout", "15000000", 0);
+    io_deadline = av_gettime_relative() + 15000000;
+    int result = avformat_open_input(&input, url.c_str(), nullptr, &options);
+    av_dict_free(&options);
+    if (result < 0) return result;
+    result = avformat_find_stream_info(input, nullptr);
+    if (result < 0) return result;
+    const AVCodec *decoder = nullptr;
+    stream_index = av_find_best_stream(input, AVMEDIA_TYPE_VIDEO, -1, -1, &decoder, 0);
+    if (stream_index < 0) return stream_index;
+    audio = av_find_best_stream(input, AVMEDIA_TYPE_AUDIO, -1, -1, nullptr, 0) >= 0;
+    codec = avcodec_alloc_context3(nullptr);
+    if (!codec) return AVERROR(ENOMEM);
+    result = avcodec_parameters_to_context(codec, input->streams[stream_index]->codecpar);
+    if (result < 0) return result;
+    codec->thread_count = std::min(8u, std::max(1u, std::thread::hardware_concurrency()));
+    const AVCodec *software_decoder = decoder;
+    if (codec->codec_id == AV_CODEC_ID_AV1) {
+        const AVCodec *native_decoder = avcodec_find_decoder_by_name("av1");
+        if (native_decoder) decoder = native_decoder;
+    }
+    configure_hardware(decoder);
+    if (!codec->hw_device_ctx) decoder = software_decoder;
+    else codec->thread_count = 1;
+    result = avcodec_open2(codec, decoder, nullptr);
+    if (result < 0) return result;
+    codec_name = decoder->name;
+    return read_geometry();
+}
+
+int VideoDecoder::read_geometry() {
+    source_width = codec->width;
+    source_height = codec->height;
+    auto *stream = input->streams[stream_index];
+#if LIBAVFORMAT_VERSION_MAJOR >= 61
+    const AVPacketSideData *display = av_packet_side_data_get(stream->codecpar->coded_side_data,
+        stream->codecpar->nb_coded_side_data, AV_PKT_DATA_DISPLAYMATRIX);
+    const uint8_t *matrix = display ? display->data : nullptr;
+    size_t matrix_size = display ? display->size : 0;
+#else
+    size_t matrix_size = 0;
+    const uint8_t *matrix = av_stream_get_side_data(stream, AV_PKT_DATA_DISPLAYMATRIX, &matrix_size);
+#endif
+    if (matrix && matrix_size >= 9 * sizeof(int32_t)) {
+        double angle = -av_display_rotation_get(reinterpret_cast<const int32_t *>(matrix));
+        if (!std::isfinite(angle) || std::abs(angle / 90.0 - std::round(angle / 90.0)) > 0.001) return AVERROR(ENOSYS);
+        rotation = (int(std::round(angle / 90.0)) % 4 + 4) % 4;
+    }
+    AVRational aspect = av_guess_sample_aspect_ratio(input, stream, nullptr);
+    if (aspect.num > 0 && aspect.den > 0) source_width = int(av_rescale(source_width, aspect.num, aspect.den));
+    if (rotation % 2) std::swap(source_width, source_height);
+    if (source_width <= 0 || source_height <= 0 || source_width > 8192 || source_height > 8192 ||
+            int64_t(source_width) * source_height > 33554432) return AVERROR(ENOSYS);
+    origin_us = input->start_time == AV_NOPTS_VALUE ? 0 : input->start_time;
+    duration = input->duration == AV_NOPTS_VALUE ? 0 : input->duration / 1000;
+    io_deadline = 0;
+    return 0;
+}
+
+int VideoDecoder::start(const std::string &url, const std::string &authorization, int64_t start_ms) {
+    stop();
+    stopping = false;
+    decode_error = 0;
+    hardware_active = false;
+    pinned_download = false;
+    hardware_device.clear();
+    corrupt_packets = 0;
+    decoded_frames = dropped_frames = converted_frames = 0;
+    download_us = conversion_us = 0;
+    read_us = decode_us = read_bytes = 0;
+    buffered_ms = buffered_bytes = 0;
+    reader_ended = seek_interrupt = false;
+    end_of_stream = false;
+    clock = std::max<int64_t>(0, start_ms);
+    seek_target = clock > 0 ? clock : -1;
+    discard_before = clock - 100;
+    last_publish_us = 0;
+    decoded_timestamp = 0;
+    generation = 0;
+    rotation = 0;
+    std::promise<int> initialized;
+    auto result = initialized.get_future();
+    worker = std::thread([this, url, authorization, ready = std::move(initialized)]() mutable {
+        int error = open(url, authorization);
+        ready.set_value(error);
+        if (error >= 0) {
+            reader = std::thread(&VideoDecoder::read_loop, this);
+            decode_loop();
+            stopping = true;
+            wake.notify_all();
+            reader.join();
+        }
+        close();
+    });
+    return result.get();
+}
+
+void VideoDecoder::close() {
+    sws_freeContext(scaler);
+    scaler = nullptr;
+    avcodec_free_context(&codec);
+    avformat_close_input(&input);
+}
+
+void VideoDecoder::stop() {
+    stopping = true;
+    wake.notify_all();
+    if (worker.joinable()) worker.join();
+    std::lock_guard<std::mutex> lock(mutex);
+    clear_packets();
+    pending = VideoPlanes();
+    staging = VideoPlanes();
+    frame_ready = false;
+}
+
+void VideoDecoder::set_clock(int64_t milliseconds) {
+    { std::lock_guard<std::mutex> lock(mutex); clock = milliseconds; }
+    wake.notify_all();
+}
+
+void VideoDecoder::seek(int64_t milliseconds) {
+    {
+        std::lock_guard<std::mutex> lock(mutex);
+        seek_target = std::max<int64_t>(0, milliseconds);
+        clock = seek_target;
+        discard_before = seek_target - 100;
+        last_publish_us = 0;
+        ++generation;
+        seek_interrupt = true;
+        clear_packets();
+        reader_ended = false;
+        end_of_stream = false;
+        frame_ready = false;
+    }
+    wake.notify_all();
+}
+
+bool VideoDecoder::take_frame(VideoPlanes &frame) {
+    std::lock_guard<std::mutex> lock(mutex);
+    if (!frame_ready) return false;
+    std::swap(frame, pending);
+    frame_ready = false;
+    wake.notify_all();
+    return true;
+}
+
+bool VideoDecoder::has_frame() {
+    std::lock_guard<std::mutex> lock(mutex);
+    return frame_ready;
+}
+
+void VideoDecoder::decode_loop() {
+    AVPacket *packet = av_packet_alloc();
+    AVFrame *frame = av_frame_alloc();
+    if (!packet || !frame) decode_error = AVERROR(ENOMEM);
+    uint64_t codec_generation = 0;
+    int consecutive_errors = 0;
+    while (!stopping && decode_error >= 0) {
+        int64_t started = av_gettime_relative();
+        int result = avcodec_receive_frame(codec, frame);
+        decode_us += av_gettime_relative() - started;
+        if (result >= 0) {
+            consecutive_errors = 0;
+            ++decoded_frames;
+            bool keep_going = publish(frame, codec_generation);
+            av_frame_unref(frame);
+            if (!keep_going) break;
+            continue;
+        }
+        if (result == AVERROR_EOF) {
+            end_of_stream = true;
+        } else if (result == AVERROR_INVALIDDATA) {
+            ++corrupt_packets;
+            if (++consecutive_errors > 8) { decode_error = result; break; }
+        } else if (result != AVERROR(EAGAIN)) { decode_error = result; break; }
+        bool flush = false;
+        if (!read_packet(packet, codec_generation, flush, result)) break;
+        if (result < 0 && (flush || result != AVERROR_EOF)) { decode_error = result; break; }
+        if (flush) {
+            avcodec_flush_buffers(codec);
+            end_of_stream = false;
+            consecutive_errors = 0;
+            continue;
+        }
+        started = av_gettime_relative();
+        bool draining = result == AVERROR_EOF;
+        result = avcodec_send_packet(codec, draining ? nullptr : packet);
+        decode_us += av_gettime_relative() - started;
+        av_packet_unref(packet);
+        if (result == AVERROR_INVALIDDATA && ++consecutive_errors <= 8) {
+            ++corrupt_packets;
+            continue;
+        }
+        if (result < 0) { decode_error = result; break; }
+    }
+    av_frame_free(&frame);
+    av_packet_free(&packet);
+}

native/pc/video_decoder.h

@@ -0,0 +1,135 @@
+#pragma once
+
+#include "video_plane.h"
+
+#include <godot_cpp/variant/packed_byte_array.hpp>
+#include <godot_cpp/variant/dictionary.hpp>
+#include <array>
+#include <atomic>
+#include <condition_variable>
+#include <deque>
+#include <mutex>
+#include <string>
+#include <thread>
+
+struct AVFormatContext;
+struct AVCodecContext;
+struct AVFrame;
+struct AVPacket;
+struct SwsContext;
+
+struct VideoPlanes {
+    int width = 0;
+    int height = 0;
+    int storage_width = 0;
+    int storage_height = 0;
+    int display_width = 0;
+    int display_height = 0;
+    int rotation = 0;
+    int plane_count = 3;
+    int sample_bytes = 2;
+    bool interleaved = false;
+    float sample_scale = 65535;
+    float code_max = 1023;
+    int64_t timestamp = 0;
+    uint64_t generation = 0;
+    float kr = 0.2126f;
+    float kb = 0.0722f;
+    float full_range = 0;
+    float transfer = 0;
+    float source_peak = 1000.f / 203.f;
+    std::array<VideoPlane, 3> planes;
+};
+
+class VideoDecoder {
+public:
+    ~VideoDecoder();
+    int start(const std::string &url, const std::string &authorization, int64_t start_ms);
+    void stop();
+    void set_clock(int64_t milliseconds);
+    void seek(int64_t milliseconds);
+    bool take_frame(VideoPlanes &frame);
+    int error() const { return decode_error; }
+    bool has_audio() const { return audio; }
+    int width() const { return source_width; }
+    int height() const { return source_height; }
+    int64_t duration_ms() const { return duration; }
+    bool ended() const { return end_of_stream; }
+    bool read_ahead_ready() const {
+        return reader_ended || buffered_ms >= 1000 || buffered_bytes >= max_buffer_bytes || buffered_packets >= max_buffer_packets;
+    }
+    godot::Dictionary diagnostics() const;
+    void set_frame_callback(void (*callback)(void *), void *owner) { frame_callback = callback; frame_owner = owner; }
+    bool has_frame();
+    uint64_t current_generation() const { return generation; }
+
+private:
+    static constexpr int64_t max_buffer_ms = 30000;
+    static constexpr uint64_t max_buffer_bytes = 256 * 1048576;
+    static constexpr size_t max_buffer_packets = 4096;
+    static int interrupt(void *owner);
+    void configure_hardware(const struct AVCodec *decoder);
+    int open(const std::string &url, const std::string &authorization);
+    int read_geometry();
+    void decode_loop();
+    void read_loop();
+    bool read_packet(AVPacket *packet, uint64_t &packet_generation, bool &flush, int &error);
+    void clear_packets();
+    void update_buffer_size();
+    bool publish(AVFrame *frame, uint64_t frame_generation);
+    bool convert(AVFrame *frame, VideoPlanes &output);
+    bool prepare_planes(AVFrame *frame, VideoPlanes &output, int storage_width, int storage_height);
+    bool download_planes(AVFrame *frame, VideoPlanes &output);
+    void close();
+    AVFormatContext *input = nullptr;
+    AVCodecContext *codec = nullptr;
+    SwsContext *scaler = nullptr;
+    int stream_index = -1;
+    int hardware_format = -1;
+    bool hardware_attempted = false;
+    int source_width = 0;
+    int source_height = 0;
+    int rotation = 0;
+    bool audio = false;
+    std::string codec_name;
+    std::string hardware_device;
+    std::atomic<uint64_t> corrupt_packets{0};
+    std::atomic<bool> hardware_active{false};
+    std::atomic<bool> pinned_download{false};
+    std::atomic<int> active_transfer{0};
+    std::atomic<uint64_t> decoded_frames{0}, dropped_frames{0}, converted_frames{0};
+    std::atomic<uint64_t> download_us{0}, conversion_us{0};
+    std::atomic<uint64_t> read_us{0}, decode_us{0}, read_bytes{0};
+    std::atomic<int64_t> buffered_ms{0};
+    std::atomic<uint64_t> buffered_bytes{0};
+    std::atomic<size_t> buffered_packets{0};
+    std::atomic<bool> reader_ended{false}, seek_interrupt{false};
+    int64_t origin_us = 0;
+    int64_t duration = 0;
+    std::atomic<bool> end_of_stream{false};
+    std::thread worker;
+    std::thread reader;
+    std::atomic<bool> stopping{false};
+    std::atomic<int> decode_error{0};
+    std::atomic<int64_t> io_deadline{0};
+    std::mutex mutex;
+    std::condition_variable wake;
+    struct QueuedPacket {
+        AVPacket *packet = nullptr;
+        uint64_t generation = 0;
+        bool flush = false;
+        int error = 0;
+    };
+    std::deque<QueuedPacket> packets;
+    VideoPlanes pending;
+    VideoPlanes staging;
+    bool frame_ready = false;
+    int64_t clock = 0;
+    int64_t seek_target = -1;
+    int64_t discard_before = -1;
+    int64_t last_publish_us = 0;
+    std::atomic<int64_t> decoded_timestamp{0};
+    std::atomic<uint64_t> generation{0};
+    void (*frame_callback)(void *) = nullptr;
+    void *frame_owner = nullptr;
+};

native/pc/video_decoder_frames.cpp

@@ -0,0 +1,82 @@
+#include "video_decoder.h"
+#include <godot_cpp/variant/variant.hpp>
+extern "C" {
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+#include <libavutil/hwcontext.h>
+#include <libavutil/time.h>
+#include <libavutil/pixfmt.h>
+#include <libswscale/swscale.h>
+}
+#include <algorithm>
+#include <cstring>
+
+bool VideoDecoder::publish(AVFrame *frame, uint64_t frame_generation) {
+    VideoPlanes &output = staging;
+    {
+        std::lock_guard<std::mutex> lock(mutex);
+        if (generation != frame_generation) { ++dropped_frames; return true; }
+    }
+    int64_t timestamp = frame->best_effort_timestamp;
+    output.timestamp = timestamp == AV_NOPTS_VALUE ? 0 :
+        (av_rescale_q(timestamp, input->streams[stream_index]->time_base, AV_TIME_BASE_Q) - origin_us) / 1000;
+    decoded_timestamp = output.timestamp;
+    {
+        std::lock_guard<std::mutex> lock(mutex);
+        if (output.timestamp < discard_before ||
+                (output.timestamp < clock - 100 && av_gettime_relative() - last_publish_us < 100000)) {
+            ++dropped_frames;
+            return true;
+        }
+        discard_before = -1;
+    }
+    int64_t started = av_gettime_relative();
+    hardware_active = frame->hw_frames_ctx != nullptr;
+    bool converted;
+    if (frame->hw_frames_ctx) {
+        converted = download_planes(frame, output);
+        download_us += av_gettime_relative() - started;
+    } else {
+        pinned_download = false;
+        converted = convert(frame, output);
+        conversion_us += av_gettime_relative() - started;
+    }
+    ++converted_frames;
+    if (!converted) { decode_error = AVERROR_INVALIDDATA; return false; }
+    output.generation = frame_generation;
+    std::unique_lock<std::mutex> lock(mutex);
+    wake.wait(lock, [this, &output, frame_generation] {
+        return stopping || generation != frame_generation || (!frame_ready && output.timestamp <= clock + 30);
+    });
+    if (stopping) return false;
+    if (generation != frame_generation) { ++dropped_frames; return true; }
+    std::swap(pending, output);
+    frame_ready = true;
+    last_publish_us = av_gettime_relative();
+    lock.unlock();
+    if (frame_callback) frame_callback(frame_owner);
+    return true;
+}
+
+godot::Dictionary VideoDecoder::diagnostics() const {
+    godot::Dictionary values;
+    values["codec"] = godot::String(codec_name.c_str());
+    values["hardware_device"] = hardware_active ? godot::String(hardware_device.c_str()) : godot::String("none");
+    values["hardware_decoding"] = hardware_active.load();
+    values["pinned_download"] = pinned_download.load();
+    values["transfer"] = active_transfer.load() == 1 ? "pq" : active_transfer.load() == 2 ? "hlg" : "sdr";
+    values["decoded_frames"] = int64_t(decoded_frames.load());
+    values["dropped_frames"] = int64_t(dropped_frames.load());
+    values["corrupt_packets"] = int64_t(corrupt_packets.load());
+    values["decode_error"] = decode_error.load();
+    values["decoded_timestamp_ms"] = decoded_timestamp.load();
+    values["read_ahead_ms"] = buffered_ms.load();
+    values["read_ahead_mb"] = double(buffered_bytes.load()) / 1048576.0;
+    values["read_mb"] = double(read_bytes.load()) / 1048576.0;
+    values["read_seconds"] = double(read_us.load()) / 1000000.0;
+    values["decode_ms"] = decoded_frames ? double(decode_us.load()) / decoded_frames.load() / 1000.0 : 0;
+    uint64_t count = converted_frames.load();
+    values["download_ms"] = count ? double(download_us.load()) / count / 1000.0 : 0;
+    values["conversion_ms"] = count ? double(conversion_us.load()) / count / 1000.0 : 0;
+    return values;
+}

native/pc/video_decoder_packets.cpp

@@ -0,0 +1,106 @@
+#include "video_decoder.h"
+extern "C" {
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+#include <libavutil/time.h>
+}
+#include <algorithm>
+
+void VideoDecoder::clear_packets() {
+    for (auto &entry : packets) av_packet_free(&entry.packet);
+    packets.clear();
+    buffered_bytes = buffered_ms = 0;
+    buffered_packets = 0;
+}
+
+void VideoDecoder::update_buffer_size() {
+    buffered_packets = packets.size();
+    int64_t first = AV_NOPTS_VALUE;
+    int64_t last = AV_NOPTS_VALUE;
+    for (const auto &entry : packets) {
+        if (!entry.packet) continue;
+        int64_t timestamp = entry.packet->dts == AV_NOPTS_VALUE ? entry.packet->pts : entry.packet->dts;
+        if (timestamp == AV_NOPTS_VALUE) continue;
+        if (first == AV_NOPTS_VALUE) first = timestamp;
+        last = timestamp;
+    }
+    buffered_ms = first == AV_NOPTS_VALUE ? 0 : std::max<int64_t>(0,
+        av_rescale_q(last - first, input->streams[stream_index]->time_base, AVRational{1, 1000}));
+}
+
+bool VideoDecoder::read_packet(AVPacket *packet, uint64_t &packet_generation, bool &flush, int &error) {
+    std::unique_lock<std::mutex> lock(mutex);
+    wake.wait(lock, [this] { return stopping || !packets.empty(); });
+    if (stopping) return false;
+    auto entry = packets.front();
+    packets.pop_front();
+    packet_generation = entry.generation;
+    flush = entry.flush;
+    error = entry.error;
+    if (entry.packet) {
+        buffered_bytes -= entry.packet->size;
+        av_packet_move_ref(packet, entry.packet);
+        av_packet_free(&entry.packet);
+    }
+    update_buffer_size();
+    wake.notify_all();
+    return true;
+}
+
+void VideoDecoder::read_loop() {
+    int consecutive_errors = 0;
+    while (!stopping) {
+        int64_t target;
+        uint64_t read_generation;
+        {
+            std::unique_lock<std::mutex> lock(mutex);
+            wake.wait(lock, [this] {
+                return stopping || seek_target >= 0 || (!reader_ended &&
+                    packets.size() < max_buffer_packets && buffered_bytes < max_buffer_bytes && buffered_ms < max_buffer_ms);
+            });
+            if (stopping) break;
+            target = seek_target;
+            seek_target = -1;
+            seek_interrupt = false;
+            read_generation = generation;
+        }
+        if (target >= 0) {
+            io_deadline = av_gettime_relative() + 15000000;
+            int error = avformat_seek_file(input, -1, INT64_MIN, origin_us + target * 1000, INT64_MAX, 0);
+            io_deadline = 0;
+            std::lock_guard<std::mutex> lock(mutex);
+            if (generation != read_generation) continue;
+            consecutive_errors = 0;
+            packets.push_back({nullptr, read_generation, true, error});
+            if (error < 0) reader_ended = true;
+            wake.notify_all();
+            if (error < 0) continue;
+        }
+        AVPacket *packet = av_packet_alloc();
+        int64_t started = av_gettime_relative();
+        io_deadline = started + 15000000;
+        int result = packet ? av_read_frame(input, packet) : AVERROR(ENOMEM);
+        io_deadline = 0;
+        read_us += av_gettime_relative() - started;
+        std::lock_guard<std::mutex> lock(mutex);
+        if (generation != read_generation || stopping) { av_packet_free(&packet); continue; }
+        if (result == AVERROR_INVALIDDATA && ++consecutive_errors <= 8) {
+            ++corrupt_packets;
+            av_packet_free(&packet);
+            continue;
+        }
+        if (result < 0) {
+            av_packet_free(&packet);
+            packets.push_back({nullptr, read_generation, false, result});
+            reader_ended = true;
+        } else {
+            consecutive_errors = 0;
+            read_bytes += packet->size;
+            if (packet->stream_index != stream_index) { av_packet_free(&packet); continue; }
+            buffered_bytes += packet->size;
+            packets.push_back({packet, read_generation, false, 0});
+            update_buffer_size();
+        }
+        wake.notify_all();
+    }
+}

native/pc/video_decoder_planes.cpp

@@ -0,0 +1,126 @@
+#include "video_decoder.h"
+extern "C" {
+#include <libavcodec/avcodec.h>
+#include <libavformat/avformat.h>
+#include <libavutil/hwcontext.h>
+#include <libavutil/mastering_display_metadata.h>
+#include <libswscale/swscale.h>
+}
+#include <algorithm>
+#include <cstring>
+
+static bool native_format(int format) {
+    return format == AV_PIX_FMT_NV12 || format == AV_PIX_FMT_P010LE || format == AV_PIX_FMT_YUV420P ||
+        format == AV_PIX_FMT_YUVJ420P || format == AV_PIX_FMT_YUV420P10LE;
+}
+
+static bool supported_size(int width, int height) {
+    return width > 0 && height > 0 && width <= 8192 && height <= 8192 && int64_t(width) * height <= 33554432;
+}
+
+bool VideoDecoder::prepare_planes(AVFrame *frame, VideoPlanes &output, int storage_width, int storage_height) {
+    output.width = frame->width;
+    output.height = frame->height;
+    output.storage_width = storage_width;
+    output.storage_height = storage_height;
+    output.rotation = rotation;
+    AVRational aspect = av_guess_sample_aspect_ratio(input, input->streams[stream_index], frame);
+    output.display_width = aspect.num > 0 && aspect.den > 0 ? int(av_rescale(frame->width, aspect.num, aspect.den)) : frame->width;
+    output.display_height = frame->height;
+    if (rotation % 2) std::swap(output.display_width, output.display_height);
+    if (!supported_size(output.width, output.height) || !supported_size(storage_width, storage_height) ||
+            !supported_size(output.display_width, output.display_height)) return false;
+    output.interleaved = frame->format == AV_PIX_FMT_NV12 || frame->format == AV_PIX_FMT_P010LE;
+    output.sample_bytes = frame->format == AV_PIX_FMT_NV12 || frame->format == AV_PIX_FMT_YUV420P || frame->format == AV_PIX_FMT_YUVJ420P ? 1 : 2;
+    output.plane_count = output.interleaved ? 2 : 3;
+    output.sample_scale = output.sample_bytes == 1 ? 1020.f : frame->format == AV_PIX_FMT_P010LE ? 65535.f / 64.f : 65535.f;
+    output.code_max = output.sample_bytes == 1 ? 1020.f : 1023.f;
+    for (int index = 0; index < 3; ++index) {
+        int width = index ? (storage_width + 1) / 2 : storage_width;
+        int height = index ? (storage_height + 1) / 2 : storage_height;
+        int64_t bytes = int64_t(width) * height * output.sample_bytes * (index && output.interleaved ? 2 : 1);
+        if (output.planes[index].resize(index < output.plane_count ? bytes : 0) != 0) return false;
+    }
+    auto range = frame->color_range != AVCOL_RANGE_UNSPECIFIED ? frame->color_range : codec->color_range;
+    auto colorspace = frame->colorspace != AVCOL_SPC_UNSPECIFIED ? frame->colorspace : codec->colorspace;
+    auto transfer = frame->color_trc != AVCOL_TRC_UNSPECIFIED ? frame->color_trc : codec->color_trc;
+    output.full_range = range == AVCOL_RANGE_JPEG ? 1.f : 0.f;
+    output.kr = .2126f;
+    output.kb = .0722f;
+    if (colorspace == AVCOL_SPC_BT2020_NCL) { output.kr = .2627f; output.kb = .0593f; }
+    else if (colorspace == AVCOL_SPC_BT470BG || colorspace == AVCOL_SPC_SMPTE170M ||
+            (colorspace == AVCOL_SPC_UNSPECIFIED && frame->height < 720)) { output.kr = .299f; output.kb = .114f; }
+    output.transfer = transfer == AVCOL_TRC_SMPTE2084 ? 1.f : transfer == AVCOL_TRC_ARIB_STD_B67 ? 2.f : 0.f;
+    active_transfer = int(output.transfer);
+    float peak_nits = 1000;
+    auto *mastering = av_frame_get_side_data(frame, AV_FRAME_DATA_MASTERING_DISPLAY_METADATA);
+    if (mastering && mastering->size >= sizeof(AVMasteringDisplayMetadata)) {
+        auto *metadata = reinterpret_cast<AVMasteringDisplayMetadata *>(mastering->data);
+        if (metadata->has_luminance) peak_nits = float(av_q2d(metadata->max_luminance));
+    }
+    auto *light = av_frame_get_side_data(frame, AV_FRAME_DATA_CONTENT_LIGHT_LEVEL);
+    if (light && light->size >= sizeof(AVContentLightMetadata)) {
+        auto *metadata = reinterpret_cast<AVContentLightMetadata *>(light->data);
+        if (metadata->MaxCLL) peak_nits = float(metadata->MaxCLL);
+    }
+    output.source_peak = std::clamp(peak_nits, 203.f, 10000.f) / 203.f;
+    return true;
+}
+
+// VideoPlane owns the allocation until the transfer completes.
+static void retain_plane_storage(void *, uint8_t *) {}
+
+bool VideoDecoder::download_planes(AVFrame *frame, VideoPlanes &output) {
+    auto *context = reinterpret_cast<AVHWFramesContext *>(frame->hw_frames_ctx->data);
+    if (!native_format(context->sw_format)) return false;
+    AVFrame description = *frame;
+    description.format = context->sw_format;
+    if (!prepare_planes(&description, output, context->width, context->height)) return false;
+    AVFrame *target = av_frame_alloc();
+    if (!target) return false;
+    target->format = context->sw_format;
+    target->width = context->width;
+    target->height = context->height;
+    bool ready = true;
+    bool pinned = context->format == AV_PIX_FMT_CUDA;
+    for (int index = 0; index < output.plane_count; ++index) {
+        if (context->format == AV_PIX_FMT_CUDA) pinned = output.planes[index].pin(context->device_ref) && pinned;
+        int width = index ? (context->width + 1) / 2 : context->width;
+        target->data[index] = output.planes[index].ptrw();
+        target->linesize[index] = width * output.sample_bytes * (index && output.interleaved ? 2 : 1);
+        target->buf[index] = av_buffer_create(target->data[index], output.planes[index].size(), retain_plane_storage, nullptr, 0);
+        ready = ready && target->buf[index];
+    }
+    pinned_download = pinned;
+    int result = ready ? av_hwframe_transfer_data(target, frame, 0) : AVERROR(ENOMEM);
+    av_frame_free(&target);
+    return result >= 0;
+}
+
+bool VideoDecoder::convert(AVFrame *frame, VideoPlanes &output) {
+    bool native = native_format(frame->format);
+    AVFrame description = *frame;
+    if (!native) description.format = AV_PIX_FMT_YUV420P10LE;
+    if (!prepare_planes(&description, output, frame->width, frame->height)) return false;
+    uint8_t *data[4] = {};
+    int strides[4] = {};
+    for (int index = 0; index < output.plane_count; ++index) {
+        int width = index ? (frame->width + 1) / 2 : frame->width;
+        int height = index ? (frame->height + 1) / 2 : frame->height;
+        strides[index] = width * output.sample_bytes * (index && output.interleaved ? 2 : 1);
+        data[index] = output.planes[index].ptrw();
+        if (native) {
+            for (int row = 0; row < height; ++row) {
+                std::memcpy(data[index] + row * strides[index], frame->data[index] + row * frame->linesize[index], strides[index]);
+            }
+        }
+    }
+    if (native) return true;
+    scaler = sws_getCachedContext(scaler, frame->width, frame->height, AVPixelFormat(frame->format),
+        frame->width, frame->height, AV_PIX_FMT_YUV420P10LE, SWS_POINT, nullptr, nullptr, nullptr);
+    if (!scaler) return false;
+    int range = int(output.full_range);
+    const int *coefficients = sws_getCoefficients(SWS_CS_DEFAULT);
+    if (sws_setColorspaceDetails(scaler, coefficients, range, coefficients, range, 0, 1 << 16, 1 << 16) < 0) return false;
+    return sws_scale(scaler, frame->data, frame->linesize, 0, frame->height, data, strides) == frame->height;
+}

native/pc/video_plane.cpp

@@ -0,0 +1,107 @@
+#include "video_plane.h"
+extern "C" {
+#include <libavutil/buffer.h>
+#include <libavutil/hwcontext.h>
+}
+#include <cstring>
+#ifdef _WIN32
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#define CUDA_CALL __stdcall
+#else
+#include <dlfcn.h>
+#define CUDA_CALL
+#endif
+
+struct CudaApi {
+    int (CUDA_CALL *push)(void *) = nullptr;
+    int (CUDA_CALL *pop)(void **) = nullptr;
+    int (CUDA_CALL *host_register)(void *, size_t, unsigned) = nullptr;
+    int (CUDA_CALL *host_unregister)(void *) = nullptr;
+
+    CudaApi() {
+#ifdef _WIN32
+        HMODULE library = LoadLibraryExW(L"nvcuda.dll", nullptr, LOAD_LIBRARY_SEARCH_SYSTEM32);
+        auto symbol = [library](const char *name) -> void * { return library ? reinterpret_cast<void *>(GetProcAddress(library, name)) : nullptr; };
+#else
+        void *library = dlopen("libcuda.so.1", RTLD_NOW | RTLD_LOCAL);
+        auto symbol = [library](const char *name) -> void * { return library ? dlsym(library, name) : nullptr; };
+#endif
+        push = reinterpret_cast<decltype(push)>(symbol("cuCtxPushCurrent_v2"));
+        pop = reinterpret_cast<decltype(pop)>(symbol("cuCtxPopCurrent_v2"));
+        host_register = reinterpret_cast<decltype(host_register)>(symbol("cuMemHostRegister_v2"));
+        host_unregister = reinterpret_cast<decltype(host_unregister)>(symbol("cuMemHostUnregister"));
+    }
+};
+
+static const CudaApi &cuda_api() {
+    static const CudaApi api;
+    return api;
+}
+
+
+class CudaHostPin {
+public:
+    CudaHostPin(AVBufferRef *owner, void *address, size_t size) : address(address) {
+        auto *device = reinterpret_cast<AVHWDeviceContext *>(owner->data);
+        if (device->type != AV_HWDEVICE_TYPE_CUDA) return;
+        const auto &api = cuda_api();
+        if (!api.push || !api.pop || !api.host_register || !api.host_unregister) return;
+        // CUcontext is the first member of FFmpeg's public AVCUDADeviceContext.
+        std::memcpy(&context, device->hwctx, sizeof(context));
+        reference = av_buffer_ref(owner);
+        if (!reference || api.push(context) != 0) return;
+        registered = api.host_register(address, size, 1) == 0;
+        void *previous = nullptr;
+        api.pop(&previous);
+    }
+
+    ~CudaHostPin() {
+        const auto &api = cuda_api();
+        if (registered && api.push(context) == 0) {
+            api.host_unregister(address);
+            void *previous = nullptr;
+            api.pop(&previous);
+        }
+        av_buffer_unref(&reference);
+    }
+
+    bool valid() const { return registered; }
+    void *get_address() const { return address; }
+private:
+    AVBufferRef *reference = nullptr;
+    void *context = nullptr;
+    void *address = nullptr;
+    bool registered = false;
+};
+
+VideoPlane::VideoPlane() = default;
+VideoPlane::~VideoPlane() = default;
+VideoPlane::VideoPlane(VideoPlane &&other) noexcept = default;
+
+VideoPlane &VideoPlane::operator=(VideoPlane &&other) noexcept {
+    if (this == &other) return *this;
+    registration.reset();
+    bytes = std::move(other.bytes);
+    registration = std::move(other.registration);
+    return *this;
+}
+
+godot::Error VideoPlane::resize(int64_t size) {
+    if (bytes.size() == size) return godot::OK;
+    registration.reset();
+    return godot::Error(bytes.resize(size));
+}
+
+bool VideoPlane::pin(AVBufferRef *device) {
+    uint8_t *address = ptrw();
+    if (registration) return registration->valid();
+    registration = std::make_unique<CudaHostPin>(device, address, bytes.size());
+    return registration->valid();
+}
+
+uint8_t *VideoPlane::ptrw() {
+    uint8_t *address = bytes.ptrw();
+    if (registration && registration->get_address() != address) registration.reset();
+    return address;
+}

native/pc/video_plane.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <godot_cpp/variant/packed_byte_array.hpp>
+#include <memory>
+
+struct AVBufferRef;
+class CudaHostPin;
+
+class VideoPlane {
+public:
+    VideoPlane();
+    ~VideoPlane();
+    VideoPlane(VideoPlane &&other) noexcept;
+    VideoPlane &operator=(VideoPlane &&other) noexcept;
+    godot::Error resize(int64_t size);
+    int64_t size() const { return bytes.size(); }
+    uint8_t *ptrw();
+    const godot::PackedByteArray &data() const { return bytes; }
+    bool pin(AVBufferRef *device);
+private:
+    godot::PackedByteArray bytes;
+    std::unique_ptr<CudaHostPin> registration;
+};

native/pc/video_sync.cpp

@@ -0,0 +1,18 @@
+#include "mpv_video.h"
+
+void JellyframeMpv::apply_audio_pause() {
+    int flag = paused || video_buffering;
+    mpv_set_property_async(player, 0, "pause", MPV_FORMAT_FLAG, &flag);
+}
+
+void JellyframeMpv::update_video_buffering() {
+    if (vulkan_renderer.is_null() || uses_video_clock() || !prepared || seeking) return;
+    int64_t timestamp = vulkan_renderer->timestamp_ms();
+    bool waiting = video_buffering;
+    if (timestamp < 0 || position - timestamp > 250) waiting = true;
+    else if (position - timestamp <= 80 && vulkan_renderer->read_ahead_ready()) waiting = false;
+    if (waiting == video_buffering) return;
+    video_buffering = waiting;
+    if (waiting) ++video_buffer_count;
+    apply_audio_pause();
+}

project.godot

@@ -16,6 +16,7 @@ compatibility/default_parent_skeleton_in_mesh_instance_3d=true
 
 config/name="Jellyframe"
 config/description="A Jellyfin cinema for standalone VR."
+config/version="0.1.2"
 run/main_scene="res://scenes/main.tscn"
 config/use_custom_user_dir=true
 config/features=PackedStringArray("4.7", "GL Compatibility")
@@ -35,13 +36,22 @@ enabled=PackedStringArray("res://addons/jellyframe_video/plugin.cfg")
 renderer/rendering_method="gl_compatibility"
 renderer/rendering_method.mobile="gl_compatibility"
 textures/vram_compression/import_etc2_astc=true
-environment/defaults/default_clear_color=Color(0.018, 0.029, 0.046, 1)
-renderer/rendering_method.linux_opengl="gl_compatibility"
-renderer/rendering_method.linux_vulkan="mobile"
-rendering_device/driver.linux_vulkan="vulkan"
+environment/defaults/default_clear_color=Color(0, 0, 0, 1)
+renderer/rendering_method.windows="mobile"
+renderer/rendering_method.linux="mobile"
+rendering_device/fallback_to_d3d12.windows=false
+rendering_device/fallback_to_opengl3.windows=true
+rendering_device/fallback_to_opengl3.linux=true
+rendering_device/staging_buffer/block_size_kb.windows=4096
+rendering_device/staging_buffer/block_size_kb.linux=4096
+rendering_device/staging_buffer/max_size_mb.windows=512
+rendering_device/staging_buffer/max_size_mb.linux=512
+rendering_device/staging_buffer/texture_upload_region_size_px.windows=512
+rendering_device/staging_buffer/texture_upload_region_size_px.linux=512
 
 [xr]
 
 openxr/enabled=true
+openxr/extensions/render_model=true
 shaders/enabled=true
 openxr/extensions/meta/passthrough=true

scripts/core/photo_sequence.gd

@@ -0,0 +1,45 @@
+class_name PhotoSequence
+extends RefCounted
+
+var items: Array = []
+var index := -1
+var offset := 0
+var has_more := false
+var search := ""
+var library_id := ""
+var busy := false
+
+func capture(library: LibraryView, selected: Dictionary) -> void:
+	items.clear()
+	if library.grid:
+		for card in library.grid.get_children():
+			if card.item.get("Type", "") == "Photo": items.append(card.item)
+	index = items.find(selected)
+	if index < 0:
+		items = [selected]
+		index = 0
+	offset = library.offset
+	has_more = library.has_more
+	search = library.search
+	library_id = library.library_id
+
+func can_next() -> bool:
+	return index + 1 < items.size() or has_more
+
+func step(direction: int, api: JellyfinClient) -> Dictionary:
+	if busy or index + direction < 0: return {}
+	busy = true
+	while direction > 0 and index + 1 >= items.size() and has_more:
+		var result := await api.library(search, offset, library_id)
+		if not result.ok:
+			busy = false
+			return {"error": result.error}
+		var page: Array = result.data.get("Items", [])
+		offset += page.size()
+		has_more = not page.is_empty() and offset < int(result.data.get("TotalRecordCount", offset))
+		for item in page:
+			if item.get("Type", "") == "Photo": items.append(item)
+	busy = false
+	if index + direction >= items.size(): return {}
+	index += direction
+	return {"item": items[index]}

scripts/core/photo_sequence.gd.uid

@@ -0,0 +1 @@
+uid://gscxynvjkrml

scripts/core/settings.gd

@@ -4,6 +4,11 @@ extends RefCounted
 const PATH := "user://settings.cfg"
 const SCREEN_KEYS := ["width", "distance", "height", "curvature"]
 const PLAYBACK_MODES := ["auto", "original", "transcoded"]
+const TRANSCODE_PRESETS := {
+	720: {"label": "720p", "width": 1280, "height": 720, "bitrate": 6000000},
+	1080: {"label": "1080p", "width": 1920, "height": 1080, "bitrate": 12000000},
+	2160: {"label": "4K", "width": 3840, "height": 2160, "bitrate": 40000000}
+}
 const LIBRARY_SORT_OPTIONS := [
 	["Name", "SortName"], ["Random", "Random"],
 	["Community rating", "CommunityRating"], ["Critics rating", "CriticRating"],
@@ -16,11 +21,13 @@ var distance := 3.0
 var height := 0.0
 var curvature := 0.0
 var environment := "Void"
+var follow_screen := false
 var server := ""
 var device_id := ""
 var library_sort_by := "SortName"
 var library_sort_order := "Ascending"
 var playback_mode := "auto"
+var transcode_resolution := 1080
 
 func load_settings(path: String = PATH) -> void:
 	var config := ConfigFile.new()
@@ -29,6 +36,7 @@ func load_settings(path: String = PATH) -> void:
 	distance = clampf(config.get_value("screen", "distance", distance), 1.5, 8.0)
 	height = clampf(config.get_value("screen", "height", height), -2.0, 2.0)
 	curvature = clampf(config.get_value("screen", "curvature", curvature), 0.0, 1.2)
+	follow_screen = config.get_value("screen", "follow_screen", false) == true
 	environment = config.get_value("screen", "environment", "Void")
 	if int(config.get_value("screen", "environment_version", 1)) < 2:
 		if environment == "Theatre": environment = "Cinema"
@@ -44,6 +52,8 @@ func load_settings(path: String = PATH) -> void:
 		library_sort_order = "Ascending"
 	playback_mode = str(config.get_value("playback", "mode", "auto"))
 	if playback_mode not in PLAYBACK_MODES: playback_mode = "auto"
+	transcode_resolution = int(config.get_value("playback", "transcode_resolution", 1080))
+	if not TRANSCODE_PRESETS.has(transcode_resolution): transcode_resolution = 1080
 	if device_id.is_empty():
 		device_id = Crypto.new().generate_random_bytes(16).hex_encode()
 		save(path)
@@ -61,11 +71,13 @@ func save(path: String = PATH) -> Error:
 	for key in SCREEN_KEYS:
 		config.set_value("screen", key, get(key))
 	config.set_value("screen", "environment", environment)
+	config.set_value("screen", "follow_screen", follow_screen)
 	config.set_value("screen", "environment_version", 2)
 	config.set_value("connection", "server", server)
 	config.set_value("connection", "device_id", device_id)
 	config.set_value("library", "sort_by", library_sort_by)
 	config.set_value("library", "sort_order", library_sort_order)
 	config.set_value("playback", "mode", playback_mode)
+	config.set_value("playback", "transcode_resolution", transcode_resolution)
 	return config.save(path)
 

scripts/jellyfin/client.gd

@@ -12,7 +12,7 @@ var random_library_generation: Dictionary = {}
 
 func authorization() -> String:
 	var name := headset_name().replace("\\", "\\\\").replace('"', '\\"').replace("\r", " ").replace("\n", " ")
-	var value := 'MediaBrowser Client="Jellyframe", Device="%s", DeviceId="%s", Version="0.1.0"' % [name, device_id]
+	var value := 'MediaBrowser Client="Jellyframe", Device="%s", DeviceId="%s", Version="0.1.2"' % [name, device_id]
 	if not token.is_empty():
 		value += ', Token="%s"' % token
 	return value
@@ -84,7 +84,7 @@ func query(values: Dictionary) -> String:
 	return "?" + "&".join(pairs)
 
 func library(search: String = "", offset: int = 0, parent_id: String = "") -> Dictionary:
-	var values := {"UserId": user_id, "Recursive": "true", "IncludeItemTypes": "Movie,Series,Video", "Fields": "Overview,UserData", "Limit": 25, "StartIndex": offset, "SortBy": library_sort_by, "SortOrder": library_sort_order}
+	var values := {"UserId": user_id, "Recursive": "true", "IncludeItemTypes": "Movie,Series,Video,Photo", "Fields": "Overview,UserData", "Limit": 25, "StartIndex": offset, "SortBy": library_sort_by, "SortOrder": library_sort_order}
 	if search.is_empty() and parent_id.is_empty():
 		values["SortBy"] = "DateCreated"
 		values["SortOrder"] = "Descending"

scripts/jellyfin/media_segments.gd

@@ -0,0 +1,43 @@
+class_name MediaSegments
+extends RefCounted
+
+const LABELS := {"Intro": "Skip intro", "Outro": "Skip credits", "Recap": "Skip recap", "Preview": "Skip preview"}
+
+var segments: Array[Dictionary] = []
+var generation := 0
+
+func clear() -> void:
+	generation += 1
+	segments.clear()
+
+func load_item(api: JellyfinClient, item_id: String) -> void:
+	clear()
+	var current := generation
+	var result := await api.request("/MediaSegments/" + item_id.uri_encode())
+	if current != generation or not result.get("ok", false): return
+	segments = parse(result.get("data"))
+
+static func parse(data: Variant) -> Array[Dictionary]:
+	var parsed: Array[Dictionary] = []
+	if not data is Dictionary or not data.get("Items") is Array: return parsed
+	for item in data.Items:
+		if not item is Dictionary or not LABELS.has(item.get("Type")): continue
+		var start: Variant = item.get("StartTicks")
+		var end: Variant = item.get("EndTicks")
+		if not (start is int or start is float) or not (end is int or end is float): continue
+		if not is_finite(float(start)) or not is_finite(float(end)): continue
+		if start < 0 or end <= start or end >= 9223372036854775807: continue
+		var start_ms := int(start / 10000)
+		var end_ms := int(end / 10000)
+		if end_ms <= start_ms: continue
+		parsed.append({"start_ms": start_ms, "end_ms": end_ms, "label": LABELS[item.Type]})
+	parsed.sort_custom(func(a: Dictionary, b: Dictionary): return a.start_ms < b.start_ms)
+	return parsed
+
+func active(position_ms: int, duration_ms: int) -> Dictionary:
+	if duration_ms <= 0: return {}
+	for segment in segments:
+		var target := mini(int(segment.end_ms), maxi(0, duration_ms - 1000))
+		if position_ms >= segment.start_ms and position_ms < target:
+			return {"label": segment.label, "target_ms": target}
+	return {}

scripts/jellyfin/media_segments.gd.uid

@@ -0,0 +1 @@
+uid://cwoeoeho3i2tr

scripts/jellyfin/playback.gd

@@ -7,6 +7,7 @@ signal stream_ready(url: String, source: Dictionary, start_ms: int)
 var api: JellyfinClient
 var settings: JellyframeSettings
 var active_playback_mode := "auto"
+var active_transcode_resolution := 1080
 var item: Dictionary = {}
 var source: Dictionary = {}
 var session_id := ""
@@ -14,7 +15,6 @@ var method := "DirectPlay"
 var position_ticks := 0
 var started := false
 var fallback_attempted := false
-var diagnostics_pending := false
 
 func open(selected: Dictionary, transcode: bool = false) -> void:
 	item = selected
@@ -22,12 +22,11 @@ func open(selected: Dictionary, transcode: bool = false) -> void:
 		position_ticks = int(item.get("UserData", {}).get("PlaybackPositionTicks", 0))
 		fallback_attempted = false
 		active_playback_mode = settings.playback_mode if settings != null else "auto"
+		active_transcode_resolution = settings.transcode_resolution if settings != null and active_playback_mode == "transcoded" else 1080
 	started = false
 	var use_transcode := transcode or active_playback_mode == "transcoded"
 	var original := active_playback_mode == "original"
 	var profile := _device_profile(use_transcode, original)
-	if not use_transcode:
-		print("Jellyframe playback: direct codecs=", profile.DirectPlayProfiles[0].get("VideoCodec", "original formats"))
 	var result := await api.request("/Items/%s/PlaybackInfo" % str(item.Id).uri_encode(), HTTPClient.METHOD_POST, {
 		"UserId": api.user_id, "StartTimeTicks": position_ticks, "IsPlayback": true,
 		"AutoOpenLiveStream": true, "EnableDirectPlay": not use_transcode, "EnableDirectStream": false,
@@ -61,11 +60,6 @@ func open(selected: Dictionary, transcode: bool = false) -> void:
 			failed.emit("The server returned an unsupported stream address.")
 			return
 		if not is_hls(): start_ms = 0
-	print("Jellyframe playback: method=", method, ", bitrate=", source.get("Bitrate", 0), ", transcode reasons=", source.get("TranscodeReasons", []))
-	for track in source.get("MediaStreams", []):
-		if track.get("Type", "") == "Video":
-			print("Jellyframe playback: codec=", track.get("Codec", "unknown"), ", size=", track.get("Width", 0), "x", track.get("Height", 0), ", range=", track.get("VideoRangeType", "unknown"), ", fps=", track.get("AverageFrameRate", 0))
-			break
 	stream_ready.emit(url, source, start_ms)
 
 func is_hls() -> bool:
@@ -81,8 +75,9 @@ func _device_profile(transcode: bool, original: bool = false) -> Dictionary:
 		direct_profile["AudioCodec"] = "aac,mp3,opus,vorbis"
 	var transcoding_profile := {"Container": "ts", "Type": "Video", "VideoCodec": "h264", "AudioCodec": "aac", "Protocol": "hls", "Context": "Streaming", "MaxAudioChannels": "2", "MinSegments": 2, "BreakOnNonKeyFrames": true}
 	var codec_conditions := [{"Condition": "Equals", "Property": "VideoRangeType", "Value": "SDR", "IsRequired": true}]
+	var preset: Dictionary = JellyframeSettings.TRANSCODE_PRESETS.get(active_transcode_resolution, JellyframeSettings.TRANSCODE_PRESETS[1080])
 	transcoding_profile["Conditions"] = []
-	for limit in [["Width", "1920"], ["Height", "1080"], ["VideoFramerate", "30"], ["VideoBitrate", "12000000"]]:
+	for limit in [["Width", str(preset.width)], ["Height", str(preset.height)], ["VideoFramerate", "30"], ["VideoBitrate", str(preset.bitrate)]]:
 		transcoding_profile.Conditions.append({"Condition": "LessThanEqual", "Property": limit[0], "Value": limit[1], "IsRequired": true})
 	if transcode: codec_conditions.append_array(transcoding_profile.Conditions)
 	return {
@@ -111,24 +106,7 @@ func report(event: String, paused: bool = false) -> void:
 	if not started: return
 	var path := "/Sessions/Playing" + ("/" + event if event != "Playing" else "")
 	await api.request(path, HTTPClient.METHOD_POST, {"ItemId": item.Id, "MediaSourceId": source.Id, "PlaySessionId": session_id, "PositionTicks": position_ticks, "IsPaused": paused, "CanSeek": true, "PlayMethod": method})
-	if event == "Progress" and method == "Transcode" and OS.is_debug_build() and not diagnostics_pending:
-		_log_transcoding()
 	if event == "Stopped":
 		started = false
 		if method == "Transcode":
 			await api.request("/Videos/ActiveEncodings" + api.query({"DeviceId": api.device_id, "PlaySessionId": session_id}), HTTPClient.METHOD_DELETE)
-
-func _log_transcoding() -> void:
-	diagnostics_pending = true
-	var result := await api.request("/Sessions" + api.query({"DeviceId": api.device_id}))
-	diagnostics_pending = false
-	if not result.ok or not result.data is Array: return
-	for active in result.data:
-		if not active is Dictionary: continue
-		if str(active.get("DeviceId", "")) != api.device_id: continue
-		var playing_item: Variant = active.get("NowPlayingItem")
-		if not playing_item is Dictionary: continue
-		if str(playing_item.get("Id", "")) != str(item.get("Id", "")): continue
-		var info: Variant = active.get("TranscodingInfo")
-		if not info is Dictionary: continue
-		print("Jellyframe transcoding: fps=", info.get("Framerate"), ", bitrate=", info.get("Bitrate"), ", size=", info.get("Width"), "x", info.get("Height"), ", hardware=", info.get("HardwareAccelerationType"), ", video copy=", info.get("IsVideoDirect"), ", reasons=", info.get("TranscodeReasons"))

scripts/main.gd

@@ -14,6 +14,9 @@ var libraries_loaded := false
 var library_generation := 0
 var page_generation := 0
 var page: VBoxContainer
+var settings_return_page: Control
+var settings_return_heading := ""
+var settings_return_status := ""
 var status: Label
 var keyboard: VRKeyboard
 var material: ShaderMaterial
@@ -31,11 +34,17 @@ var transcode_offset := 0
 var quick_generation := 0
 var countdown_generation := 0
 var autoplay_pending := false
-var calibration := false
 var seeking := false
 var seek_paused := false
 var timeline_elapsed := 0.0
 var decoder_ready := false
+var media_segments := MediaSegments.new()
+var photo_active := false
+var photo_loading := false
+var photo_item: Dictionary = {}
+var video_material: ShaderMaterial
+var photo_loader: PhotoView
+var photo_sequence := PhotoSequence.new()
 
 func _ready() -> void:
 	settings.load_settings()
@@ -56,9 +65,6 @@ func _ready() -> void:
 	video.size_changed.connect(func(w: int, h: int): video_size = Vector2i(w, h); _resize_screen())
 	_show_login()
 	await _restore_session()
-	if video.has_android_services() and OS.is_debug_build() and video.bridge.calibration_requested():
-		await get_tree().create_timer(2).timeout
-		_calibrate()
 
 func _setup_world() -> void:
 	world = ViewingWorld.new()
@@ -73,10 +79,13 @@ func _setup_world() -> void:
 	player_overlay.action.connect(_player_action)
 	player_overlay.seek_requested.connect(_seek_to)
 	world.player_loading.cancelled.connect(_show_library)
+	world.player_skip_popup.skip_requested.connect(_skip_segment)
 	material = world.material
 	theatre = world.theatre
 	video.material = material
 	world.menu_requested.connect(_toggle_menu)
+	world.settings_requested.connect(_toggle_settings)
+	world.library_requested.connect(_toggle_controller_library)
 	var xr := XRServer.find_interface("OpenXR") as OpenXRInterface
 	if xr:
 		xr.pose_recentered.connect(_recenter, CONNECT_DEFERRED)
@@ -93,12 +102,17 @@ func _setup_ui() -> void:
 	status = shell.status
 	shell.navigate.connect(_open_library)
 	shell.screen_settings.connect(_screen_settings)
+	shell.return_from_settings.connect(_return_from_settings)
 	shell.sign_out.connect(_sign_out)
 	keyboard = VRKeyboard.new()
 	viewport.add_child(keyboard)
 	keyboard.hide()
 
-func _clear_page() -> void:
+func _clear_page(keep_settings_return: bool = false) -> void:
+	if not keep_settings_return and is_instance_valid(settings_return_page):
+		settings_return_page.queue_free()
+		settings_return_page = null
+	shell.set_settings_mode(false)
 	page_generation += 1
 	countdown_generation += 1
 	_cancel_countdown()
@@ -141,8 +155,6 @@ func _show_login() -> void:
 		else: status.text = result.error)
 	Widgets.button("Quick Connect", func():
 		if _configure(address.text): _quick_connect(), row)
-	if video.has_android_services() and OS.is_debug_build():
-		Widgets.button("Test 3D playback", _calibrate, row)
 	Widgets.label("HTTP sends credentials without encryption. Use HTTPS outside your home network.", page, 18)
 	status.text = "Sign in to start watching."
 
@@ -236,6 +248,22 @@ func _show_library() -> void:
 	if shell.buttons.has(shell.selected_id): title = shell.buttons[shell.selected_id].text
 	_open_library(shell.selected_id, title)
 
+func _toggle_controller_library() -> void:
+	if api.token.is_empty(): return
+	if autoplay_pending:
+		_show_library()
+		return
+	for child in page.get_children():
+		if child is SettingsView:
+			_return_from_settings()
+			return
+	_toggle_panel()
+
+func _toggle_panel() -> void:
+	panel.visible = not panel.visible
+	player_overlay.hide()
+	keyboard.hide()
+
 func _open_library(id: String, title: String) -> void:
 	_clear_page()
 	shell.set_signed_in(true)
@@ -247,7 +275,11 @@ func _open_library(id: String, title: String) -> void:
 	api.library_sort_by = settings.library_sort_by
 	api.library_sort_order = settings.library_sort_order
 	library.size_flags_vertical = Control.SIZE_EXPAND_FILL
-	library.status.connect(func(message: String): status.text = message)
+	library.status.connect(func(message: String):
+		if library == settings_return_page:
+			settings_return_status = message
+		else:
+			status.text = message)
 	library.selected.connect(_details)
 	page.add_child(library)
 	library.field.focus_entered.connect(func(): keyboard.edit.call_deferred(library.field))
@@ -269,6 +301,12 @@ func _load_libraries() -> void:
 		Widgets.button("Retry libraries", _load_libraries, shell.libraries).add_theme_font_size_override("font_size", 17)
 
 func _details(item: Dictionary, season: Dictionary = {}) -> void:
+	if item.get("Type", "") == "Photo":
+		photo_sequence = PhotoSequence.new()
+		for child in page.get_children():
+			if child is LibraryView: photo_sequence.capture(child, item)
+		_show_photo(item)
+		return
 	page_generation += 1
 	var current := page_generation
 	status.text = "Loading details..."
@@ -285,12 +323,94 @@ func _details(item: Dictionary, season: Dictionary = {}) -> void:
 	view.initial_season = season
 	view.size_flags_vertical = Control.SIZE_EXPAND_FILL
 	view.play_requested.connect(_start)
+	view.play_from_start_requested.connect(_start.bind(true))
 	view.back_requested.connect(_show_library)
 	page.add_child(view)
 	status.text = "Ready."
 
-func _start(item: Dictionary) -> void:
-	if playing and str(session.item.get("Id", "")) == str(item.get("Id", "")):
+func _show_photo(item: Dictionary) -> void:
+	page_generation += 1
+	var current := page_generation
+	await _stop(false)
+	if current != page_generation: return
+	photo_active = true
+	photo_item = item
+	video_material = material
+	material = ShaderMaterial.new()
+	material.shader = preload("res://shaders/pc_video.gdshader")
+	screen.material_override = material
+	world.panorama.material_override = material
+	mode = PhotoView.stereo_mode(item)
+	projection_mode = VideoProjection.detect({"Path": item.get("Path", item.get("Name", ""))})
+	stereo_overridden = false
+	projection_overridden = false
+	photo_loader = PhotoView.new()
+	photo_loader.api = api
+	photo_loader.item = item
+	photo_loader.photo_ready.connect(_photo_ready)
+	photo_loader.failed.connect(_photo_failed)
+	status.text = "Loading photo..."
+	photo_loading = true
+	keyboard.hide()
+	panel.hide()
+	screen.show()
+	_resize_screen()
+	_update_loading()
+	add_child(photo_loader)
+	photo_loader._load()
+
+func _photo_ready(texture: Texture2D) -> void:
+	if not photo_active: return
+	photo_loading = false
+	_update_loading()
+	material.set_shader_parameter("video_texture", texture)
+	video_size = Vector2i(texture.get_size())
+	screen.show()
+	world.set_panoramic(projection_mode != VideoProjection.Mode.SCREEN, VideoProjection.horizontal_angle(projection_mode))
+	_resize_screen()
+	status.text = ""
+	_show_playback()
+
+func _photo_failed(message: String) -> void:
+	_close_photo()
+	status.text = message + " Select the photo to try again."
+	panel.show()
+
+func _step_photo(direction: int) -> void:
+	if not photo_active or photo_sequence.busy: return
+	var current := page_generation
+	player_overlay.set_photo_navigation(false, false)
+	photo_loading = true
+	_update_loading()
+	var result := await photo_sequence.step(direction, api)
+	if current != page_generation or not photo_active: return
+	if result.has("item"):
+		await _show_photo(result.item)
+	else:
+		photo_loading = false
+		_update_loading()
+		player_overlay.set_photo_navigation(photo_sequence.index > 0, photo_sequence.can_next())
+		if result.has("error"): player_overlay.tooltip.text = result.error
+
+func _close_photo() -> void:
+	if not photo_active: return
+	photo_active = false
+	photo_loading = false
+	world.player_loading.hide()
+	photo_item = {}
+	if is_instance_valid(photo_loader):
+		remove_child(photo_loader)
+		photo_loader.queue_free()
+		photo_loader = null
+	material = video_material
+	screen.material_override = material
+	world.panorama.material_override = material
+	video_material = null
+	world.set_panoramic(false)
+	player_overlay.set_photo_mode(false)
+
+func _start(item: Dictionary, from_start: bool = false) -> void:
+	if not from_start and playing and str(session.item.get("Id", "")) == str(item.get("Id", "")):
 		if video.paused:
 			video.toggle_pause()
 			session.report("Progress", false)
@@ -300,20 +420,26 @@ func _start(item: Dictionary) -> void:
 		status.text = video.unavailable_message()
 		return
 	await _stop(false)
-	calibration = false
 	projection_overridden = false
 	stereo_overridden = false
 	projection_mode = VideoProjection.Mode.SCREEN
 	world.set_panoramic(false)
-	_recenter()
+	_resize_screen()
 	status.text = "Preparing playback..."
 	playing = true
 	screen.show()
 	_show_playback()
 	player_overlay.title.text = DetailsMetadata.title(item, "Now playing")
-	await session.open(item)
+	media_segments.load_item(api, str(item.Id))
+	var selected := item
+	if from_start:
+		selected = item.duplicate(true)
+		if not selected.get("UserData") is Dictionary: selected.UserData = {}
+		selected.UserData.PlaybackPositionTicks = 0
+	await session.open(selected)
 
 func _play_stream(url: String, source: Dictionary, start_ms: int) -> void:
+	var keep_menu_open := playing and panel.visible
 	decoder_ready = false
 	if not seeking and not stereo_overridden: mode = Stereo.detect(source)
 	if not seeking and not projection_overridden:
@@ -323,10 +449,10 @@ func _play_stream(url: String, source: Dictionary, start_ms: int) -> void:
 		if stream.get("Type", "") == "Video":
 			video_size = Vector2i(int(stream.get("Width", 1920)), int(stream.get("Height", 1080)))
 	transcode_offset = session.position_ticks if session.method == "Transcode" and not session.is_hls() else 0
-	if not seeking: _recenter()
+	if not seeking: _resize_screen()
 	screen.show()
 	playing = true
-	if not seeking: _show_playback()
+	if not seeking and not keep_menu_open: _show_playback()
 	_update_timeline()
 	await video.open(url, api.authorization(), start_ms)
 
@@ -334,9 +460,8 @@ func _video_prepared() -> void:
 	decoder_ready = true
 	if seeking and seek_paused: video.toggle_pause()
 	session.report("Playing", video.paused)
-	status.text = "Playing. Press A or B to show the controls."
-	if get_viewport().use_xr and not seeking:
-		panel.hide()
+	status.text = "Playing. Press A for controls or B for the library."
+	if get_viewport().use_xr and not seeking and not panel.visible:
 		player_overlay.hide()
 	seeking = false
 	_update_timeline()
@@ -344,24 +469,33 @@ func _video_prepared() -> void:
 func _show_playback() -> void:
 	keyboard.hide()
 	panel.hide()
-	player_overlay.title.text = DetailsMetadata.title(session.item, "Now playing")
+	player_overlay.set_photo_mode(photo_active)
+	if photo_active: player_overlay.set_photo_navigation(photo_sequence.index > 0, photo_sequence.can_next())
+	player_overlay.title.text = DetailsMetadata.title(photo_item if photo_active else session.item, "Now playing")
 	player_overlay.show()
 	_update_timeline()
 
 func _player_action(action: String) -> void:
+	if photo_active and action in ["pause", "back", "forward", "skip_segment"]: return
 	match action:
+		"previous_photo": _step_photo(-1)
+		"next_photo": _step_photo(1)
 		"pause":
 			video.toggle_pause()
 			session.report("Progress", video.paused)
 			_update_timeline()
 		"back": _skip(-10000)
 		"forward": _skip(30000)
+		"skip_segment": _skip_segment()
 		"stop": _stop()
 		"settings": _screen_settings()
 		"library": _return_to_title()
 		"hide": player_overlay.hide()
 
 func _return_to_title() -> void:
+	if photo_active:
+		_show_library()
+		return
 	var item := session.item
 	if item.is_empty():
 		_show_library()
@@ -382,11 +516,29 @@ func _return_to_title() -> void:
 			return
 	await _details({"Id": target_id}, season)
 
+func _toggle_settings() -> void:
+	if api.token.is_empty() or not shell.signed_in: return
+	for child in page.get_children():
+		if child is SettingsView:
+			_toggle_panel()
+			return
+	_screen_settings()
+
 func _screen_settings() -> void:
-	_clear_page()
-	var previous_heading := shell.heading.text if shell.heading.text != "Settings" else "Home"
+	if api.token.is_empty() or not shell.signed_in: return
+	for child in page.get_children():
+		if child is LibraryView or child is DetailsView:
+			settings_return_page = child
+			settings_return_heading = shell.heading.text
+			settings_return_status = status.text
+			child.hide()
+			child.reparent(viewport)
+	_clear_page(true)
+	panel.show()
 	shell.heading.text = "Settings"
+	shell.set_settings_mode(true)
 	var view := SettingsView.new()
+	view.navigation_host = shell.settings_navigation
 	view.settings = settings
 	view.passthrough_supported = world.passthrough.is_supported()
 	view.stereo_mode = mode
@@ -394,19 +546,28 @@ func _screen_settings() -> void:
 	view.swap_eyes = material.get_shader_parameter("swap_eyes") == true
 	view.size_flags_vertical = Control.SIZE_EXPAND_FILL
 	view.screen_changed.connect(func(): _resize_screen(); _position_screen())
+	view.screen_follow_changed.connect(_update_screen_follow)
 	view.environment_changed.connect(_change_environment)
 	view.stereo_selected.connect(_select_stereo)
 	view.projection_selected.connect(_select_projection)
 	view.eyes_swapped.connect(func(): material.set_shader_parameter("swap_eyes", not material.get_shader_parameter("swap_eyes")))
 	view.status.connect(func(message: String): status.text = message)
-	view.back_requested.connect(func():
-		shell.heading.text = previous_heading
-		if playing: _show_playback()
-		elif not api.token.is_empty(): _show_library()
-		else: _show_login())
 	page.add_child(view)
 	status.text = "Changes take effect as you make them."
 
+func _return_from_settings() -> void:
+	if not is_instance_valid(settings_return_page):
+		_show_library()
+		return
+	var previous := settings_return_page
+	settings_return_page = null
+	_clear_page()
+	previous.reparent(page)
+	previous.show()
+	shell.heading.text = settings_return_heading
+	status.text = settings_return_status
+	panel.show()
+
 func _resize_screen() -> void:
 	var panoramic := projection_mode != VideoProjection.Mode.SCREEN
 	var aspect_ratio := 16.0 / 9.0 if panoramic else Stereo.aspect(video_size.x, video_size.y, mode)
@@ -420,6 +581,7 @@ func _resize_screen() -> void:
 	material.set_shader_parameter("top_bottom", mode == Stereo.Mode.TOP_BOTTOM)
 	player_overlay.fit_screen(dimensions.x, aspect_ratio, curvature)
 	world.player_loading.fit_screen(dimensions.x, curvature)
+	world.skip_screen_size = Vector3(dimensions.x, aspect_ratio, curvature)
 
 func _select_projection(value: int) -> void:
 	projection_mode = value
@@ -446,9 +608,8 @@ func _recenter() -> void:
 func _recenter_video() -> void:
 	screen.global_basis = camera.global_basis
 	theatre.recenter(camera.global_transform)
-	if world.panoramic:
-		world.panorama.global_position = camera.global_position
-		world.panorama.global_rotation = Vector3(0.0, camera.global_rotation.y, 0.0)
+	world.panorama.global_position = camera.global_position
+	world.panorama.global_rotation = Vector3(0.0, camera.global_rotation.y, 0.0)
 	_position_screen()
 	_resize_screen()
 
@@ -460,12 +621,18 @@ func _position_screen() -> void:
 	else:
 		screen.global_position = camera.global_position - screen.global_basis.z * settings.distance + screen.global_basis.y * settings.height
 
+func _update_screen_follow() -> void:
+	if not settings.follow_screen or settings.environment not in ["Void", "Passthrough"]: return
+	if projection_mode != VideoProjection.Mode.SCREEN: return
+	screen.global_basis = camera.global_basis
+	_position_screen()
+
 func _toggle_menu() -> void:
 	if not get_viewport().use_xr: return
 	if autoplay_pending:
 		_show_library()
 		return
-	if playing:
+	if playing or photo_active:
 		if player_overlay.visible: player_overlay.hide()
 		else: _show_playback()
 	else: panel.visible = not panel.visible
@@ -474,7 +641,6 @@ func _skip(amount: int) -> void:
 	_seek_to(int(transcode_offset / 10000) + video.position_ms() + amount)
 
 func _duration_ms() -> int:
-	if calibration: return video.duration_ms()
 	var ticks := int(session.source.get("RunTimeTicks", 0))
 	if ticks <= 0: ticks = int(session.item.get("RunTimeTicks", 0))
 	if ticks > 0: return int(ticks / 10000)
@@ -482,13 +648,24 @@ func _duration_ms() -> int:
 	return duration + int(transcode_offset / 10000) if duration > 0 else 0
 
 func _update_timeline() -> void:
-	if autoplay_pending: return
+	if autoplay_pending or photo_active: return
 	player_overlay.update_time(int(transcode_offset / 10000) + video.position_ms(), _duration_ms(), decoder_ready and not seeking, video.paused)
+	world.player_skip_popup.update_segment(_active_segment())
 	_update_loading()
 
+func _active_segment() -> Dictionary:
+	if not playing or not decoder_ready or seeking: return {}
+	return media_segments.active(int(transcode_offset / 10000) + video.position_ms(), _duration_ms())
+
+func _skip_segment() -> void:
+	var segment := _active_segment()
+	if not segment.is_empty(): _seek_to(int(segment.target_ms))
+
 func _update_loading() -> void:
 	if autoplay_pending: return
-	if playing and (not decoder_ready or seeking):
+	if photo_active and photo_loading:
+		world.player_loading.show_photo_loading()
+	elif playing and (not decoder_ready or seeking):
 		world.player_loading.show_loading()
 	elif playing and video.is_buffering():
 		world.player_loading.show_buffering()
@@ -498,7 +675,7 @@ func _update_loading() -> void:
 func _seek_to(milliseconds: int) -> void:
 	if not playing or seeking or not decoder_ready: return
 	var target := clampi(milliseconds, 0, maxi(0, _duration_ms() - 1000))
-	if calibration or session.method != "Transcode" or session.is_hls():
+	if session.method != "Transcode" or session.is_hls():
 		video.seek(target)
 		return
 	seeking = true
@@ -515,6 +692,9 @@ func _seek_to(milliseconds: int) -> void:
 	await session.open(session.item, true)
 
 func _stop(show_library: bool = true, completed: bool = false) -> void:
+	_close_photo()
+	media_segments.clear()
+	world.player_skip_popup.update_segment({})
 	countdown_generation += 1
 	_cancel_countdown()
 	world.player_loading.hide()
@@ -532,12 +712,6 @@ func _stop(show_library: bool = true, completed: bool = false) -> void:
 
 func _ended() -> void:
 	if not playing: return
-	if calibration:
-		await _stop(false)
-		calibration = false
-		_show_login()
-		if get_viewport().use_xr: panel.show()
-		return
 	var previous := session.item.duplicate(true)
 	var generation := countdown_generation + 1
 	await _stop(false, true)
@@ -580,9 +754,6 @@ func _cancel_countdown() -> void:
 
 func _video_failed(message: String) -> void:
 	status.text = message
-	if calibration:
-		_error(message)
-		return
 	if video.available() and playing:
 		decoder_ready = false
 		_update_timeline()
@@ -591,6 +762,8 @@ func _video_failed(message: String) -> void:
 		await session.retry_transcode()
 
 func _error(message: String) -> void:
+	media_segments.clear()
+	world.player_skip_popup.update_segment({})
 	countdown_generation += 1
 	_cancel_countdown()
 	world.player_loading.hide()
@@ -618,6 +791,7 @@ func _sign_out() -> void:
 	_show_login()
 
 func _process(delta: float) -> void:
+	_update_screen_follow()
 	if not playing: return
 	_update_loading()
 	timeline_elapsed += delta
@@ -633,21 +807,3 @@ func _process(delta: float) -> void:
 
 func _unhandled_input(event: InputEvent) -> void:
 	if event is InputEventKey and event.pressed and event.keycode == KEY_ESCAPE: _toggle_menu()
-
-
-func _calibrate() -> void:
-	transcode_offset = 0
-	decoder_ready = false
-	print("Jellyframe: calibration requested")
-	calibration = true
-	mode = Stereo.Mode.HALF_SBS
-	video_size = Vector2i(1920, 1080)
-	_resize_screen()
-	_recenter()
-	print("Jellyframe: calibration screen positioned")
-	screen.show()
-	playing = true
-	status.text = "Close one eye at a time. Check that LEFT appears in your left eye and RIGHT in your right eye."
-	_update_timeline()
-	await video.open(video.bridge.calibration_url(), "", 0)
-	if get_viewport().use_xr: panel.hide()

scripts/player/android_video.gd

@@ -2,6 +2,9 @@ class_name AndroidVideo
 extends VideoBackend
 
 var texture: ExternalTexture
+var playback_generation := 0
+var stream_open := false
+var frame_visible := false
 
 func _ready() -> void:
 	if not Engine.has_singleton("JellyframeVideo"): return
@@ -22,17 +25,24 @@ func unavailable_message() -> String:
 	return "Video playback requires the Jellyframe Android plugin."
 
 func open(url: String, authorization: String, start_ms: int) -> void:
-	print("Jellyframe: opening video")
+	playback_generation += 1
+	var opening := playback_generation
+	_clear_frame()
 	if not available():
 		failed.emit(unavailable_message())
 		return
 	material.set_shader_parameter("video_texture", texture)
-	print("Jellyframe: external texture assigned")
 	await RenderingServer.frame_post_draw
-	print("Jellyframe: starting decoder, texture ID ", texture.get_external_texture_id())
+	if opening != playback_generation: return
 	bridge.open_video(texture.get_external_texture_id(), url, authorization, start_ms)
+	stream_open = true
 	paused = false
 
+func _clear_frame() -> void:
+	stream_open = false
+	frame_visible = false
+	if material != null: material.set_shader_parameter("video_ready", false)
+
 func toggle_pause() -> void:
 	if available():
 		paused = not paused
@@ -51,10 +61,16 @@ func is_buffering() -> bool:
 	return bridge.is_buffering() if available() else false
 
 func stop() -> void:
+	playback_generation += 1
+	_clear_frame()
 	if available(): bridge.stop_video()
 
 func _process(_delta: float) -> void:
 	if not available() or material == null: return
+	var ready: bool = stream_open and bridge.has_video_frame()
+	if ready != frame_visible:
+		frame_visible = ready
+		material.set_shader_parameter("video_ready", ready)
 	var matrix: PackedFloat32Array = bridge.texture_transform()
 	if matrix.size() == 16:
 		material.set_shader_parameter("texture_transform", Projection(Vector4(matrix[0], matrix[1], matrix[2], matrix[3]), Vector4(matrix[4], matrix[5], matrix[6], matrix[7]), Vector4(matrix[8], matrix[9], matrix[10], matrix[11]), Vector4(matrix[12], matrix[13], matrix[14], matrix[15])))

scripts/player/pc_video.gd

@@ -12,6 +12,7 @@ func unavailable_message() -> String:
 	return "The video plugin is missing. Extract all files from the Windows build, including the DLLs."
 
 func open(url: String, authorization: String, start_ms: int) -> void:
+	_set_texture(null)
 	if not available():
 		failed.emit(unavailable_message())
 		return
@@ -22,11 +23,24 @@ func open(url: String, authorization: String, start_ms: int) -> void:
 		bridge.ended.connect(func(): ended.emit())
 		bridge.failed.connect(func(message: String): failed.emit(message))
 		bridge.size_changed.connect(func(w: int, h: int): size_changed.emit(w, h))
-		bridge.texture_changed.connect(func(texture: Texture2D): material.set_shader_parameter("video_texture", texture))
+		bridge.texture_changed.connect(_set_texture)
 	paused = false
 	var error: String = bridge.open_video(url, authorization, start_ms)
 	if not error.is_empty(): failed.emit(error)
 
+func _set_texture(texture: Texture2D) -> void:
+	if material == null: return
+	material.set_shader_parameter("video_texture", texture)
+	material.set_shader_parameter("direct_yuv", false)
+	var parameters: Dictionary = {}
+	if texture != null and bridge != null:
+		parameters = bridge.video_shader_parameters()
+	for parameter in parameters:
+		material.set_shader_parameter(parameter, parameters[parameter])
+	if parameters.is_empty():
+		for parameter in ["y_plane", "u_plane", "v_plane"]:
+			material.set_shader_parameter(parameter, null)
+
 func toggle_pause() -> void:
 	if bridge != null:
 		paused = not paused
@@ -42,5 +56,6 @@ func duration_ms() -> int:
 	return bridge.duration_ms() if bridge != null else 0
 
 func stop() -> void:
+	_set_texture(null)
 	if bridge != null: bridge.stop_video()
 	paused = false

scripts/ui/details.gd

@@ -2,6 +2,7 @@ class_name DetailsView
 extends VBoxContainer
 
 signal play_requested(item: Dictionary)
+signal play_from_start_requested(item: Dictionary)
 signal back_requested
 
 var item: Dictionary
@@ -12,6 +13,7 @@ var scroll: ScrollContainer
 var body: VBoxContainer
 var series_browser: SeriesBrowser
 var play_button: Button
+var play_from_start_button: Button
 var back_button: Button
 var title_label: Label
 var overview_label: Label
@@ -111,7 +113,9 @@ func _build_playback(parent: VBoxContainer) -> void:
 		return
 	var user: Dictionary = item.get("UserData", {}) if item.get("UserData") else {}
 	var position := int(user.get("PlaybackPositionTicks", 0))
-	var actions := HBoxContainer.new()
+	var actions := HFlowContainer.new()
+	actions.add_theme_constant_override("h_separation", 12)
+	actions.add_theme_constant_override("v_separation", 12)
 	parent.add_child(actions)
 	play_button = Widgets.button("Resume" if position > 0 else "Play movie", func(): play_requested.emit(item), actions)
 	play_button.custom_minimum_size = Vector2(200, 64)
@@ -126,6 +130,8 @@ func _build_playback(parent: VBoxContainer) -> void:
 	focus.border_color = Color("071c20")
 	play_button.add_theme_stylebox_override("focus", focus)
 	if position > 0:
+		play_from_start_button = Widgets.button("Play from start", func(): play_from_start_requested.emit(item), actions)
+		play_from_start_button.custom_minimum_size = Vector2(200, 64)
 		_muted("Continue from " + DetailsMetadata.duration(position), parent, 20)
 
 func _build_information() -> void:

scripts/ui/details_metadata.gd

@@ -22,8 +22,6 @@ static func facts(item: Dictionary) -> Array[String]:
 	if item.get("RunTimeTicks"): values.append(duration(int(item.RunTimeTicks)))
 	if item.get("OfficialRating"): values.append(str(item.OfficialRating))
 	if item.get("CommunityRating"): values.append("Rating %.1f / 10" % float(item.CommunityRating))
-	var user: Dictionary = item.get("UserData", {}) if item.get("UserData") else {}
-	if user.get("Played", false): values.append("Watched")
 	return values
 
 static func streams(item: Dictionary) -> Dictionary:

scripts/ui/episode_card.gd

@@ -42,6 +42,8 @@ func _ready() -> void:
 	title_label = _label(DetailsMetadata.title(item, "Episode"), text, 26)
 	var facts := DetailsMetadata.facts(item)
 	var user: Dictionary = item.get("UserData", {}) if item.get("UserData") else {}
+	if user.get("Played", false):
+		Widgets.watched_badge(frame)
 	var position := int(user.get("PlaybackPositionTicks", 0))
 	if position > 0: facts.append("Continue from " + DetailsMetadata.duration(position))
 	if not facts.is_empty():
@@ -50,6 +52,8 @@ func _ready() -> void:
 	play_button = Widgets.button("Resume episode" if position > 0 else "Play episode", func(): chosen.emit(item), image_column)
 	play_button.custom_minimum_size = Vector2(190, 56)
 	play_button.accessibility_name = play_button.text + " " + title_label.text
+	if user.get("Played", false):
+		play_button.accessibility_name += ", watched"
 
 func _label(value: String, parent: Node, font_size: int) -> Label:
 	var label := Widgets.label(value, parent, font_size)

scripts/ui/library.gd

@@ -27,7 +27,7 @@ func _ready() -> void:
 	add_child(artwork)
 	var tools := HBoxContainer.new()
 	add_child(tools)
-	field = Widgets.input("Search " + ("movies and shows" if library_id.is_empty() else library_name), tools)
+	field = Widgets.input("Search " + library_name, tools)
 	field.size_flags_horizontal = Control.SIZE_EXPAND_FILL
 	field.text_submitted.connect(refresh)
 	Widgets.button("Search", func(): refresh(field.text), tools)
@@ -80,9 +80,9 @@ func _more(current: int) -> void:
 		return
 	var items: Array = result.data.get("Items", [])
 	if offset == 0:
-		if search.is_empty() and not items.is_empty():
+		if search.is_empty() and items.any(func(item: Dictionary): return item.get("Type", "") != "Photo"):
 			var hero := LibraryHero.new()
-			hero.item = _choose_hero(items)
+			hero.item = _choose_hero(items.filter(func(item: Dictionary): return item.get("Type", "") != "Photo"))
 			hero.artwork = artwork
 			hero.chosen.connect(func(item: Dictionary): selected.emit(item))
 			content.add_child(hero)

scripts/ui/media_card.gd

@@ -32,6 +32,8 @@ func _ready() -> void:
 	var poster := TextureRect.new()
 	poster.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
 	poster.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_COVERED
+	if item.get("Type", "") == "Photo":
+		poster.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
 	poster.mouse_filter = Control.MOUSE_FILTER_IGNORE
 	image_frame.add_child(poster)
 	artwork.fetch(poster, item)
@@ -41,8 +43,9 @@ func _ready() -> void:
 	title.mouse_filter = Control.MOUSE_FILTER_IGNORE
 	var user_data: Dictionary = item.get("UserData", {}) if item.get("UserData") else {}
 	var detail := DetailsMetadata.year(item)
+	if item.get("Type", "") == "Photo": detail = ""
 	if user_data.get("Played", false):
-		_watched_badge(image_frame)
+		Widgets.watched_badge(image_frame)
 		accessibility_name = tooltip_text + ", watched"
 	if item.get("Type", "") == "Series": detail += "  /  Series"
 	var subtitle := Widgets.label(detail.trim_prefix("  /  "), body, 16)
@@ -58,19 +61,3 @@ func _ready() -> void:
 		bar.add_theme_stylebox_override("background", Widgets.surface(Color("29374b"), 2))
 		bar.add_theme_stylebox_override("fill", Widgets.surface(Color("6de3cf"), 2))
 		body.add_child(bar)
-
-func _watched_badge(image_frame: PanelContainer) -> void:
-	var overlay := Control.new()
-	overlay.mouse_filter = Control.MOUSE_FILTER_IGNORE
-	image_frame.add_child(overlay)
-	var badge := TextureRect.new()
-	badge.texture = preload("res://assets/icons/watched.svg")
-	badge.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
-	badge.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
-	badge.mouse_filter = Control.MOUSE_FILTER_IGNORE
-	overlay.add_child(badge)
-	badge.set_anchors_and_offsets_preset(Control.PRESET_TOP_RIGHT)
-	badge.offset_left = -36
-	badge.offset_top = 8
-	badge.offset_right = -8
-	badge.offset_bottom = 36

scripts/ui/menu_feedback.gd

@@ -22,7 +22,6 @@ func _connect_button(node: Node) -> void:
 	if not button.pressed.is_connected(_play): button.pressed.connect(_play)
 
 func _play() -> void:
-	if OS.is_debug_build() and OS.get_name() == "Android": print("Jellyframe input: button activated")
 	player.play()
 
 func _click_sound() -> AudioStreamWAV:

scripts/ui/photo_view.gd

@@ -0,0 +1,48 @@
+class_name PhotoView
+extends Node
+
+signal photo_ready(texture: Texture2D)
+signal failed(message: String)
+var api: JellyfinClient
+var item: Dictionary
+var request: HTTPRequest
+
+static func stereo_mode(photo: Dictionary) -> Stereo.Mode:
+	var source := {"Path": photo.get("Path", photo.get("Name", "")), "Video3DFormat": photo.get("Video3DFormat", "")}
+	var detected := Stereo.detect(source)
+	if detected != Stereo.Mode.MONO: return detected
+	var pattern := RegEx.new()
+	pattern.compile("(?i)(?:^|[ ._\\-])sbs(?:$|[ ._\\-])")
+	return Stereo.Mode.FULL_SBS if pattern.search(str(source.Path).get_file()) else Stereo.Mode.MONO
+
+func _ready() -> void:
+	request = HTTPRequest.new()
+	request.timeout = 30
+	request.body_size_limit = 32 * 1024 * 1024
+	request.request_completed.connect(_loaded)
+	add_child(request)
+
+func _load() -> void:
+	var url := api.server + "/Items/%s/Images/Primary" % str(item.Id).uri_encode()
+	url += api.query({"maxWidth": 3840, "maxHeight": 3840, "quality": 95, "format": "Jpg"})
+	if request.request(url, ["Authorization: " + api.authorization()]) != OK:
+		_failed("Could not start the photo request.")
+
+func _loaded(result: int, code: int, _headers: PackedStringArray, body: PackedByteArray) -> void:
+	if result != HTTPRequest.RESULT_SUCCESS:
+		_failed("Could not load the photo. Check your connection and try again.")
+		return
+	if code != 200:
+		_failed("Could not load the photo. Server returned HTTP %d." % code)
+		return
+	var image := Image.new()
+	if image.load_jpg_from_buffer(body) != OK:
+		_failed("The server returned an unreadable photo.")
+		return
+	photo_ready.emit(ImageTexture.create_from_image(image))
+
+func _failed(text: String) -> void:
+	failed.emit(text)
+
+func _exit_tree() -> void:
+	if is_instance_valid(request): request.cancel_request()

scripts/ui/photo_view.gd.uid

@@ -0,0 +1 @@
+uid://wo7uui2jccph

scripts/ui/player_loading.gd

@@ -33,9 +33,9 @@ func _ready() -> void:
 	var material := StandardMaterial3D.new()
 	material.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
 	material.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
-	material.no_depth_test = true
 	material.render_priority = 1
 	material.albedo_texture = viewport.get_texture()
+	VrOverlayMaterial.apply_depth(material)
 	material_override = material
 	var panel := PanelContainer.new()
 	panel.theme = Widgets.theme()
@@ -62,6 +62,9 @@ func _ready() -> void:
 func show_loading() -> void:
 	_show_waiting("Loading video...")
 
+func show_photo_loading() -> void:
+	_show_waiting("Loading photo...")
+
 func show_buffering() -> void:
 	_show_waiting("Buffering video...")
 

scripts/ui/player_overlay.gd

@@ -12,6 +12,14 @@ var play_icon: Texture2D
 var pause_icon: Texture2D
 var tooltip: Label
 var hovered_control: Control
+var video_controls: Array[Button] = []
+var stop_button: Button
+var controls_spacer: Control
+var controls_row: HBoxContainer
+var photo_mode := false
+var previous_photo: Button
+var next_photo: Button
+var screen_dimensions := Vector3(3.6, 16.0 / 9.0, 0.0)
 
 func _ready() -> void:
 	play_icon = load("res://assets/icons/material/play_arrow.svg")
@@ -25,6 +33,7 @@ func _ready() -> void:
 	material.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
 	material.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
 	material.albedo_texture = viewport.get_texture()
+	VrOverlayMaterial.apply_depth(material)
 	material_override = material
 	var panel := PanelContainer.new()
 	panel.theme = Widgets.theme()
@@ -45,27 +54,69 @@ func _ready() -> void:
 	timeline.slider.mouse_exited.connect(_hide_tooltip.bind(timeline.slider))
 	timeline.slider.focus_entered.connect(_show_tooltip.bind(timeline.slider))
 	timeline.slider.focus_exited.connect(_hide_tooltip.bind(timeline.slider))
-	var row := HBoxContainer.new()
-	row.add_theme_constant_override("separation", 12)
-	body.add_child(row)
-	for entry in [["Pause", "pause", "pause"], ["Stop", "stop", "stop"], ["Back 10 seconds", "back", "replay_10"], ["Forward 30 seconds", "forward", "forward_30"], ["Settings", "settings", "settings"], ["Library", "library", "video_library"], ["Hide controls", "hide", "visibility_off"]]:
-		var button := Widgets.button("", func(): action.emit(entry[1]), row)
-		button.icon = load("res://assets/icons/material/%s.svg" % entry[2])
-		button.accessibility_name = entry[0]
-		button.custom_minimum_size = Vector2(140, 72)
-		button.icon_alignment = HORIZONTAL_ALIGNMENT_CENTER
-		button.add_theme_constant_override("icon_max_width", 44)
-		button.mouse_entered.connect(_show_tooltip.bind(button))
-		button.mouse_exited.connect(_hide_tooltip.bind(button))
-		button.focus_entered.connect(_show_tooltip.bind(button))
-		button.focus_exited.connect(_hide_tooltip.bind(button))
-		if entry[1] == "pause": pause_button = button
+	_build_controls(body)
 	tooltip = Widgets.label("", body, 20)
 	tooltip.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
 	tooltip.mouse_filter = Control.MOUSE_FILTER_IGNORE
 	tooltip.custom_minimum_size.y = 28
 	hide()
 
+func _build_controls(parent: Control) -> void:
+	var row := HBoxContainer.new()
+	controls_row = row
+	row.add_theme_constant_override("separation", 12)
+	parent.add_child(row)
+	pause_button = _add_control("Pause", "pause", "pause", row)
+	stop_button = _add_control("Stop", "stop", "stop", row)
+	_add_control("Back 10 seconds", "back", "replay_10", row)
+	_add_control("Forward 30 seconds", "forward", "forward_30", row)
+	controls_spacer = row.add_spacer(false)
+	var tracks := _add_control("Audio and subtitles (coming soon)", "tracks", "subtitles", row)
+	tracks.disabled = true
+	tracks.mouse_default_cursor_shape = Control.CURSOR_ARROW
+	tracks.add_theme_color_override("icon_disabled_color", Color("8793a8"))
+	_add_control("Settings", "settings", "settings", row)
+	_add_control("Hide controls", "hide", "visibility_off", row)
+	previous_photo = _add_control("Previous photo", "previous_photo", "chevron_left", row)
+	next_photo = _add_control("Next photo", "next_photo", "chevron_right", row)
+	previous_photo.hide()
+	next_photo.hide()
+
+func _add_control(label: String, action_name: String, icon_name: String, parent: Control) -> Button:
+	var button := Widgets.button("", func(): action.emit(action_name), parent)
+	if action_name in ["pause", "back", "forward", "tracks"]: video_controls.append(button)
+	button.icon = load("res://assets/icons/material/%s.svg" % icon_name)
+	button.accessibility_name = label
+	button.custom_minimum_size = Vector2(140, 72)
+	button.icon_alignment = HORIZONTAL_ALIGNMENT_CENTER
+	button.add_theme_constant_override("icon_max_width", 44)
+	button.mouse_entered.connect(_show_tooltip.bind(button))
+	button.mouse_exited.connect(_hide_tooltip.bind(button))
+	button.focus_entered.connect(_show_tooltip.bind(button))
+	button.focus_exited.connect(_hide_tooltip.bind(button))
+	return button
+
+func set_photo_mode(enabled: bool) -> void:
+	photo_mode = enabled
+	previous_photo.visible = enabled
+	next_photo.visible = enabled
+	controls_row.move_child(previous_photo, 0 if enabled else controls_row.get_child_count() - 1)
+	controls_row.move_child(next_photo, 1 if enabled else controls_row.get_child_count() - 1)
+	timeline.visible = not enabled
+	for button in video_controls: button.visible = not enabled
+	controls_spacer.visible = not enabled
+	controls_row.alignment = BoxContainer.ALIGNMENT_CENTER if enabled else BoxContainer.ALIGNMENT_BEGIN
+	stop_button.icon = load("res://assets/icons/material/logout.svg" if enabled else "res://assets/icons/material/stop.svg")
+	stop_button.accessibility_name = "Exit" if enabled else "Stop"
+	viewport.size = Vector2i(820, 210) if enabled else Vector2i(1400, 300)
+	fit_screen(screen_dimensions.x, screen_dimensions.y, screen_dimensions.z)
+	hovered_control = null
+	tooltip.text = ""
+
+func set_photo_navigation(has_previous: bool, has_next: bool) -> void:
+	previous_photo.disabled = not has_previous
+	next_photo.disabled = not has_next
+
 func _show_tooltip(control: Control) -> void:
 	hovered_control = control
 	tooltip.text = control.accessibility_name
@@ -83,7 +134,9 @@ func _process(_delta: float) -> void:
 		tooltip.text = hovered_control.accessibility_name
 
 func fit_screen(width: float, aspect: float, curvature: float) -> void:
-	panel_size = Vector2(width * 0.94, width * 0.94 * 300.0 / 1400.0)
+	screen_dimensions = Vector3(width, aspect, curvature)
+	var panel_width := width * 0.94 * float(viewport.size.x) / 1400.0
+	panel_size = Vector2(panel_width, panel_width * float(viewport.size.y) / float(viewport.size.x))
 	var quad := QuadMesh.new()
 	quad.size = panel_size
 	mesh = quad

scripts/ui/player_skip_popup.gd

@@ -0,0 +1,59 @@
+class_name PlayerSkipPopup
+extends MeshInstance3D
+
+signal skip_requested
+
+var viewport: SubViewport
+var button: Button
+var panel_size := Vector2.ZERO
+var available := false
+
+func _ready() -> void:
+	cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF
+	viewport = SubViewport.new()
+	viewport.size = Vector2i(300, 90)
+	viewport.transparent_bg = true
+	viewport.render_target_update_mode = SubViewport.UPDATE_DISABLED
+	add_child(viewport)
+	var material := StandardMaterial3D.new()
+	material.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+	material.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
+	material.render_priority = 1
+	material.albedo_texture = viewport.get_texture()
+	VrOverlayMaterial.apply_depth(material)
+	material_override = material
+	button = Widgets.button("Skip intro", func(): skip_requested.emit(), viewport)
+	button.theme = Widgets.theme()
+	button.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+	button.add_theme_font_size_override("font_size", 30)
+	for state in ["normal", "hover", "pressed", "disabled"]:
+		var style := Widgets.surface(Color("101624db"), 22, 16)
+		if state in ["hover", "pressed"]:
+			style.set_border_width_all(3)
+			style.border_color = Color("6de3cf") if state == "hover" else Color("47bda9")
+		button.add_theme_stylebox_override(state, style)
+	var focus := Widgets.surface(Color.TRANSPARENT, 22, 16)
+	focus.set_border_width_all(3)
+	focus.border_color = Color("6de3cf")
+	button.add_theme_stylebox_override("focus", focus)
+	visibility_changed.connect(func():
+		viewport.render_target_update_mode = SubViewport.UPDATE_ALWAYS if is_visible_in_tree() else SubViewport.UPDATE_DISABLED
+		if not is_visible_in_tree(): button.release_focus())
+	hide()
+
+func update_segment(segment: Dictionary) -> void:
+	available = not segment.is_empty()
+	if not available:
+		hide()
+		return
+	button.text = str(segment.label)
+	button.accessibility_name = button.text
+
+func fit_screen(width: float, aspect: float, curvature: float, controls_height: float = 0.0) -> void:
+	panel_size = Vector2(width * 0.20, width * 0.06)
+	if mesh == null: mesh = QuadMesh.new()
+	mesh.size = panel_size
+	position.x = width * 0.47 - panel_size.x / 2.0
+	position.y = -width / aspect / 2.0 + width * 0.02 + panel_size.y / 2.0
+	if controls_height > 0.0: position.y += controls_height + width * 0.02
+	position.z = (1.0 - cos(curvature / 2.0)) * width / curvature + 0.035 if curvature > 0.001 else 0.035

scripts/ui/player_skip_popup.gd.uid

@@ -0,0 +1 @@
+uid://xa6vnyg643ki

scripts/ui/screen_position_slider.gd

@@ -0,0 +1,42 @@
+extends HSlider
+
+var pending_steps := 0.0
+
+func _init() -> void:
+	scrollable = false
+	tooltip_text = "Point here and move the joystick left or right to adjust."
+	var track := Widgets.surface(Color("445268"), 7)
+	track.content_margin_top = 7
+	track.content_margin_bottom = 7
+	add_theme_stylebox_override("slider", track)
+	var fill := track.duplicate() as StyleBoxFlat
+	fill.bg_color = Color("6de3cf")
+	add_theme_stylebox_override("grabber_area", fill)
+	add_theme_stylebox_override("grabber_area_highlight", fill)
+	_style_grabbers()
+	mouse_exited.connect(func(): pending_steps = 0.0)
+
+func _style_grabbers() -> void:
+	for state in ["grabber", "grabber_highlight", "grabber_disabled"]:
+		var color := Color("8793a8") if state == "grabber_disabled" else Color("6de3cf")
+		if state == "grabber_highlight": color = Color.WHITE
+		var gradient := Gradient.new()
+		gradient.colors = PackedColorArray([color, color, Color(color, 0)])
+		gradient.offsets = PackedFloat32Array([0.0, 0.85, 1.0])
+		var texture := GradientTexture2D.new()
+		texture.gradient = gradient
+		texture.width = 26
+		texture.height = 26
+		texture.fill = GradientTexture2D.FILL_RADIAL
+		texture.fill_from = Vector2(0.5, 0.5)
+		texture.fill_to = Vector2(1.0, 0.5)
+		add_theme_icon_override(state, texture)
+
+func adjust_horizontal(amount: float) -> void:
+	if not editable: return
+	if signf(amount) != signf(pending_steps): pending_steps = 0.0
+	pending_steps += amount
+	var steps := int(pending_steps)
+	if steps == 0: return
+	pending_steps -= steps
+	value += steps * step

scripts/ui/settings_view.gd

@@ -1,8 +1,8 @@
 class_name SettingsView
 extends VBoxContainer
 
-signal back_requested
 signal screen_changed
+signal screen_follow_changed
 signal environment_changed
 signal stereo_selected(value: int)
 signal projection_selected(value: int)
@@ -19,37 +19,43 @@ var screen_dimensions: GridContainer
 var stereo_choices: HFlowContainer
 var reset_screen_button: Button
 var playback_choices: VBoxContainer
+var transcode_options: VBoxContainer
+var transcode_choices: HFlowContainer
 var sections: Array[VBoxContainer] = []
 var scroll: ScrollContainer
 var dragging_slider := false
+var navigation_host: Container
+var navigation: GridContainer
+var navigation_buttons: Array[Button] = []
+var section_heading: Label
+var sort_order_choices: HBoxContainer
+var environment_choices: VBoxContainer
+var environment_buttons: Dictionary = {}
+var follow_switch: CheckButton
+
+const SECTION_TITLES := ["Library sorting", "Screen", "Environment", "Playback"]
+const SECTION_ICONS := [
+	preload("res://assets/icons/material/video_library.svg"),
+	preload("res://assets/icons/material/tv.svg"),
+	preload("res://assets/icons/material/home.svg"),
+	preload("res://assets/icons/material/play_arrow.svg")
+]
 
 func _ready() -> void:
-	add_theme_constant_override("separation", 18)
-	var navigation := HFlowContainer.new()
-	navigation.add_theme_constant_override("h_separation", 12)
-	navigation.add_theme_constant_override("v_separation", 12)
-	add_child(navigation)
-	var group := ButtonGroup.new()
-	for index in range(4):
-		var title: String = ["Library sorting", "Screen", "Environment", "Playback"][index]
-		var button := Widgets.button(title, func(): _show_section(index), navigation)
-		button.toggle_mode = true
-		button.button_group = group
-		button.button_pressed = index == 0
-		button.accessibility_name = title
-		button.text = ("● " if index == 0 else "") + title
-		button.toggled.connect(func(selected: bool): button.text = ("● " if selected else "") + title)
-		button.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+	add_theme_constant_override("separation", 20)
+	_build_navigation()
+	section_heading = Widgets.label(SECTION_TITLES[0], self, 28)
 	scroll = ScrollContainer.new()
 	scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL
 	scroll.horizontal_scroll_mode = ScrollContainer.SCROLL_MODE_DISABLED
+	scroll.follow_focus = true
 	add_child(scroll)
 	var body := VBoxContainer.new()
 	body.size_flags_horizontal = Control.SIZE_EXPAND_FILL
 	scroll.add_child(body)
 	for index in range(4):
 		var section := VBoxContainer.new()
-		section.add_theme_constant_override("separation", 18)
+		section.add_theme_constant_override("separation", 24)
 		section.visible = index == 0
 		body.add_child(section)
 		sections.append(section)
@@ -57,52 +63,99 @@ func _ready() -> void:
 	_build_screen(sections[1])
 	_build_environment(sections[2])
 	_build_playback(sections[3])
-	Widgets.button("Back", func(): back_requested.emit(), self)
 	resized.connect(_adapt_columns)
+	scroll.resized.connect(_adapt_columns)
 	_adapt_columns()
 
+func _build_navigation() -> void:
+	navigation = GridContainer.new()
+	navigation.size_flags_vertical = Control.SIZE_SHRINK_BEGIN
+	navigation.add_theme_constant_override("v_separation", 8)
+	navigation.add_theme_constant_override("h_separation", 8)
+	navigation_host.add_child(navigation)
+	var group := ButtonGroup.new()
+	for index in range(4):
+		var title: String = SECTION_TITLES[index]
+		var button := Widgets.button(title, func(): _show_section(index), navigation)
+		button.toggle_mode = true
+		button.button_group = group
+		button.button_pressed = index == 0
+		button.accessibility_name = title
+		button.alignment = HORIZONTAL_ALIGNMENT_LEFT
+		button.icon = SECTION_ICONS[index]
+		button.expand_icon = true
+		button.add_theme_constant_override("icon_max_width", 24)
+		button.add_theme_constant_override("h_separation", 12)
+		button.add_theme_font_size_override("font_size", 19)
+		button.custom_minimum_size = Vector2(0, 64)
+		button.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+		_style_control(button)
+		navigation_buttons.append(button)
+
 func _show_section(index: int) -> void:
 	for section_index in range(sections.size()):
 		sections[section_index].visible = section_index == index
+	navigation_buttons[index].button_pressed = true
+	section_heading.text = SECTION_TITLES[index]
 	scroll.scroll_vertical = 0
 
+func _card(parent: VBoxContainer, title: String = "") -> VBoxContainer:
+	var panel := PanelContainer.new()
+	panel.add_theme_stylebox_override("panel", Widgets.surface(Color("162133"), 20, 20))
+	parent.add_child(panel)
+	var body := VBoxContainer.new()
+	body.add_theme_constant_override("separation", 12)
+	panel.add_child(body)
+	if not title.is_empty(): Widgets.label(title, body, 22)
+	return body
+
+func _style_control(control: Button) -> void:
+	for state in ["normal", "hover", "pressed", "hover_pressed", "disabled", "focus"]:
+		var color := Color("202a3d")
+		if state in ["hover", "disabled"]: color = Color("34435b")
+		if state in ["pressed", "hover_pressed"]: color = Color("2b4b50")
+		if state == "focus": color = Color(0, 0, 0, 0)
+		var style := Widgets.surface(color, 12, 12)
+		if state in ["hover", "hover_pressed", "focus"]:
+			style.set_border_width_all(3)
+			style.border_color = Color("6de3cf")
+		control.add_theme_stylebox_override(state, style)
+	control.add_theme_color_override("font_disabled_color", Color("8793a8"))
+
 func _hint(message: String, parent: Node) -> void:
 	var label := Widgets.label(message, parent, 18)
 	label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
 	label.add_theme_color_override("font_color", Color("a4aec0"))
 
 func _build_library(parent: VBoxContainer) -> void:
-	_hint("Choose how to sort your libraries. Home always shows the newest additions first.", parent)
-	Widgets.label("Sort by", parent, 26)
+	_hint("Choose how to sort your libraries. Home shows the newest additions first.", parent)
+	var order_card := _card(parent, "Sort order")
+	sort_order_choices = HBoxContainer.new()
+	sort_order_choices.add_theme_constant_override("separation", 12)
+	order_card.add_child(sort_order_choices)
+	var order_group := ButtonGroup.new()
+	for value in ["Ascending", "Descending"]:
+		_choice(value, value == settings.library_sort_order, order_group, sort_order_choices,
+			func(): settings.library_sort_order = value; _save())
+	_hint("Ascending sorts A to Z, lowest to highest, or oldest to newest. Descending reverses the order. This setting does not affect Random.", order_card)
+	var sort_card := _card(parent, "Sort by")
 	sort_choices = GridContainer.new()
-	sort_choices.columns = 2
-	sort_choices.add_theme_constant_override("h_separation", 18)
+	sort_choices.add_theme_constant_override("h_separation", 8)
 	sort_choices.add_theme_constant_override("v_separation", 8)
-	parent.add_child(sort_choices)
+	sort_card.add_child(sort_choices)
 	var group := ButtonGroup.new()
 	for option in JellyframeSettings.LIBRARY_SORT_OPTIONS:
 		_choice(option[0], option[1] == settings.library_sort_by, group, sort_choices,
 			func(): settings.library_sort_by = option[1]; _save())
-	var order_heading := Widgets.label("Sort order", parent, 26)
-	var order := HBoxContainer.new()
-	order.add_theme_constant_override("separation", 18)
-	parent.add_child(order)
-	var order_group := ButtonGroup.new()
-	for value in ["Ascending", "Descending"]:
-		_choice(value, value == settings.library_sort_order, order_group, order,
-			func(): settings.library_sort_order = value; _save())
-	parent.move_child(order_heading, 1)
-	parent.move_child(order, 2)
-	_hint("Ascending sorts A to Z, low to high or oldest first. Descending reverses that order. Sort order does not affect Random.", parent)
 
 func _build_playback(parent: VBoxContainer) -> void:
-	Widgets.label("Playback quality", parent, 26)
+	parent = _card(parent, "Playback quality")
 	_hint("Choose the video quality. Your choice applies to the next video you start.", parent)
 	playback_choices = VBoxContainer.new()
 	playback_choices.add_theme_constant_override("separation", 12)
 	parent.add_child(playback_choices)
 	var group := ButtonGroup.new()
-	var conversion_hint := "Jellyfin converts the video for this device, up to 1080p at 30 fps."
+	var conversion_hint := "Jellyfin converts the video to the resolution you choose below, up to 30 fps."
 	for option in [
 		["Automatic", "auto", "Play the original file when supported. Otherwise, Jellyfin converts it."],
 		["Original full resolution", "original", "Play the original file without conversion. Your device must support its format."],
@@ -111,8 +164,31 @@ func _build_playback(parent: VBoxContainer) -> void:
 		var row := VBoxContainer.new()
 		playback_choices.add_child(row)
 		_choice(option[0], option[1] == settings.playback_mode, group, row,
-			func(): settings.playback_mode = option[1]; _save())
+			func(): _select_playback_mode(option[1]))
 		_hint(option[2], row)
+	_build_transcode_options(parent)
+
+func _select_playback_mode(value: String) -> void:
+	settings.playback_mode = value
+	transcode_options.visible = value == "transcoded"
+	_save()
+
+func _build_transcode_options(parent: VBoxContainer) -> void:
+	transcode_options = VBoxContainer.new()
+	transcode_options.add_theme_constant_override("separation", 12)
+	transcode_options.visible = settings.playback_mode == "transcoded"
+	parent.add_child(transcode_options)
+	Widgets.label("Transcoded resolution", transcode_options, 26)
+	transcode_choices = HFlowContainer.new()
+	transcode_choices.add_theme_constant_override("h_separation", 12)
+	transcode_choices.add_theme_constant_override("v_separation", 12)
+	transcode_options.add_child(transcode_choices)
+	var group := ButtonGroup.new()
+	for resolution in JellyframeSettings.TRANSCODE_PRESETS:
+		var preset: Dictionary = JellyframeSettings.TRANSCODE_PRESETS[resolution]
+		_choice(preset.label, settings.transcode_resolution == resolution, group, transcode_choices,
+			func(): settings.transcode_resolution = resolution; _save())
+	_hint("Choose a maximum resolution. Smaller videos keep their size. Higher resolutions need a faster connection and more server processing power.", transcode_options)
 
 func _choice(title: String, selected: bool, group: ButtonGroup, parent: Node, action: Callable) -> CheckBox:
 	var choice := CheckBox.new()
@@ -123,12 +199,7 @@ func _choice(title: String, selected: bool, group: ButtonGroup, parent: Node, ac
 	choice.custom_minimum_size = Vector2(0, 56)
 	choice.size_flags_horizontal = Control.SIZE_EXPAND_FILL
 	choice.mouse_default_cursor_shape = Control.CURSOR_POINTING_HAND
-	for state in ["normal", "hover", "pressed", "hover_pressed", "focus"]:
-		var style := Widgets.surface(Color("2b4b50") if state in ["pressed", "hover_pressed"] else Color("202a3d"), 12, 8)
-		if state != "normal":
-			style.set_border_width_all(2)
-			style.border_color = Color("6de3cf")
-		choice.add_theme_stylebox_override(state, style)
+	_style_control(choice)
 	choice.pressed.connect(action)
 	parent.add_child(choice)
 	return choice
@@ -139,6 +210,7 @@ func _build_screen(parent: VBoxContainer) -> void:
 	_build_screen_position(parent)
 
 func _build_screen_position(parent: VBoxContainer) -> void:
+	parent = _card(parent)
 	var header := HFlowContainer.new()
 	header.add_theme_constant_override("h_separation", 18)
 	header.add_theme_constant_override("v_separation", 12)
@@ -163,7 +235,7 @@ func _screen_position_hint() -> String:
 	return "Set the screen size, distance, height and curve."
 
 func _build_video_format(parent: VBoxContainer) -> void:
-	Widgets.label("Video format", parent, 26)
+	parent = _card(parent, "Picture format")
 	_hint("Jellyframe detects the 3D format. Choose a different format if the picture looks wrong.", parent)
 	stereo_choices = HFlowContainer.new()
 	stereo_choices.add_theme_constant_override("h_separation", 12)
@@ -171,18 +243,21 @@ func _build_video_format(parent: VBoxContainer) -> void:
 	var group := ButtonGroup.new()
 	for entry in [["2D", Stereo.Mode.MONO], ["Half-SBS", Stereo.Mode.HALF_SBS], ["Full-SBS", Stereo.Mode.FULL_SBS], ["Top-bottom", Stereo.Mode.TOP_BOTTOM]]:
 		_choice(entry[0], entry[1] == stereo_mode, group, stereo_choices, func(): stereo_mode = entry[1]; stereo_selected.emit(entry[1]))
-	var swap := CheckBox.new()
+	var swap := CheckButton.new()
 	swap.text = "Swap left and right eyes"
+	swap.accessibility_name = swap.text
+	_style_control(swap)
 	swap.custom_minimum_size.y = 56
 	swap.button_pressed = swap_eyes
 	swap.toggled.connect(func(enabled: bool): swap_eyes = enabled; eyes_swapped.emit())
 	parent.add_child(swap)
 
 func _build_projection(parent: VBoxContainer) -> void:
-	Widgets.label("Video projection", parent, 26)
+	parent = _card(parent, "Video projection")
 	_hint("180° fills the view in front of you. 360° surrounds you. Both use equirectangular video and hide the environment during playback. Fisheye and cubemap layouts are not supported.", parent)
-	var choices := HBoxContainer.new()
-	choices.add_theme_constant_override("separation", 12)
+	var choices := HFlowContainer.new()
+	choices.add_theme_constant_override("h_separation", 12)
+	choices.add_theme_constant_override("v_separation", 12)
 	parent.add_child(choices)
 	var group := ButtonGroup.new()
 	for entry in [["Screen", VideoProjection.Mode.SCREEN], ["180°", VideoProjection.Mode.EQUIRECTANGULAR_180], ["360°", VideoProjection.Mode.EQUIRECTANGULAR]]:
@@ -192,28 +267,46 @@ func _build_projection(parent: VBoxContainer) -> void:
 			_rebuild_screen.call_deferred())
 
 func _build_environment(parent: VBoxContainer) -> void:
-	Widgets.label("Environment", parent, 26)
-	_hint("Choose a background for your video screen.", parent)
-	var environments := GridContainer.new()
-	environments.columns = 2
-	environments.add_theme_constant_override("h_separation", 12)
-	environments.add_theme_constant_override("v_separation", 12)
-	parent.add_child(environments)
-	var environment_group := ButtonGroup.new()
-	for value in ["Void", "Cinema", "Theatre", "Passthrough"]:
-		var choice := _choice(value, value == settings.environment, environment_group, environments,
+	_hint("Choose a background for your screen.", parent)
+	environment_choices = VBoxContainer.new()
+	environment_choices.add_theme_constant_override("separation", 16)
+	parent.add_child(environment_choices)
+	var adjustable := _card(environment_choices, "Void & Passthrough")
+	var fixed := _card(environment_choices, "Cinema & Theatre")
+	var group := ButtonGroup.new()
+	var descriptions := [
+		"A dark background. Change the screen size and position in Screen settings.",
+		"See your room around the screen. Change its size and position in Screen settings." if passthrough_supported else "This device does not support passthrough.",
+		"A cinema with a fixed screen. Recenter to face it.",
+		"A simpler cinema with a fixed screen. Recenter to face it."
+	]
+	var values := ["Void", "Passthrough", "Cinema", "Theatre"]
+	for index in range(values.size()):
+		var value: String = values[index]
+		var card := adjustable if index < 2 else fixed
+		var choice := _choice(value, value == settings.environment, group, card,
 			func(): settings.environment = value; _rebuild_screen(); environment_changed.emit(); _save())
+		environment_buttons[value] = choice
+		_hint(descriptions[index], card)
 		if value == "Passthrough" and not passthrough_supported:
 			choice.disabled = true
-			choice.tooltip_text = "This device does not support passthrough."
-	Widgets.label("Void", parent, 24)
-	_hint("A dark background with an adjustable screen. Use the Screen page to change its size and position.", parent)
-	Widgets.label("Cinema", parent, 24)
-	_hint("A cinema with a fixed screen. Black bars keep the picture in proportion. Recenter to face the screen.", parent)
-	Widgets.label("Theatre", parent, 24)
-	_hint("The original simple cinema uses fewer polygons. It has its own fixed screen and supports recentering.", parent)
-	Widgets.label("Passthrough", parent, 24)
-	_hint("Your room surrounds an adjustable screen. Use the Screen page to change its size and position." if passthrough_supported else "This device does not support passthrough.", parent)
+			choice.tooltip_text = descriptions[index]
+	_build_follow_switch(adjustable)
+
+func _build_follow_switch(parent: VBoxContainer) -> void:
+	var toggle := CheckButton.new()
+	toggle.text = "Follow your movement"
+	toggle.accessibility_name = toggle.text
+	toggle.button_pressed = settings.follow_screen
+	toggle.custom_minimum_size.y = 56
+	_style_control(toggle)
+	parent.add_child(toggle)
+	follow_switch = toggle
+	toggle.toggled.connect(func(enabled: bool):
+		settings.follow_screen = enabled
+		screen_follow_changed.emit()
+		_save())
+	_hint("The screen follows you as you move or turn. Applies to both Void and Passthrough. Does not affect 180° or 360° video.", parent)
 
 func _reset_screen() -> void:
 	settings.reset_screen()
@@ -241,7 +334,7 @@ func _slider(entry: Array, parent: Node) -> void:
 	var name_label := Widgets.label(entry[0], labels, 22)
 	name_label.size_flags_horizontal = Control.SIZE_EXPAND_FILL
 	var value_label := Widgets.label("%.2f%s" % [settings.get(entry[1]), entry[4]], labels, 20)
-	var slider := HSlider.new()
+	var slider := preload("res://scripts/ui/screen_position_slider.gd").new()
 	slider.accessibility_name = entry[0]
 	slider.custom_minimum_size.y = 48
 	slider.min_value = entry[2]
@@ -262,7 +355,8 @@ func _save() -> void:
 	status.emit("Settings saved." if settings.save() == OK else "Could not save settings. Check available storage and try again.")
 
 func _adapt_columns() -> void:
+	var content_width := scroll.size.x - 40
 	if sort_choices != null:
-		sort_choices.columns = 3 if size.x >= 980 else (2 if size.x >= 650 else 1)
+		sort_choices.columns = 2 if content_width >= 540 else 1
 	if screen_dimensions != null:
-		screen_dimensions.columns = 2 if size.x >= 650 else 1
+		screen_dimensions.columns = 2 if content_width >= 540 else 1

scripts/ui/shell.gd

@@ -4,15 +4,20 @@ extends HBoxContainer
 signal navigate(id: String, title: String)
 signal screen_settings
 signal sign_out
+signal return_from_settings
 var page: VBoxContainer
 var status: Label
 var libraries: VBoxContainer
+var settings_navigation: VBoxContainer
+var navigation_heading: Label
 var home: Button
 var settings_button: Button
 var logout: Button
 var heading: Label
 var rail: PanelContainer
 var selected_id := ""
+var signed_in := false
+var settings_mode := false
 var buttons: Dictionary = {}
 var rail_background: StyleBoxFlat
 var main_background: StyleBoxFlat
@@ -41,17 +46,25 @@ func _ready() -> void:
 	logo.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
 	logo.mouse_filter = Control.MOUSE_FILTER_IGNORE
 	navigation.add_child(logo)
-	home = Widgets.button("Home", func(): navigate.emit("", "Home"), navigation)
+	home = Widgets.button("Home", _home_pressed, navigation)
 	_style_navigation_button(home, preload("res://assets/icons/material/home.svg"))
-	Widgets.label("LIBRARIES", navigation, 14).add_theme_color_override("font_color", Color("a4aec0"))
+	navigation_heading = Widgets.label("LIBRARIES", navigation, 14)
+	navigation_heading.add_theme_color_override("font_color", Color("a4aec0"))
 	var scroll := ScrollContainer.new()
 	scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL
 	scroll.horizontal_scroll_mode = ScrollContainer.SCROLL_MODE_DISABLED
+	scroll.follow_focus = true
 	navigation.add_child(scroll)
+	var lists := VBoxContainer.new()
+	lists.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+	scroll.add_child(lists)
 	libraries = VBoxContainer.new()
 	libraries.size_flags_horizontal = Control.SIZE_EXPAND_FILL
 	libraries.add_theme_constant_override("separation", 10)
-	scroll.add_child(libraries)
+	lists.add_child(libraries)
+	settings_navigation = VBoxContainer.new()
+	settings_navigation.hide()
+	lists.add_child(settings_navigation)
 	settings_button = Widgets.button("Settings", func(): screen_settings.emit(), navigation)
 	_style_navigation_button(settings_button, preload("res://assets/icons/material/settings.svg"))
 	logout = Widgets.button("Sign out", func(): sign_out.emit(), navigation)
@@ -75,14 +88,37 @@ func _ready() -> void:
 	set_signed_in(false)
 
 func set_signed_in(value: bool) -> void:
+	set_settings_mode(false)
+	signed_in = value
 	rail.visible = value
 	home.disabled = not value
+	settings_button.disabled = not value
 	logout.visible = value
 	if not value:
 		heading.text = ""
 		clear_libraries()
 		Widgets.label("Sign in to browse", libraries, 17)
 
+func set_settings_mode(enabled: bool) -> void:
+	settings_mode = enabled
+	home.text = "Library" if enabled else "Home"
+	home.icon = preload("res://assets/icons/material/video_library.svg") if enabled else preload("res://assets/icons/material/home.svg")
+	libraries.visible = not enabled
+	settings_navigation.visible = enabled
+	navigation_heading.text = "SETTINGS" if enabled else "LIBRARIES"
+	settings_button.visible = not enabled
+	logout.visible = signed_in and not enabled
+	if not enabled:
+		for child in settings_navigation.get_children():
+			settings_navigation.remove_child(child)
+			child.queue_free()
+
+func _home_pressed() -> void:
+	if settings_mode:
+		return_from_settings.emit()
+	else:
+		navigate.emit("", "Home")
+
 func clear_libraries() -> void:
 	buttons.clear()
 	for child in libraries.get_children():
@@ -93,7 +129,7 @@ func set_libraries(items: Array) -> void:
 	clear_libraries()
 	for item in items:
 		var library_type := str(item.get("CollectionType") if item.get("CollectionType") != null else "").to_lower()
-		if library_type not in ["", "mixed", "movies", "tvshows", "homevideos"]: continue
+		if library_type not in ["", "mixed", "movies", "tvshows", "homevideos", "photos"]: continue
 		var id := str(item.get("Id", ""))
 		var title := str(item.get("Name", "Library"))
 		var button := Widgets.button(title, func(): navigate.emit(id, title), libraries)

scripts/ui/widgets.gd

@@ -26,6 +26,22 @@ static func input(placeholder: String, parent: Node, secret: bool = false) -> Li
 	parent.add_child(result)
 	return result
 
+static func watched_badge(image_frame: PanelContainer) -> void:
+	var overlay := Control.new()
+	overlay.mouse_filter = Control.MOUSE_FILTER_IGNORE
+	image_frame.add_child(overlay)
+	var badge := TextureRect.new()
+	badge.texture = preload("res://assets/icons/watched.svg")
+	badge.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
+	badge.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
+	badge.mouse_filter = Control.MOUSE_FILTER_IGNORE
+	overlay.add_child(badge)
+	badge.set_anchors_and_offsets_preset(Control.PRESET_TOP_RIGHT)
+	badge.offset_left = -36
+	badge.offset_top = 8
+	badge.offset_right = -8
+	badge.offset_bottom = 36
+
 static func theme() -> Theme:
 	var result := Theme.new()
 	result.default_font_size = 22

scripts/vr/overlay_material.gd

@@ -0,0 +1,10 @@
+class_name VrOverlayMaterial
+extends RefCounted
+
+const DEPTH_SCALE := 0.01
+
+static func apply_depth(material: BaseMaterial3D) -> void:
+	# Menus and controllers share a depth range in front of the room.
+	material.use_z_clip_scale = true
+	material.z_clip_scale = DEPTH_SCALE
+	material.no_depth_test = false

scripts/vr/overlay_material.gd.uid

@@ -0,0 +1 @@
+uid://bf207wru26usd

scripts/vr/pointer.gd

@@ -44,13 +44,22 @@ func set_target(target: Node3D, target_viewport: SubViewport, target_size: Vecto
 		input.viewport = viewport
 	panel_size = target_size
 
+func points_at(target: Node3D, target_size: Vector2) -> bool:
+	var inverse := target.global_transform.affine_inverse()
+	var origin := inverse * global_position
+	var direction := inverse.basis * -global_basis.z
+	if absf(direction.z) <= 0.00001: return false
+	var distance := -origin.z / direction.z
+	var hit := origin + direction * distance
+	return distance > 0 and absf(hit.x) < target_size.x / 2 and absf(hit.y) < target_size.y / 2
+
 func _process(delta: float) -> void:
 	input.sample_trigger(get_float("trigger"))
 	if input.just_pressed and get_is_active():
 		if is_instance_valid(active_pointer) and active_pointer != self:
 			active_pointer._cancel()
 		active_pointer = self
-	if (is_instance_valid(active_pointer) and active_pointer != self) or not get_is_active() or not panel.is_visible_in_tree():
+	if not is_visible_in_tree() or (is_instance_valid(active_pointer) and active_pointer != self) or not get_is_active() or not panel.is_visible_in_tree():
 		_cancel()
 		return
 	var inverse := panel.global_transform.affine_inverse()

scripts/vr/pointer_input.gd

@@ -22,9 +22,6 @@ func aim(point: Vector2, inside: bool) -> void:
 		viewport.notify_mouse_entered()
 	_move(point)
 	if just_pressed:
-		if OS.is_debug_build() and OS.get_name() == "Android":
-			var hovered := viewport.gui_get_hovered_control()
-			print("Jellyframe input: press at ", point.round(), " target=", hovered.get_class() if hovered else "none")
 		mouse_down = true
 		_button(true)
 	elif mouse_down and not trigger_down:
@@ -32,11 +29,11 @@ func aim(point: Vector2, inside: bool) -> void:
 		_button(false)
 
 func scroll(point: Vector2, amount: float, horizontal: bool = false) -> void:
-	var wheel := InputEventMouseButton.new()
 	if horizontal:
-		wheel.button_index = MOUSE_BUTTON_WHEEL_RIGHT if amount > 0 else MOUSE_BUTTON_WHEEL_LEFT
-	else:
-		wheel.button_index = MOUSE_BUTTON_WHEEL_UP if amount > 0 else MOUSE_BUTTON_WHEEL_DOWN
+		_scroll_horizontal(amount)
+		return
+	var wheel := InputEventMouseButton.new()
+	wheel.button_index = MOUSE_BUTTON_WHEEL_UP if amount > 0 else MOUSE_BUTTON_WHEEL_DOWN
 	wheel.pressed = true
 	wheel.position = point
 	wheel.global_position = point
@@ -46,6 +43,20 @@ func scroll(point: Vector2, amount: float, horizontal: bool = false) -> void:
 	release.pressed = false
 	viewport.push_input(release, true)
 
+func _scroll_horizontal(amount: float) -> void:
+	var target: Node = viewport.gui_get_hovered_control()
+	while target != null:
+		if target.has_method("adjust_horizontal"):
+			target.adjust_horizontal(amount)
+			return
+		if target is ScrollContainer and target.horizontal_scroll_mode != ScrollContainer.SCROLL_MODE_DISABLED:
+			target.scroll_horizontal += int(signf(amount) * maxf(1.0, absf(amount) * 80.0))
+			return
+		if target is CastCarousel:
+			target.scroll.scroll_horizontal += int(signf(amount) * maxf(1.0, absf(amount) * 80.0))
+			return
+		target = target.get_parent()
+
 func cancel() -> void:
 	if previous != Vector2(-1, -1): _move(Vector2(-1, -1))
 	if mouse_down:

scripts/vr/world.gd

@@ -2,6 +2,8 @@ class_name ViewingWorld
 extends Node3D
 
 signal menu_requested
+signal settings_requested
+signal library_requested
 var settings: JellyframeSettings
 var camera: Camera3D
 var viewport: SubViewport
@@ -15,7 +17,10 @@ var theatre: TheatreEnvironment
 var passthrough := PassthroughEnvironment.new()
 var player_overlay: PlayerOverlay
 var player_loading: PlayerLoading
+var player_skip_popup: PlayerSkipPopup
+var skip_screen_size := Vector3(4.0, 16.0 / 9.0, 0.0)
 var pointers: Array[LaserPointer] = []
+var controller_models: OpenXRRenderModelManager
 
 func setup() -> void:
 	var xr := XRServer.find_interface("OpenXR")
@@ -53,8 +58,8 @@ func setup() -> void:
 	ui_material.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
 	ui_material.albedo_texture = viewport.get_texture()
 	ui_material.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
-	ui_material.no_depth_test = true
 	ui_material.render_priority = 100
+	VrOverlayMaterial.apply_depth(ui_material)
 	panel.material_override = ui_material
 	add_child(panel)
 	screen = MeshInstance3D.new()
@@ -72,16 +77,20 @@ func setup() -> void:
 	screen.add_child(player_overlay)
 	player_loading = PlayerLoading.new()
 	screen.add_child(player_loading)
+	player_skip_popup = PlayerSkipPopup.new()
+	screen.add_child(player_skip_popup)
 	_build_theatre()
 	if immersive:
+		controller_models = OpenXRRenderModelManager.new()
+		controller_models.render_model_added.connect(_prepare_controller_model)
+		origin.add_child(controller_models)
 		for hand in ["left_hand", "right_hand"]:
 			var pointer := LaserPointer.new()
 			pointer.tracker = hand
 			pointer.pose = "aim"
 			pointer.panel = panel
 			pointer.viewport = viewport
-			pointer.button_pressed.connect(func(action: String):
-				if action in ["menu_button", "ax_button", "by_button"]: menu_requested.emit())
+			pointer.button_pressed.connect(_controller_button_pressed.bind(pointer.tracker))
 			origin.add_child(pointer)
 			pointers.append(pointer)
 	else:
@@ -94,6 +103,15 @@ func setup() -> void:
 		overlay.add_child(container)
 		viewport.reparent(container)
 
+func _controller_button_pressed(action: String, hand: StringName) -> void:
+	if action == "menu_button" and hand == &"left_hand": return
+	if action == "by_button" and hand == &"left_hand":
+		settings_requested.emit()
+	elif action == "by_button" and hand == &"right_hand":
+		library_requested.emit()
+	elif action in ["menu_button", "ax_button", "by_button"]:
+		menu_requested.emit()
+
 func _process(_delta: float) -> void:
 	if not player_overlay: return
 	var show_panorama := panoramic and screen.visible
@@ -101,14 +119,41 @@ func _process(_delta: float) -> void:
 		panorama.visible = show_panorama
 		apply_environment()
 	if show_panorama: panorama.global_position = camera.global_position
+	var loading_menu_visible := player_loading.is_visible_in_tree() and player_loading.cancel_button.visible
+	_update_skip_popup()
+	var menu_visible := panel.is_visible_in_tree() or player_overlay.is_visible_in_tree() or loading_menu_visible or player_skip_popup.is_visible_in_tree()
+	var controllers_visible := not screen.visible or menu_visible
+	if controller_models != null:
+		controller_models.visible = controllers_visible
 	for pointer in pointers:
+		pointer.visible = controllers_visible
 		if player_loading.is_visible_in_tree() and player_loading.cancel_button.visible:
 			pointer.set_target(player_loading, player_loading.viewport, player_loading.panel_size)
+		elif player_skip_popup.is_visible_in_tree() and (not player_overlay.is_visible_in_tree() or pointer.points_at(player_skip_popup, player_skip_popup.panel_size)):
+			pointer.set_target(player_skip_popup, player_skip_popup.viewport, player_skip_popup.panel_size)
 		elif player_overlay.is_visible_in_tree():
 			pointer.set_target(player_overlay, player_overlay.viewport, player_overlay.panel_size)
 		else:
 			pointer.set_target(panel, viewport, Vector2(4.4, 2.75))
 
+func _update_skip_popup() -> void:
+	player_skip_popup.visible = player_skip_popup.available and not panel.is_visible_in_tree() and not player_loading.is_visible_in_tree()
+	if not player_skip_popup.is_visible_in_tree(): return
+	var controls_height := player_overlay.panel_size.y if player_overlay.is_visible_in_tree() else 0.0
+	player_skip_popup.fit_screen(skip_screen_size.x, skip_screen_size.y, skip_screen_size.z, controls_height)
+
+func _prepare_controller_model(node: Node) -> void:
+	if node is MeshInstance3D and node.mesh != null:
+		for surface in range(node.mesh.get_surface_count()):
+			var source := node.get_active_material(surface) as BaseMaterial3D
+			if source == null: continue
+			var unshaded := source.duplicate() as BaseMaterial3D
+			unshaded.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+			VrOverlayMaterial.apply_depth(unshaded)
+			node.set_surface_override_material(surface, unshaded)
+	for child in node.get_children():
+		_prepare_controller_model(child)
+
 func _build_theatre() -> void:
 	theatre = TheatreEnvironment.new()
 	add_child(theatre)
@@ -130,7 +175,6 @@ func set_panoramic(enabled: bool, horizontal_angle: float = TAU) -> void:
 	panorama.visible = enabled and screen.visible
 	if enabled:
 		panorama.global_position = camera.global_position
-		panorama.global_rotation = Vector3(0.0, camera.global_rotation.y, 0.0)
 	apply_environment()
 
 func _exit_tree() -> void:

shaders/pc_video.gdshader

@@ -1,21 +1,29 @@
 shader_type spatial;
 render_mode unshaded, cull_disabled;
 
-uniform sampler2D video_texture : source_color, filter_linear;
+uniform sampler2D video_texture : source_color, filter_linear, hint_default_black;
 uniform bool stereo = false;
 uniform bool top_bottom = false;
 uniform bool swap_eyes = false;
 
+#include "pc_video_yuv.gdshaderinc"
+
 void fragment() {
 	vec2 coordinate = UV;
+	vec2 eye_min = vec2(0.0);
+	vec2 eye_max = vec2(1.0);
 	if (stereo) {
 		int eye = int(VIEW_INDEX);
 		if (swap_eyes) { eye = 1 - eye; }
 		if (top_bottom) {
 			coordinate.y = coordinate.y * 0.5 + float(eye) * 0.5;
+			eye_min.y = float(eye) * 0.5;
+			eye_max.y = eye_min.y + 0.5;
 		} else {
 			coordinate.x = coordinate.x * 0.5 + float(eye) * 0.5;
+			eye_min.x = float(eye) * 0.5;
+			eye_max.x = eye_min.x + 0.5;
 		}
 	}
-	ALBEDO = texture(video_texture, coordinate).rgb;
+	ALBEDO = direct_yuv ? sample_video_yuv(coordinate, eye_min, eye_max) : texture(video_texture, coordinate).rgb;
 }

shaders/pc_video_yuv.gdshaderinc

@@ -0,0 +1,80 @@
+uniform bool direct_yuv = false;
+uniform sampler2D y_plane : filter_linear, repeat_disable;
+uniform sampler2D u_plane : filter_linear, repeat_disable;
+uniform sampler2D v_plane : filter_linear, repeat_disable;
+uniform vec2 source_size = vec2(1.0);
+uniform int video_rotation = 0;
+uniform bool interleaved_chroma = false;
+uniform bool chroma_in_alpha = false;
+uniform vec2 color_coefficients = vec2(0.2126, 0.0722);
+uniform float full_range = 0.0;
+uniform float transfer = 0.0;
+uniform float sample_scale = 1020.0;
+uniform float code_max = 1020.0;
+uniform float source_peak = 4.926108;
+
+float hable(float value) {
+    return ((value * (0.15 * value + 0.05) + 0.004) /
+        (value * (0.15 * value + 0.5) + 0.06)) - (0.02 / 0.3);
+}
+
+vec3 hdr_to_sdr(vec3 rgb) {
+    rgb = clamp(rgb, 0.0, 1.0);
+    if (transfer == 1.0) {
+        vec3 p = pow(rgb, vec3(1.0 / 78.84375));
+        rgb = pow(max(p - 0.8359375, 0.0) / max(18.8515625 - 18.6875 * p, 0.000001), vec3(1.0 / 0.1593017578125)) * (10000.0 / 203.0);
+    } else {
+        rgb = mix(rgb * rgb / 3.0, (exp((rgb - 0.55991073) / 0.17883277) + 0.28466892) / 12.0, greaterThan(rgb, vec3(0.5)));
+        float scene_luminance = dot(rgb, vec3(0.2627, 0.6780, 0.0593));
+        rgb *= pow(max(scene_luminance, 0.0), 0.2) * (1000.0 / 203.0);
+    }
+    if (color_coefficients.x > 0.26) {
+        rgb = mat3(vec3(1.6605, -0.1246, -0.0182), vec3(-0.5876, 1.1329, -0.1006), vec3(-0.0728, -0.0083, 1.1187)) * rgb;
+    }
+    rgb = max(rgb, vec3(0.0));
+    float signal = max(max(rgb.r, rgb.g), rgb.b);
+    float mapped = hable(signal) / max(hable(source_peak), 0.000001);
+    rgb *= mapped / max(signal, 0.000001);
+    return clamp(rgb, vec3(0.0), vec3(1.0));
+}
+
+vec2 rotate_video_uv(vec2 uv) {
+    if (video_rotation == 1) uv = vec2(uv.y, 1.0 - uv.x);
+    else if (video_rotation == 2) uv = 1.0 - uv;
+    else if (video_rotation == 3) uv = vec2(1.0 - uv.y, uv.x);
+    return uv;
+}
+
+vec3 sample_video_yuv(vec2 uv, vec2 eye_min, vec2 eye_max) {
+    vec2 first = rotate_video_uv(eye_min) * source_size;
+    vec2 last = rotate_video_uv(eye_max) * source_size;
+    vec2 lower = min(first, last);
+    vec2 upper = max(first, last);
+    vec2 pixel = rotate_video_uv(uv) * source_size;
+    vec2 y_uv = clamp(pixel, lower + 0.5, upper - 0.5) / vec2(textureSize(y_plane, 0));
+    // Keep filtering inside the selected eye and outside decoder padding.
+    vec2 chroma_uv = clamp(pixel * 0.5, ceil(lower * 0.5) + 0.5, ceil(upper * 0.5) - 0.5) / vec2(textureSize(u_plane, 0));
+    float y = texture(y_plane, y_uv).r * sample_scale;
+    vec4 chroma = texture(u_plane, chroma_uv);
+    float u = chroma.r * sample_scale - 512.0;
+    // Texture2DRD exposes R8G8 as luminance-alpha; R16G16 keeps red-green.
+    float v_sample = interleaved_chroma ? (chroma_in_alpha ? chroma.a : chroma.g) : texture(v_plane, chroma_uv).r;
+    float v = v_sample * sample_scale - 512.0;
+    if (full_range > 0.5) { y /= code_max; u /= code_max; v /= code_max; }
+    else { y = (y - 64.0) / 876.0; u /= 896.0; v /= 896.0; }
+    float kr = color_coefficients.x;
+    float kb = color_coefficients.y;
+    float kg = 1.0 - kr - kb;
+    vec3 rgb = vec3(y + 2.0 * (1.0 - kr) * v,
+        y - 2.0 * kb * (1.0 - kb) / kg * u - 2.0 * kr * (1.0 - kr) / kg * v,
+        y + 2.0 * (1.0 - kb) * u);
+    if (transfer > 0.0) {
+        rgb = hdr_to_sdr(rgb);
+        if (OUTPUT_IS_SRGB) rgb = mix(rgb * 12.92, 1.055 * pow(rgb, vec3(1.0 / 2.4)) - 0.055, greaterThan(rgb, vec3(0.0031308)));
+        return rgb;
+    }
+    rgb = clamp(rgb, vec3(0.0), vec3(1.0));
+    // Spatial materials expect linear RGB on the Mobile and Forward+ renderers.
+    if (!OUTPUT_IS_SRGB) rgb = mix(rgb / 12.92, pow((rgb + 0.055) / 1.055, vec3(2.4)), greaterThan(rgb, vec3(0.04045)));
+    return rgb;
+}

shaders/pc_video_yuv.gdshaderinc.uid

@@ -0,0 +1 @@
+uid://dg7chfym1ebt2

shaders/video.gdshader

@@ -2,6 +2,7 @@ shader_type spatial;
 render_mode unshaded, cull_disabled;
 
 uniform samplerExternalOES video_texture : source_color, filter_linear;
+uniform bool video_ready = false;
 uniform bool stereo = false;
 uniform bool top_bottom = false;
 uniform bool swap_eyes = false;
@@ -20,5 +21,5 @@ void fragment() {
 	}
 	coordinate.y = 1.0 - coordinate.y;
 	coordinate = (texture_transform * vec4(coordinate, 0.0, 1.0)).xy;
-	ALBEDO = texture(video_texture, coordinate).rgb;
+	ALBEDO = video_ready ? texture(video_texture, coordinate).rgb : vec3(0.0);
 }

tests/capture_360.gd

@@ -44,6 +44,8 @@ func capture() -> void:
 		quit(1)
 		return
 	if not await check_180_rendering(app, grid_texture): return
+	app.api.token = "fixture"
+	app.shell.set_signed_in(true)
 	app._screen_settings()
 	app.viewport.get_parent().show()
 	var settings: SettingsView = app.page.get_child(0)

tests/capture_menu_depth.gd

@@ -19,6 +19,8 @@ func capture() -> void:
 	material.cull_mode = BaseMaterial3D.CULL_DISABLED
 	material.albedo_color = Color("876143")
 	app.screen.material_override = material
+	app.api.token = "fixture"
+	app.shell.set_signed_in(true)
 	app._screen_settings()
 	app.panel.show()
 	await create_timer(0.5).timeout

tests/pc_video_test_screen.gd

@@ -0,0 +1,29 @@
+extends SubViewport
+
+var backend := PcVideo.new()
+var material := ShaderMaterial.new()
+
+func _init(decoder: Node, dimensions := Vector2i(640, 360)) -> void:
+	size = dimensions
+	own_world_3d = true
+	render_target_update_mode = SubViewport.UPDATE_ALWAYS
+	var camera := Camera3D.new()
+	camera.projection = Camera3D.PROJECTION_ORTHOGONAL
+	camera.size = 2.0
+	camera.position.z = 1.0
+	camera.current = true
+	add_child(camera)
+	var mesh := MeshInstance3D.new()
+	var quad := QuadMesh.new()
+	quad.size = Vector2(2.0 * dimensions.x / dimensions.y, 2.0)
+	mesh.mesh = quad
+	material.shader = load("res://shaders/pc_video.gdshader")
+	mesh.material_override = material
+	add_child(mesh)
+	backend.material = material
+	backend.bridge = decoder
+	add_child(backend)
+	decoder.texture_changed.connect(backend._set_texture)
+
+func image() -> Image:
+	return get_texture().get_image()

tests/pc_video_test_screen.gd.uid

@@ -0,0 +1 @@
+uid://ty8d8u06c5qk

tests/test_360_video.gd

@@ -46,6 +46,8 @@ func run_checks() -> void:
 	var app: Node = load("res://scenes/main.tscn").instantiate()
 	root.add_child(app)
 	app.set_process(false)
+	app.api.token = "fixture"
+	app.shell.set_signed_in(true)
 	app.video.queue_free()
 	var video := FixtureVideo.new()
 	app.add_child(video)

tests/test_android_video_transitions.gd

@@ -0,0 +1,104 @@
+extends SceneTree
+
+class PreviewVideo extends AndroidVideo:
+	func _ready() -> void:
+		pass
+
+class FixtureBridge extends RefCounted:
+	var ready := true
+	var opened: Array[String] = []
+
+	func open_video(_texture_id: int, url: String, _authorization: String, _start_ms: int) -> void:
+		opened.append(url)
+		ready = false
+
+	func stop_video() -> void:
+		pass
+
+	func has_video_frame() -> bool:
+		return ready
+
+	func texture_transform() -> PackedFloat32Array:
+		return PackedFloat32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1])
+
+var video: AndroidVideo
+var bridge: FixtureBridge
+var material: ShaderMaterial
+var old_frame: ImageTexture
+var screen: SubViewport
+
+func _initialize() -> void:
+	call_deferred("run_check")
+
+func require(condition: bool, message: String) -> bool:
+	if condition: return true
+	push_error(message)
+	quit(1)
+	return false
+
+func make_screen() -> void:
+	screen = SubViewport.new()
+	screen.size = Vector2i(64, 64)
+	screen.own_world_3d = true
+	screen.render_target_update_mode = SubViewport.UPDATE_ALWAYS
+	root.add_child(screen)
+	var camera := Camera3D.new()
+	camera.projection = Camera3D.PROJECTION_ORTHOGONAL
+	camera.size = 2.0
+	camera.position.z = 1.0
+	screen.add_child(camera)
+	var mesh := MeshInstance3D.new()
+	var quad := QuadMesh.new()
+	quad.size = Vector2(2.0, 2.0)
+	mesh.mesh = quad
+	var shader := Shader.new()
+	shader.code = FileAccess.get_file_as_string("res://shaders/video.gdshader").replace("samplerExternalOES", "sampler2D")
+	material = ShaderMaterial.new()
+	material.shader = shader
+	mesh.material_override = material
+	screen.add_child(mesh)
+	var image := Image.create(2, 2, false, Image.FORMAT_RGBA8)
+	image.fill(Color.RED)
+	old_frame = ImageTexture.create_from_image(image)
+	material.set_shader_parameter("video_texture", old_frame)
+
+func brightness() -> float:
+	await process_frame
+	await RenderingServer.frame_post_draw
+	return screen.get_texture().get_image().get_pixel(32, 32).get_luminance()
+
+func run_check() -> void:
+	if not require(DisplayServer.get_name() != "headless", "Android transition rendering needs a graphics context"): return
+	make_screen()
+	video = PreviewVideo.new()
+	bridge = FixtureBridge.new()
+	video.bridge = bridge
+	video.texture = ExternalTexture.new()
+	video.material = material
+	root.add_child(video)
+	if not require(await brightness() < 0.001, "An old texture is black before a video opens"): return
+	for url in ["first", "second"]:
+		await video.open(url, "", 0)
+		material.set_shader_parameter("video_texture", old_frame)
+		if not require(await brightness() < 0.001, "The old picture stays hidden while the new video prepares"): return
+		bridge.ready = true
+		if not require(await brightness() > 0.1, "A latched first frame makes the video visible"): return
+		video.stop()
+		if not require(await brightness() < 0.001, "Stopping hides the frame before the asynchronous decoder releases it"): return
+	var calls_before := bridge.opened.size()
+	video.open("cancelled", "", 0)
+	video.stop()
+	await RenderingServer.frame_post_draw
+	await process_frame
+	if not require(bridge.opened.size() == calls_before, "Stopping cancels an open waiting for the render frame"): return
+	video.open("outdated", "", 0)
+	video.open("latest", "", 0)
+	await RenderingServer.frame_post_draw
+	await process_frame
+	if not require(bridge.opened.size() == calls_before + 1 and bridge.opened.back() == "latest", "Rapid switching opens only the latest requested video"): return
+	video.stop()
+	video.queue_free()
+	screen.queue_free()
+	await process_frame
+	print("Android black startup, stop, switching, and cancelled-open checks: PASS")
+	quit()

tests/test_android_video_transitions.gd.uid

@@ -0,0 +1 @@
+uid://bomic4vkguxvw

tests/test_autoplay.gd

@@ -78,6 +78,7 @@ func run_checks() -> void:
 	app.add_child(video)
 	app.add_child(session)
 	app.api = api
+	app.shell.set_signed_in(true)
 	app.video = video
 	app.session = session
 	video.ended.connect(app._ended)

tests/test_controller_depth.gd

@@ -0,0 +1,70 @@
+extends SceneTree
+
+var failures := 0
+
+func _initialize() -> void:
+	call_deferred("run_checks")
+
+func run_checks() -> void:
+	if DisplayServer.get_name() == "headless":
+		push_error("Controller depth checks require a rendering window.")
+		quit(1)
+		return
+	var app: Node = load("res://scenes/main.tscn").instantiate()
+	root.add_child(app)
+	app.set_process(false)
+	var view := SubViewport.new()
+	view.size = Vector2i(64, 64)
+	view.own_world_3d = true
+	view.render_target_update_mode = SubViewport.UPDATE_ALWAYS
+	root.add_child(view)
+	view.add_child(Camera3D.new())
+	var room := MeshInstance3D.new()
+	room.mesh = QuadMesh.new()
+	room.position.z = -0.4
+	var blue := StandardMaterial3D.new()
+	blue.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+	blue.albedo_color = Color.BLUE
+	room.material_override = blue
+	view.add_child(room)
+	var panel := MeshInstance3D.new()
+	panel.mesh = QuadMesh.new()
+	panel.position.z = -2.0
+	view.add_child(panel)
+	var controller := MeshInstance3D.new()
+	controller.mesh = BoxMesh.new()
+	controller.scale = Vector3.ONE * 0.2
+	var red := StandardMaterial3D.new()
+	red.albedo_color = Color.RED
+	controller.mesh.material = red
+	app.world._prepare_controller_model(controller)
+	view.add_child(controller)
+	var panels := [app.world.panel, app.world.player_loading, app.player_overlay]
+	for source in panels:
+		var material: StandardMaterial3D = source.material_override.duplicate()
+		material.albedo_texture = null
+		material.albedo_color = Color.GREEN
+		panel.material_override = material
+		for room_visible in [false, true]:
+			room.visible = room_visible
+			for depth in [-1.0, -3.0]:
+				controller.position.z = depth
+				await process_frame
+				await RenderingServer.frame_post_draw
+				var pixels := view.get_texture().get_image()
+				var center := pixels.get_pixel(32, 32)
+				var expected := Color.RED if depth == -1.0 else Color.GREEN
+				check(center.is_equal_approx(expected), "Controller depth is preserved with room visibility %s at %s: %s" % [room_visible, depth, center])
+				check(pixels.get_pixel(23, 32).is_equal_approx(Color.GREEN), "The menu draws over closer room geometry")
+				if room_visible:
+					check(pixels.get_pixel(1, 1).is_equal_approx(Color.BLUE), "Room geometry outside the menu remains visible")
+	app.queue_free()
+	view.queue_free()
+	await process_frame
+	print("Rendered controller depth checks: ", "PASS" if failures == 0 else str(failures) + " failures")
+	quit(1 if failures else 0)
+
+func check(condition: bool, message: String) -> void:
+	if not condition:
+		failures += 1
+		push_error(message)

tests/test_controller_depth.gd.uid

@@ -0,0 +1 @@
+uid://cn6nx2tgy8qbx

tests/test_controller_visibility.gd

@@ -0,0 +1,78 @@
+extends SceneTree
+
+func _initialize() -> void:
+	call_deferred("run_checks")
+
+func run_checks() -> void:
+	var app: Node = load("res://scenes/main.tscn").instantiate()
+	root.add_child(app)
+	app.set_process(false)
+	app.api.token = "fixture"
+	app.shell.set_signed_in(true)
+	var world: ViewingWorld = app.world
+	check_controller_materials(world)
+	var origin := world.camera.get_parent()
+	var pointer := LaserPointer.new()
+	pointer.panel = world.panel
+	pointer.viewport = world.viewport
+	origin.add_child(pointer)
+	world.pointers.append(pointer)
+	assert(ProjectSettings.get_setting("xr/openxr/extensions/render_model"), "OpenXR render models are enabled")
+	world._process(0.0)
+	assert(pointer.visible, "Controllers are visible in the library")
+	app.playing = true
+	app.screen.show()
+	app._show_playback()
+	app._video_prepared()
+	app._player_action("hide")
+	world._process(0.0)
+	assert(not pointer.visible, "Video without menus hides the laser pointer")
+	assert(pointer.is_processing(), "Hidden controllers keep processing input")
+	app._show_playback()
+	world._process(0.0)
+	assert(pointer.visible, "Opening playback controls restores controllers")
+	app._screen_settings()
+	world.panel.show()
+	world._process(0.0)
+	assert(pointer.visible, "Settings keep controllers visible during playback")
+	app._show_playback()
+	app._player_action("hide")
+	world.player_loading.show_buffering()
+	world._process(0.0)
+	assert(not pointer.visible, "Buffering without buttons keeps controllers hidden")
+	world.player_loading.show_countdown("Next episode", 5)
+	world._process(0.0)
+	assert(pointer.visible, "Autoplay cancellation keeps controllers visible")
+	world.player_loading.hide()
+	world.set_panoramic(true)
+	world._process(0.0)
+	assert(not pointer.visible, "Panoramic playback also hides controllers")
+	app.playing = false
+	app.screen.hide()
+	world._process(0.0)
+	assert(pointer.visible, "Stopping playback restores controllers")
+	app.queue_free()
+	await process_frame
+	print("Controller visibility checks: PASS")
+	quit()
+
+func check_controller_materials(world: ViewingWorld) -> void:
+	var model := Node3D.new()
+	var component := Node3D.new()
+	model.add_child(component)
+	var mesh := MeshInstance3D.new()
+	mesh.mesh = BoxMesh.new()
+	var source := StandardMaterial3D.new()
+	source.albedo_color = Color("b7c4d6")
+	source.albedo_texture = GradientTexture2D.new()
+	source.metallic = 0.5
+	mesh.mesh.material = source
+	component.add_child(mesh)
+	world._prepare_controller_model(model)
+	var result := mesh.get_active_material(0) as BaseMaterial3D
+	assert(result.shading_mode == BaseMaterial3D.SHADING_MODE_UNSHADED, "Nested controller meshes do not require scene lighting")
+	assert(result.albedo_color == source.albedo_color and result.albedo_texture == source.albedo_texture, "Controller colors and textures are preserved")
+	assert(result.metallic == source.metallic, "Other controller material properties are preserved")
+	assert(result.use_z_clip_scale and is_equal_approx(result.z_clip_scale, VrOverlayMaterial.DEPTH_SCALE), "Controllers share the menu depth range")
+	assert(source.shading_mode == BaseMaterial3D.SHADING_MODE_PER_PIXEL, "Shared source materials remain unchanged")
+	model.free()

tests/test_controller_visibility.gd.uid

@@ -0,0 +1 @@
+uid://lndphkh6u8to

tests/test_details.gd

@@ -6,6 +6,7 @@ class FixtureApi extends JellyfinClient:
 
 var failures := 0
 var selected: Array = []
+var restarted: Array = []
 var back_count := 0
 
 func _initialize() -> void:
@@ -42,6 +43,7 @@ func show_details(shell: UiShell, item: Dictionary) -> DetailsView:
 	view.item = item
 	view.size_flags_vertical = Control.SIZE_EXPAND_FILL
 	view.play_requested.connect(func(chosen: Dictionary): selected.append(chosen))
+	view.play_from_start_requested.connect(func(chosen: Dictionary): restarted.append(chosen))
 	view.back_requested.connect(func(): back_count += 1)
 	shell.page.add_child(view)
 	return view
@@ -60,6 +62,10 @@ func run_checks() -> void:
 	check(view.play_button.text == "Resume", "Saved playback must offer Resume.")
 	view.play_button.pressed.emit()
 	check(selected == [item], "Resume must pass the original item to playback.")
+	check(view.play_from_start_button != null and view.play_from_start_button.text == "Play from start", "Saved playback also offers Play from start.")
+	view.play_from_start_button.pressed.emit()
+	check(restarted == [item] and selected == [item], "Play from start emits a separate playback request.")
+	check(item.UserData.PlaybackPositionTicks == 7200000000, "The details page keeps the original saved progress.")
 	view.back_button.pressed.emit()
 	check(back_count == 1, "Back must return to the library.")
 	check(DetailsMetadata.facts(item).has("2h 09m"), "Runtime must use readable hours and minutes.")
@@ -77,14 +83,17 @@ func run_checks() -> void:
 		await settle()
 		check(view.body.size.x <= view.scroll.size.x, "Details must fit the available width at %d pixels." % width)
 		check(view.title_label.get_global_rect().end.x <= view.scroll.get_global_rect().end.x, "Long titles must not escape the details panel.")
+		check(view.play_from_start_button.get_global_rect().end.x <= view.scroll.get_global_rect().end.x, "The restart button fits narrow details panels.")
 	root.size.x = 1536
 	view = show_details(shell, {"Id": "plain", "Name": "A movie without artwork", "Type": "Movie", "Overview": null, "UserData": null, "Genres": null, "People": null})
 	await settle()
 	check(view.play_button.text == "Play movie", "Unstarted movies must offer Play movie.")
+	check(view.play_from_start_button == null, "Titles without progress do not need a restart button.")
 	check(view.overview_label.text == "No description available.", "Missing metadata must have a readable fallback.")
 	view = show_details(shell, {"Id": "series", "Name": "Example series", "Type": "Series"})
 	await settle()
 	check(view.play_button == null, "Series must select episodes instead of playing the series itself.")
+	check(view.play_from_start_button == null, "Series headers do not offer title playback actions.")
 	check(view.series_browser != null, "Series must show a season browser.")
 	check(view.series_browser.season_grid.get_child(0).text == "No seasons available.", "An empty series must have a readable fallback.")
 	print("Details checks: ", "PASS" if failures == 0 else str(failures) + " failures")

tests/test_export_renderer.gd

@@ -1,21 +1,26 @@
 extends SceneTree
 
 func _initialize() -> void:
-	var arguments := OS.get_cmdline_user_args()
-	if arguments.size() != 1 or arguments[0] not in ["opengl", "vulkan"]:
-		push_error("Specify the expected exported renderer: opengl or vulkan.")
+	if not OS.has_feature("windows") and not OS.has_feature("linux"):
+		push_error("Run this check on Windows or Linux.")
 		quit(1)
 		return
-	var renderer := arguments[0]
-	var expected := "mobile" if renderer == "vulkan" else "gl_compatibility"
 	var actual: String = ProjectSettings.get_setting_with_override("rendering/renderer/rendering_method")
-	if not OS.has_feature("linux_" + renderer) or actual != expected:
-		push_error("The exported renderer does not match %s: %s" % [renderer, actual])
+	if actual != "mobile":
+		push_error("The desktop export must default to Mobile: %s" % actual)
 		quit(1)
 		return
-	if renderer == "vulkan" and ProjectSettings.get_setting_with_override("rendering/rendering_device/driver") != "vulkan":
-		push_error("The Vulkan export must select the Vulkan driver.")
+	if ProjectSettings.get_setting_with_override("rendering/rendering_device/driver") != "vulkan":
+		push_error("The desktop export must select the Vulkan driver.")
 		quit(1)
 		return
-	print("Exported %s renderer settings: PASS" % renderer)
+	if not ProjectSettings.get_setting_with_override("rendering/rendering_device/fallback_to_opengl3"):
+		push_error("The desktop export must allow OpenGL fallback.")
+		quit(1)
+		return
+	if OS.has_feature("windows") and ProjectSettings.get_setting_with_override("rendering/rendering_device/fallback_to_d3d12"):
+		push_error("Windows must fall back to OpenGL instead of Direct3D 12.")
+		quit(1)
+		return
+	print("Desktop Vulkan defaults and OpenGL fallback settings: PASS")
 	quit()

tests/test_http.gd

@@ -54,6 +54,7 @@ func run_checks() -> void:
 	check('Token="fixture-token"' in last_request, "Authenticated calls send the token header")
 	check("StartIndex=24" in last_request, "Library pagination is sent")
 	check("Limit=25" in last_request, "Library pages request 25 titles")
+	check("IncludeItemTypes=Movie%2CSeries%2CVideo%2CPhoto" in last_request, "Browsing and search include photos")
 	await api.library("space", 48, "movies-id")
 	check("ParentId=movies-id" in last_request and "StartIndex=48" in last_request and "SearchTerm=space" in last_request, "Search and pagination stay inside the selected library")
 	await api.views()

tests/test_media_segments.gd

@@ -0,0 +1,109 @@
+extends SceneTree
+
+class FakeClient extends JellyfinClient:
+	signal respond
+	var paths: Array[String] = []
+	var response := {"ok": true, "data": {"Items": [{"Type": "Intro", "StartTicks": 100000000, "EndTicks": 400000000}]}}
+	func request(path: String, _method: HTTPClient.Method = HTTPClient.METHOD_GET, _body: Dictionary = {}) -> Dictionary:
+		paths.append(path)
+		await respond
+		return response
+
+class FakeVideo extends AndroidVideo:
+	var position := 10000
+	var last_seek := -1
+	func position_ms() -> int: return position
+	func duration_ms() -> int: return 120000
+	func seek(value: int) -> void: last_seek = value
+	func stop() -> void: pass
+
+func _initialize() -> void:
+	call_deferred("run_checks")
+
+func run_checks() -> void:
+	var segments := MediaSegments.new()
+	segments.segments = MediaSegments.parse({"Items": [
+		{"Type": "Outro", "StartTicks": 900000000, "EndTicks": 1200000000},
+		{"Type": "Intro", "StartTicks": 100000000, "EndTicks": 400000000},
+		{"Type": "Recap", "StartTicks": 0, "EndTicks": 100000000},
+		{"Type": "Commercial", "StartTicks": 0, "EndTicks": 100000000},
+		{"Type": "Intro", "StartTicks": -1, "EndTicks": 100},
+		{"Type": "Intro", "StartTicks": 100, "EndTicks": 1},
+		{"Type": "Intro", "StartTicks": "bad", "EndTicks": 100}, null
+	]})
+	assert(segments.segments.size() == 3)
+	assert(segments.active(0, 120000).label == "Skip recap")
+	assert(segments.active(10000, 120000).target_ms == 40000)
+	assert(segments.active(40000, 120000).is_empty())
+	assert(segments.active(90000, 120000).target_ms == 119000)
+	assert(segments.active(119000, 120000).is_empty())
+	assert(segments.active(10000, 0).is_empty())
+	assert(MediaSegments.parse(null).is_empty())
+	assert(MediaSegments.parse({"Items": null}).is_empty())
+	var api := FakeClient.new()
+	root.add_child(api)
+	segments.load_item(api, "episode/id")
+	assert(api.paths == ["/MediaSegments/episode%2Fid"])
+	segments.clear()
+	api.respond.emit()
+	assert(segments.segments.is_empty(), "Stopped playback rejects late responses")
+	segments.load_item(api, "episode")
+	api.respond.emit()
+	assert(segments.segments.size() == 1)
+	api.response = {"ok": false, "status": 404}
+	segments.load_item(api, "missing")
+	api.respond.emit()
+	assert(segments.segments.is_empty(), "Missing API clears old timestamps")
+	var app: Node = load("res://scenes/main.tscn").instantiate()
+	root.add_child(app)
+	var video := FakeVideo.new()
+	app.add_child(video)
+	app.video = video
+	app.media_segments.segments = MediaSegments.parse({"Items": [{"Type": "Intro", "StartTicks": 100000000, "EndTicks": 400000000}]})
+	app.playing = true
+	app.decoder_ready = true
+	app._update_timeline()
+	assert(app.world.player_skip_popup.available)
+	app.screen.show()
+	app.panel.hide()
+	app.player_overlay.hide()
+	app.world._process(0.0)
+	var popup: PlayerSkipPopup = app.world.player_skip_popup
+	assert(popup.is_visible_in_tree(), "Skip popup works with playback controls hidden")
+	assert(popup.position.x > 0 and popup.position.y < 0, "Popup sits at the bottom-right")
+	var bottom := popup.position.y
+	app.player_overlay.show()
+	app.world._process(0.0)
+	assert(popup.position.y > bottom, "Popup moves above visible controls")
+	var pointer := LaserPointer.new()
+	app.add_child(pointer)
+	pointer.global_position = popup.global_position + Vector3(0, 0, 1)
+	assert(pointer.points_at(popup, popup.panel_size), "Controller ray can target the popup")
+	pointer.global_position.x += 10
+	assert(not pointer.points_at(popup, popup.panel_size), "Other controls remain reachable outside the popup")
+	app.panel.show()
+	app.world._process(0.0)
+	assert(not popup.visible, "Library and settings hide the popup")
+	app.panel.hide()
+	app.world._process(0.0)
+	app.world.player_skip_popup.button.pressed.emit()
+	assert(video.last_seek == 40000, "The button seeks to the intro end")
+	app.session.method = "Transcode"
+	app.session.source = {"TranscodingUrl": "/master.m3u8"}
+	app._skip_segment()
+	assert(video.last_seek == 40000, "HLS uses the same absolute seek")
+	app.transcode_offset = 400000000
+	app._update_timeline()
+	assert(not app.world.player_skip_popup.available, "Progressive transcode uses absolute position")
+	app.transcode_offset = 0
+	app.decoder_ready = false
+	app._update_timeline()
+	assert(not app.world.player_skip_popup.available, "Loading hides skip actions")
+	app.playing = false
+	await app._stop(false)
+	assert(app.media_segments.segments.is_empty())
+	app.queue_free()
+	api.queue_free()
+	await process_frame
+	print("Media segment checks: PASS")
+	quit()

tests/test_media_segments.gd.uid

@@ -0,0 +1 @@
+uid://wmflbhqeuv0y

tests/test_pc_gpu_video.gd

@@ -2,9 +2,11 @@ extends SceneTree
 
 var decoder: Node
 var preview: TextureRect
+var screen: SubViewport
+var video_size := Vector2i.ZERO
 var video_texture: Texture2D
 var errors: Array[String] = []
-var frame_times: Array[float] = []
+var expected_renderer := "opengl"
 
 func _initialize() -> void:
 	call_deferred("run_check")
@@ -42,21 +44,19 @@ func check_controls_and_reopen(url: String) -> bool:
 	deadline = Time.get_ticks_msec() + 10000
 	while video_texture == null and errors.is_empty() and Time.get_ticks_msec() < deadline:
 		await process_frame
-	return require(video_texture != null and video_texture.get_size() == Vector2(1920, 1080) and errors.is_empty(), "Reopening replaces high-resolution GPU buffers")
+	return require(video_texture != null and video_size == Vector2i(1920, 1080) and errors.is_empty(), "Reopening replaces high-resolution GPU buffers")
 
 func run_check() -> void:
-	var url := ProjectSettings.globalize_path("res://native/android/src/main/res/raw/stereo_test.mp4")
+	expected_renderer = "vulkan" if RenderingServer.get_current_rendering_driver_name() == "vulkan" else "opengl"
+	var url := ProjectSettings.globalize_path("res://tests/fixtures/stereo_test.mp4")
 	var reopen_url := url
 	var expected_size := Vector2i(1920, 1080)
-	var minimum_fps := 0.0
 	for argument in OS.get_cmdline_user_args():
 		if argument.begins_with("--video="):
 			url = argument.trim_prefix("--video=")
 		if argument.begins_with("--size="):
 			var parts := argument.trim_prefix("--size=").split("x")
 			expected_size = Vector2i(int(parts[0]), int(parts[1]))
-		if argument.begins_with("--min-fps="):
-			minimum_fps = float(argument.trim_prefix("--min-fps="))
 		if argument.begins_with("--reopen-video="):
 			reopen_url = argument.trim_prefix("--reopen-video=")
 	if not require(DisplayServer.get_name() != "headless", "GPU checks require a graphics context"):
@@ -65,11 +65,15 @@ func run_check() -> void:
 	Engine.max_fps = 120
 	decoder = ClassDB.instantiate("JellyframeMpv")
 	root.add_child(decoder)
+	screen = preload("res://tests/pc_video_test_screen.gd").new(decoder)
+	root.add_child(screen)
+	decoder.size_changed.connect(func(w: int, h: int): video_size = Vector2i(w, h))
 	preview = TextureRect.new()
 	preview.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
 	preview.size = Vector2(640, 360)
 	root.add_child(preview)
-	decoder.texture_changed.connect(func(value: Texture2D): video_texture = value; preview.texture = value)
+	preview.texture = screen.get_texture()
+	decoder.texture_changed.connect(func(value: Texture2D): video_texture = value)
 	decoder.failed.connect(func(message: String): errors.append(message))
 	if not require(decoder.open_video(url, "", 0).is_empty(), "Open the GPU test video"):
 		return
@@ -78,35 +82,16 @@ func run_check() -> void:
 		await process_frame
 	if not require(video_texture != null and errors.is_empty(), "GPU produces a frame: " + str(errors)):
 		return
-	if not require(video_texture.get_size() == Vector2(expected_size), "GPU rendering preserves the source resolution"):
+	if not require(video_size == expected_size, "GPU rendering preserves the source resolution"):
 		return
-	await create_timer(0.5).timeout
-	var before: Dictionary = decoder.playback_diagnostics()
-	var last_frame := Time.get_ticks_usec()
-	var started := last_frame
-	while Time.get_ticks_usec() - started < 3000000 and errors.is_empty():
-		await process_frame
-		var now := Time.get_ticks_usec()
-		frame_times.append(float(now - last_frame) / 1000.0)
-		last_frame = now
-	var statistics: Dictionary = decoder.playback_diagnostics()
-	statistics["sample_uploaded_fps"] = float(statistics.uploaded_frames - before.uploaded_frames) * 1000000.0 / float(last_frame - started)
-	for counter in ["frame-drop-count", "decoder-frame-drop-count"]:
-		if before.get(counter) != null and statistics.get(counter) != null:
-			statistics["sample_" + counter] = statistics[counter] - before[counter]
-	frame_times.sort()
-	statistics["godot_frame_p95_ms"] = frame_times[mini(frame_times.size() - 1, int(frame_times.size() * 0.95))]
-	print("GPU playback statistics: ", JSON.stringify(statistics))
-	if not require(errors.is_empty() and statistics.render_backend == "opengl", "The GPU backend stays active during playback"):
+	var before := int(decoder.position_ms())
+	await create_timer(3.0).timeout
+	if not require(errors.is_empty() and decoder.rendering_backend() == expected_renderer, "The GPU backend stays active during playback"):
 		return
-	if not require(statistics.cpu_rgba_bytes == 0 and statistics.upload_cpu_ms == 0, "GPU playback avoids CPU RGBA staging and image uploads"):
+	if not require(decoder.position_ms() > before + 2000, "High-resolution playback continues advancing"):
 		return
-	var image := video_texture.get_image()
-	if not require(image != null and image.get_size() == expected_size, "Read the full-resolution GPU result"):
-		return
-	if not require(statistics.uploaded_frames > before.uploaded_frames, "Video frames continue reaching Godot"):
-		return
-	if not require(float(statistics.sample_uploaded_fps) >= minimum_fps, "Video meets the requested delivered frame rate"):
+	var image: Image = screen.image()
+	if not require(image != null and image.get_size() == screen.size, "Read the rendered video material"):
 		return
 	var screen_image := root.get_texture().get_image()
 	var brightest := 0.0

tests/test_pc_hdr.py

@@ -0,0 +1,71 @@
+"""Compare Vulkan PQ/HLG tone mapping and the 3D screen against FFmpeg references."""
+
+import argparse
+from array import array
+import math
+from pathlib import Path
+import subprocess
+import tempfile
+
+
+def pq_signal(nits):
+    value = (nits / 10000) ** (2610 / 16384)
+    return ((3424 / 4096 + 2413 / 128 * value) / (1 + 2392 / 128 * value)) ** (2523 / 32)
+
+
+def hlg_signal(nits):
+    value = (nits / 1000) ** (1 / 1.2)
+    return math.sqrt(3 * value) if value <= 1 / 12 else 0.17883277 * math.log(12 * value - 0.28466892) + 0.55991073
+
+
+def run(command):
+    result = subprocess.run(command, capture_output=True, text=True, timeout=60)
+    if result.returncode:
+        raise RuntimeError(result.stdout + result.stderr)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--godot", type=Path, required=True)
+    parser.add_argument("--ffmpeg", type=Path, required=True)
+    args = parser.parse_args()
+    project = Path(__file__).resolve().parents[1]
+    output = project / "build" / "hdr-tests"
+    output.mkdir(parents=True, exist_ok=True)
+    ffmpeg = str(args.ffmpeg.resolve())
+    with tempfile.TemporaryDirectory(dir=output) as directory:
+        directory = Path(directory)
+        for transfer, peak in [("pq", 1000), ("hlg", 1000), ("pq", 4000), ("sdr", 1000)]:
+            levels = [0, .1, 1, 5, 18, 50, 100, 203, 400, 1000]
+            signals = [pq_signal(nits) if transfer == "pq" else hlg_signal(nits) if transfer == "hlg" else nits / 1000 for nits in levels]
+            pixels = array("H")
+            row = array("H")
+            for signal in signals:
+                row.extend([round(64 + 876 * signal)] * 64)
+            for _ in range(192):
+                pixels.extend(row)
+            pixels.extend([512] * (640 * 192 // 2))
+            raw = directory / "levels.yuv"
+            raw.write_bytes(pixels.tobytes())
+            video = directory / "levels.mp4"
+            reference = directory / "reference.png"
+            trc = {"pq": "smpte2084", "hlg": "arib-std-b67", "sdr": "bt709"}[transfer]
+            primaries = "bt709" if transfer == "sdr" else "bt2020"
+            matrix = "bt709" if transfer == "sdr" else "bt2020nc"
+            encoder = f"lossless=1:log-level=error:colorprim={primaries}:transfer={trc}:colormatrix={matrix}:max-cll={peak},100"
+            run([ffmpeg, "-v", "error", "-f", "rawvideo", "-pixel_format", "yuv420p10le", "-video_size", "640x192",
+                 "-framerate", "1", "-i", str(raw), "-c:v", "libx265", "-preset", "ultrafast", "-x265-params", encoder,
+                 "-color_trc", trc, "-color_primaries", primaries, "-colorspace", matrix, "-y", str(video)])
+            filters = "format=rgb24" if transfer == "sdr" else (
+                "zscale=transfer=linear:npl=203,format=gbrpf32le,zscale=primaries=bt709,"
+                f"tonemap=tonemap=hable:desat=0:peak={peak / 203},"
+                "zscale=transfer=iec61966-2-1:range=full,format=rgb24")
+            run([ffmpeg, "-v", "error", "-i", str(video), "-vf", filters, "-frames:v", "1", "-y", str(reference)])
+            subprocess.run([str(args.godot.resolve()), "--path", str(project), "--xr-mode", "off", "--audio-driver", "Dummy",
+                            "--rendering-method", "mobile", "--rendering-driver", "vulkan", "--resolution", "640x360",
+                            "--script", "tests/test_pc_hdr_video.gd", "--", str(video), str(reference), transfer], check=True, timeout=30)
+    print("PQ, HLG, mastering peaks, and SDR screen checks: PASS")
+
+
+if __name__ == "__main__":
+    main()

tests/test_pc_hdr_video.gd

@@ -0,0 +1,57 @@
+extends SceneTree
+
+var decoder: Node
+var texture: Texture2D
+var errors: Array[String] = []
+
+func _initialize() -> void:
+	call_deferred("run_check")
+
+func require(condition: bool, message: String) -> bool:
+	if condition:
+		return true
+	push_error(message)
+	if decoder != null:
+		decoder.stop_video()
+	quit(1)
+	return false
+
+func run_check() -> void:
+	var args := OS.get_cmdline_user_args()
+	if not require(args.size() == 3, "Pass a video, reference PNG, and expected transfer"):
+		return
+	var reference := Image.load_from_file(args[1])
+	if not require(reference != null and not reference.is_empty(), "Read the FFmpeg tone-mapping reference"):
+		return
+	decoder = ClassDB.instantiate("JellyframeMpv")
+	root.add_child(decoder)
+	var screen := preload("res://tests/pc_video_test_screen.gd").new(decoder, Vector2i(640, 192))
+	root.add_child(screen)
+	decoder.texture_changed.connect(func(value: Texture2D): texture = value)
+	decoder.failed.connect(func(value: String): errors.append(value))
+	if not require(decoder.open_video(args[0], "", 0).is_empty(), "Open the HDR fixture"):
+		return
+	var deadline := Time.get_ticks_msec() + 10000
+	while texture == null and errors.is_empty() and Time.get_ticks_msec() < deadline:
+		await process_frame
+	if not require(texture != null and errors.is_empty(), "Vulkan produces HDR output: " + str(errors)):
+		return
+	decoder.set_paused(true)
+	var diagnostics: Dictionary = decoder.playback_diagnostics()
+	if not require(diagnostics.get("renderer") == "vulkan" and diagnostics.get("transfer") == args[2], "The decoder preserves transfer metadata: " + str(diagnostics)):
+		return
+	await create_timer(0.2).timeout
+	var rendered := screen.get_texture().get_image()
+	for index in range(10):
+		var point := Vector2i(index * 64 + 32, 96)
+		var expected := reference.get_pixelv(point)
+		var visible := rendered.get_pixelv(point)
+		for channel in range(3):
+			if not require(absf(visible[channel] - expected[channel]) < 0.02, "The 3D video screen preserves patch %d brightness: expected %s, got %s" % [index, str(expected), str(visible)]):
+				return
+	decoder.stop_video()
+	decoder.queue_free()
+	screen.queue_free()
+	await process_frame
+	print("Vulkan direct YUV HDR and 3D screen checks: PASS")
+	quit()

tests/test_pc_hdr_video.gd.uid

@@ -0,0 +1 @@
+uid://b0c1dcgtvan1n

tests/test_pc_streaming.py

@@ -66,10 +66,12 @@ def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--godot", required=True)
     parser.add_argument("--hls-directory", type=Path)
-    parser.add_argument("--opengl", action="store_true", help="Test GPU playback in a window")
+    graphics = parser.add_mutually_exclusive_group()
+    graphics.add_argument("--opengl", action="store_true", help="Test OpenGL GPU playback in a window")
+    graphics.add_argument("--vulkan", action="store_true", help="Test Vulkan GPU playback in a window")
     args = parser.parse_args()
     project = Path(__file__).resolve().parents[1]
-    media = [(project / "native/android/src/main/res/raw", "stereo_test.mp4")]
+    media = [(project / "tests/fixtures", "stereo_test.mp4")]
     if args.hls_directory:
         media.append((args.hls_directory.resolve(), "stream.m3u8"))
     for directory, name in media:
@@ -79,12 +81,14 @@ def main():
             thread.start()
             try:
                 result = subprocess.run(
-                    [args.godot, *(["--resolution", "640x360"] if args.opengl else ["--headless"]),
+                    [args.godot, *(["--resolution", "640x360", "--rendering-method", "mobile", "--rendering-driver", "vulkan"]
+                                  if args.vulkan else ["--resolution", "640x360", "--rendering-method", "gl_compatibility"]
+                                  if args.opengl else ["--headless"]),
                      "--xr-mode", "off", "--path", str(project),
                      "--script", "tests/test_pc_video.gd", "--",
                      f"--video=http://127.0.0.1:{server.server_port}/{name}",
                      f"--auth={AUTHORIZATION}",
-                     f"--expect-renderer={'opengl' if args.opengl else 'software'}"],
+                     f"--expect-renderer={'vulkan' if args.vulkan else 'opengl' if args.opengl else 'software'}"],
                     timeout=45, check=False,
                 )
                 if result.returncode: