From feef698940e90fbb71d04452da51452fbcae3fdb Mon Sep 17 00:00:00 2001 From: Lizzy <23005387+Cuteminded@users.noreply.github.com> Date: Sat, 24 Oct 2026 05:03:16 +0200 Subject: [PATCH] Reorganize development and installation docs --- DEVELOPMENT.md | 263 +++++++++++++++++++++++------------------------- INSTALLATION.md | 54 ++++------ 2 files changed, 144 insertions(+), 173 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0da108c..6d6e9ec 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,30 +1,18 @@ -# Build from source +# Development -Jellyframe uses Godot and OpenXR. It has an Android video plugin and a shared PC plugin for Windows and Linux. The PC plugin uses libmpv for OpenGL playback and audio. Vulkan video uses FFmpeg and Godot's RenderingDevice. +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`. -Check the [README's tested results](README.md#what-has-been-tested) and [current limitations](README.md#current-limitations) before making platform or performance claims. Windows SteamVR playback with Vulkan, HDR, 4K, and 8K has been confirmed on an RTX 4070. Other platforms and renderers need separate testing. +Build the native video plugin for your platform before importing the project. Close Jellyframe before rebuilding the plugin. -## Android build requirements +## 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. The PC Vulkan backend's hardware decoding and HDR conversion do not apply to Android. - -## Build the Quest APK - -Open **Actions > Build Android APK > Run workflow** to build a Quest 3 debug APK. The workflow builds the native video plugin, exports the APK, and checks its signature. It needs no repository secrets and keeps the APK artifact for 14 days. - -Each workflow run creates a new debug signing key. If the installed APK has a different key, uninstall it before installing the new build. Uninstalling removes saved settings and sign-in. These APKs are test builds, not 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: @@ -34,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: @@ -44,11 +32,13 @@ 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. It downloads Godot OpenXR Vendors 5.1.0 for Quest passthrough support, checks the archive's SHA-256 checksum, and includes the vendor licences in the APK. The downloaded addon stays 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 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' @@ -57,107 +47,13 @@ godot --headless --xr-mode off --path . --editor --import --quit godot --headless --xr-mode off --path . --export-release 'Windows' dist/windows/jellyframe.exe ``` -The plugin build script downloads pinned CMake, LLVM-MinGW, godot-cpp, libmpv, and FFmpeg archives into `build/desktop` and verifies their checksums. It generates `addons/jellyframe_mpv` without a system-wide compiler installation. Close Jellyframe 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. Run the tests separately with the commands below. Build commands disable OpenXR; the exported app keeps it enabled. The workflow needs no repository secrets. 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). -The Windows preset exports one executable and defaults to OpenGL. With SteamVR and the headset running, launch Vulkan explicitly: +## Build on Linux x64 or ARM64 -```powershell -.\dist\windows\jellyframe.exe --rendering-method mobile --rendering-driver vulkan -``` - -The Linux presets select their renderer automatically. The workflow does not create separate Windows renderer packages or launchers. - -After building the PC plugin, run its decoder tests without a headset: - -```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' -``` - -Run GPU playback checks 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 mobile --rendering-driver vulkan --path . --script tests/test_pc_video_transitions.gd -godot --xr-mode off --rendering-method gl_compatibility --path . --script tests/test_pc_video_transitions.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 Vulkan test generates ten-bit video fixtures and checks BT.601 limited-range and BT.709 full-range colors, paused seeks, completion, and playback with audio. Pass `--video=` and `--size=7680x4320` to `test_pc_gpu_video.gd` to check an 8K source and reopening at 1080p. These checks do not measure sustained frame rate or verify headset playback. - -The transition test renders the PC video material before playback, after stopping, and when reopening a video. It checks that a missing texture produces black and that a decoded video becomes visible. Vulkan and OpenGL checks have passed locally. The black start/stop transition still needs headset confirmation. - -OpenGL uses the existing libmpv renderer and shared GPU textures. Vulkan uses a separate FFmpeg decoder and a compute shader on Godot's main Vulkan device. - -Native NV12, P010, and planar 4:2:0 frames keep their original plane layout. The decoder converts other formats to ten-bit planar data. Windows tries CUDA/NVDEC before D3D11VA. Linux tries VA-API or CUDA. CUDA downloads go directly into reusable pinned upload buffers. - -A reader thread buffers compressed video packets independently of decoding. It reads ahead up to four seconds, 128 MiB, or 512 packets. If video falls behind, audio waits for it to catch up and for one second of compressed video to accumulate. Playback can also resume when the reader reaches the end or the buffer limit. Seeking clears queued packets and flushes the decoder. - -Decoding and downloads run on another worker. Godot's render thread handles uploads, with one upload scheduled at a time. Uploads share the renderer's frame budget. Decoded planes pass through system memory, so this is not a zero-copy backend. - -Desktop RenderingDevice settings allow up to 512 MiB of staging buffers and use larger upload regions to reduce stalls with 8K ten-bit frames. The engine allocates this memory as needed. OpenGL and Android Compatibility rendering do not use these buffers. - -PQ and HLG video use Hable tone mapping to SDR. The conversion uses mastering or content-light metadata when available, or a 1,000-nit default. The HDR test compares gray patches with FFmpeg's reference conversion and checks their brightness through the 3D video material. HDR output and display calibration are not supported. - -Measure presentation rate and frame times with a source long enough for the requested sample, including 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 result reports presented frames per second, dropped frames, decoder and transfer timings, and main-loop frame times. The default source is the locally generated `build/gpu-worker/8k-av1-test.mp4`. Supply your own file on a fresh checkout. This windowed benchmark does not measure SteamVR performance. - -During ordinary playback, the startup log identifies the renderer, codec, hardware device, HDR transfer, and backend version. Set `JELLYFRAME_VIDEO_STATS=1` to log counters every five seconds. The decoder skips isolated corrupt video packets. Repeated errors trigger the software fallback. - -To test buffering, supply a video with audio and at least 20 seconds of content. The test uses FFmpeg and `ffprobe` from the same directory and serves the file over local HTTP: - -```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 interrupts delivery and checks recovery, audio synchronization, and a manual pause during buffering. The second delivers at twice the average bitrate, adds a 1.5-second interruption, and checks that read-ahead absorbs it without a buffer stop. Omitting `--video` generates a 4K HEVC fixture and requires FFmpeg's NVIDIA NVENC encoder. - -These checks passed with an 8K AV1 source on the Windows RTX 4070 setup. A separate 15-second local benchmark measured about 60 presented frames per second without dropped frames. Headset confirmation of HDR, 4K, and 8K playback is recorded separately in the [README](README.md#what-has-been-tested). - -For a Vulkan playback log in PowerShell, 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') -``` - -The log includes the codec, hardware decoder, audio and video positions, read-ahead duration and size, dropped frames, and video buffering count. Remove access tokens and private server details before sharing a log. - -For videos with audio, libmpv opens the source separately with video disabled and supplies the audio clock. Remote playback can therefore make two sets of media requests. Silent videos use the FFmpeg frames and a local playback clock. - -If initialization, decoding, or GPU playback stalls or fails, playback falls back to the existing software renderer. `JELLYFRAME_PC_RENDERER=software` forces that fallback for troubleshooting. - -With SteamVR and your headset running, test the stereo screen and controllers: - -```powershell -godot --rendering-method mobile --rendering-driver vulkan --path . --script tests/test_steamvr_video.gd -``` - -The headset 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 the playback controls. When signed in, press B to browse the library while playback continues. Use `--rendering-method gl_compatibility` instead of the Vulkan arguments to check OpenGL. 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. It remembers sign-in through the local session store but does not play videos in the app. Decoder test scripts are separate from this desktop interface mode. - -## 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 libavcodec-dev libavformat-dev libavutil-dev libswscale-dev @@ -165,45 +61,60 @@ 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`. It uses the system libmpv and FFmpeg development packages. FFmpeg 6 or newer is required. 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' 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' dist/linux-arm64/jellyframe.arm64 ``` -Windows and Linux use the Mobile renderer with Vulkan. If Vulkan cannot initialize, Godot falls back to OpenGL Compatibility. Pass `--rendering-method gl_compatibility` to select OpenGL manually. Each Linux executable embeds its resources and loads the native decoder library from the output folder. +Keep the executable and native decoder `.so` file together. -The Build Linux workflow uses native `ubuntu-24.04` and `ubuntu-24.04-arm` runners. Each job builds its plugin, exports one app with Vulkan as the default and OpenGL as the fallback, and checks output files and decoder dependencies. It then packages a system-libraries archive and one AppImage for its architecture. Run the tests separately with the commands in this guide. +### Package an AppImage -The system-libraries artifact is a tar archive that preserves Linux executable permissions. GitHub keeps the build artifacts for 14 days. The workflow needs no repository secrets. - -To package AppImages after exporting and copying the licenses into `dist/linux-`, 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 and includes its license notices and package manifest. The host supplies graphics drivers and OpenXR. The packager downloads appimagetool 1.9.1 for the selected architecture, verifies its SHA-256 checksum, and runs it without FUSE. +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-.AppImage`. The host supplies graphics drivers and OpenXR. -appimagetool downloads its AppImage runtime during packaging, so packaging needs network access. The output is `dist/jellyframe-linux-.AppImage`. +## Run the app during development -The decoder and headset tests in [Build and test on Windows](#build-and-test-on-windows) also work on Linux. Use `python3` for the HTTP streaming test and pass the path to your Linux Godot executable. +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 @@ -214,15 +125,89 @@ godot --headless --xr-mode off --path . --script tests/test_player_tooltips.gd godot --headless --xr-mode off --path . --script tests/test_player_loading.gd ``` -## Check 180° and 360° rendering +## Test PC video -Render synthetic panoramas to check top-bottom eye selection and confirm that the view behind a 180° video stays dark on desktop: +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 +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. + +### 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 + +```sh godot --xr-mode off --path . --script tests/capture_360.gd ``` -The check uses a generated texture to test the PC shader and saves panorama and settings previews in `dist`. It does not enable desktop video playback in the app. It cannot test 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 @@ -230,5 +215,5 @@ The check uses a generated texture to test the PC shader and saves panorama and - `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 OpenGL renderer, FFmpeg Vulkan decoder, GPU plane conversion, and playback synchronization. +- `native/pc` contains the libmpv OpenGL renderer and FFmpeg Vulkan decoder. - `scripts/core` contains screen settings and stereo geometry. diff --git a/INSTALLATION.md b/INSTALLATION.md index 95d1474..c008d41 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,60 +1,48 @@ # 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 the Android APK from **Assets** on the [latest release page](https://github.com/Cuteminded/jellyframe/releases/latest). To build the APK yourself, follow the [build instructions](DEVELOPMENT.md). - -Connect your headset to your computer and approve USB debugging in the headset. Install the APK with Android's `adb` tool. Run these commands from the folder containing the downloaded APK: +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 jellyframe-android.apk ``` -If you built the APK yourself, use `dist/jellyframe-android.apk` as the install path instead. +Open Jellyframe from **Unknown Sources** in your headset. -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. +## Windows with SteamVR -## Try it on Windows with SteamVR +Download the Windows ZIP and extract the entire archive. Keep all files together in the extracted folder. -Download the Windows ZIP from **Assets** on the [latest release page](https://github.com/Cuteminded/jellyframe/releases/latest). Extract the entire ZIP and keep the executable, PCK, and any DLLs together in the same folder. +Install SteamVR and connect your headset. In SteamVR's **Settings > OpenXR**, set SteamVR as the active OpenXR runtime. Start SteamVR, then run `jellyframe.exe`. -Install SteamVR and connect your headset. In SteamVR's **Settings > OpenXR**, set SteamVR as the active OpenXR runtime. Start SteamVR, then 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). - -Windows starts with Vulkan and falls back to OpenGL if Vulkan cannot initialize. To select OpenGL manually, run this from the extracted folder in PowerShell: +If Jellyframe cannot start with Vulkan, try OpenGL from PowerShell in the extracted folder: ```powershell .\jellyframe.exe --rendering-method gl_compatibility ``` -Sign in to Jellyfin and select a title to play it in VR. Pause, seek, resume, and side-by-side 3D controls work as they do in the Quest build. +## Linux x64 or ARM64 -Keep all DLLs from the matching build beside the executable. Current source builds need `jellyframe_mpv.dll`, `libmpv-2.dll`, `avcodec-62.dll`, `avformat-62.dll`, `avutil-60.dll`, `swscale-9.dll`, and `swresample-6.dll`. +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. -The confirmed Vulkan HDR, 4K, and 8K results apply to a Windows SteamVR setup with an NVIDIA RTX 4070. Check the [current limitations](README.md#current-limitations) for other configurations. A published release may predate these changes; use [the source build instructions](DEVELOPMENT.md#build-and-test-on-windows) when testing the current implementation. - -## Try it on Linux x64 or ARM64 - -Download the Linux AppImage from **Assets** on the [latest release page](https://github.com/Cuteminded/jellyframe/releases/latest). Choose the file for your computer's architecture, `x86_64` or `arm64`. AppImages include libmpv and the bundled decoder libraries. - -Make the downloaded AppImage executable and launch it. For x64: +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.AppImage ./jellyframe-linux-x86_64.AppImage ``` -Linux starts with Vulkan and falls back to OpenGL if Vulkan cannot initialize. Use the same AppImage when adding Jellyframe to Steam on SteamOS. For ARM64, use `jellyframe-linux-arm64.AppImage`. +For ARM64, replace the filename with `jellyframe-linux-arm64.AppImage`. On SteamOS, add the AppImage to Steam as a non-Steam game. -To select OpenGL manually: +If Jellyframe cannot start with Vulkan, try OpenGL: ```sh ./jellyframe-linux-x86_64.AppImage --rendering-method gl_compatibility @@ -62,13 +50,9 @@ To select OpenGL manually: If mounting an AppImage fails because FUSE is unavailable, run it with `--appimage-extract-and-run`. -The builds target Ubuntu 24.04. AppImages need compatible system libraries, graphics drivers, and an OpenXR runtime. They may not work on older Linux distributions. +### Use system libraries instead of an AppImage -Connect your headset and start your OpenXR runtime before opening Jellyframe. On x64, set SteamVR as the active runtime. The runtime must support the selected graphics API. SteamVR on ARM64 and standalone Steam Frame support still need headset testing. - -SteamOS Vulkan playback was confirmed with an earlier PC backend. The current native Vulkan decoder, HDR conversion, and high-resolution playback still need Linux headset testing. The Windows results do not confirm those cases on Linux. See the [current limitations](README.md#current-limitations). - -The `system-libs` archive remains available if you prefer to install libmpv yourself. It contains the same executable with Vulkan as the default and OpenGL as the fallback. 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 @@ -78,4 +62,6 @@ tar -xzf jellyframe-linux-x86_64-system-libs.tar.gz 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.