aiden/VR-Web-Player
1
0
Fork 0
forked from EXT/VR180-Web-Player
Code Actions Activity

Updated
Some checks failed
Test / test (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Aiden
2026-06-11 09:12:17 +10:00
parent 1d4b3ce307
commit b674df1555
21 changed files with 1176 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
README.md
View File

@@ -10,45 +10,68 @@ The player supports two projection modes:
Build the player first, then host the generated `vr180player/` directory on your CDN and include the module script. The script automatically loads its matching CSS file from the same folder, and it imports its helper modules with relative module paths.
```html
<div data-vr-web-player data-projection="vr180">
<video poster="poster.jpg" title="Demo Video" crossorigin="anonymous" playsinline preload="metadata">
<source src="sbs-video.mp4" type="video/mp4">
</video>
</div>
<button
type="button"
data-vr-web-launcher
data-media-type="image"
data-projection="vr180"
data-src="vr180-sbs-image.jpg"
data-title="Temple Hall"
data-crossorigin="anonymous">
<img src="temple-thumb.jpg" alt="Temple Hall">
</button>
<script type="module" src="https://cdn.example.com/vr180player/vr180-player.js"></script>
```
Use `data-projection="plane"` for flat 3D video on a rectangular plane:
A page can contain any number of launchers. Each launcher represents one SBS media item. A launcher click goes straight into immersive WebXR when `immersive-vr` is supported. When immersive WebXR is unavailable, the same click opens a modal with the left-eye fallback view.
Launcher attributes:
- `data-vr-web-launcher`: required marker.
- `data-src`: required media URL. For image carousels, provide at least two comma-separated image URLs.
- `data-media-type="image|video"`: optional when the media type can be inferred from the URL extension.
- `data-projection="vr180|plane"`: defaults to `vr180`.
- `data-title`: optional display title.
- `data-carousel`: optional image carousel mode.
- `data-head-lock="auto|position|none"`: optional positional comfort mode. It defaults to `auto`, which position-locks `vr180` media to the headset to avoid false 6DoF parallax, while leaving `plane` media fixed like a screen.
- `data-poster`, `data-type`, and `data-preload`: video helpers.
- `data-crossorigin`: optional media CORS mode, usually `anonymous` for CDN media.
Use `data-projection="plane"` for flat 3D media on a rectangular plane:
```html
<div data-vr-web-player data-projection="plane">
<video poster="poster.jpg" title="Demo Video" crossorigin="anonymous" playsinline preload="metadata">
<source src="sbs-video.mp4" type="video/mp4">
</video>
</div>
<button
type="button"
data-vr-web-launcher
data-media-type="video"
data-projection="plane"
data-src="flat-sbs-video.mp4"
data-poster="poster.jpg"
data-title="Flat 3D Demo"
data-type="video/mp4"
data-crossorigin="anonymous">
<img src="poster.jpg" alt="Flat 3D Demo">
</button>
```
Use `data-head-lock="auto|position|none"` to control positional comfort in immersive mode. It defaults to `auto`, which position-locks `vr180` media to the headset to avoid false 6DoF parallax, while leaving `plane` media fixed like a screen. Use `position` to force locking for either projection, or `none` to keep all media world-fixed.
Use an `img` element for a static SBS image:
Use `data-carousel` for multiple SBS still images in one immersive session:
```html
<div data-vr-web-player data-projection="plane">
<img src="sbs-image.png" alt="Demo image" title="Demo Image" crossorigin="anonymous">
</div>
<button
type="button"
data-vr-web-launcher
data-carousel
data-media-type="image"
data-projection="vr180"
data-src="first-sbs-image.png, second-sbs-image.png"
data-title="VR180 Stills"
data-crossorigin="anonymous">
<img src="first-thumb.jpg" alt="VR180 Stills">
</button>
```
Add `data-carousel` to an image player when you want previous/next controls for multiple SBS still images in one immersive session:
```html
<div data-vr-web-player data-projection="vr180" data-carousel>
<img src="first-sbs-image.png" alt="First image" title="First Image" crossorigin="anonymous">
<img src="second-sbs-image.png" alt="Second image" title="Second Image" crossorigin="anonymous">
</div>
```
Only one player is supported per page in this version. The player logs a clear console message and does not initialize if no `[data-vr-web-player]` container is found, if multiple containers are found, if the container does not contain exactly one supported video/image element, if an image carousel does not contain at least two images and no videos, or if `data-projection` is not `vr180` or `plane`.
`[data-vr-web-player]` is now an internal container created by the launcher at runtime. Authored pages should use `[data-vr-web-launcher]`.
## Media format
This version supports side-by-side media only:
@@ -59,7 +82,7 @@ This version supports side-by-side media only:
It does not support over-under, MV-HEVC, APMP, or `.aivu`.
## How it works
When the page loads, the media is embedded normally with an entry button over it. When the user clicks the button, the player checks for `navigator.xr` and `immersive-vr` support.
When the page loads, the script binds every `[data-vr-web-launcher]` on the page. When the user clicks a launcher, the player checks for `navigator.xr` and `immersive-vr` support, then splits between immersive entry and fallback modal display.
- In WebXR, `vr180` maps the left and right halves of the SBS media onto the matching eyes of a 180 degree sphere. In the default `auto` head-lock mode, the sphere follows headset position but not headset rotation.
- In WebXR, `plane` maps the left and right halves onto the matching eyes of a floating 16:9 plane.
@@ -71,7 +94,7 @@ When the page loads, the media is embedded normally with an entry button over it
- Control icons are embedded from [Lucide](https://lucide.dev/) SVG definitions, so no PNG icon assets are required.
## Demo
Run `npm run build`, then open `test-pages/index.html` through a local web server. The test hub links to focused pages for flat 3D image, VR180 3D image, image carousels, flat 3D video, and VR180 3D video. The root `index.html` redirects there for convenience.
Run `npm run build`, then open `test-pages/index.html` through a local web server. The test hub is a gallery with launchers for flat 3D image, VR180 3D image, image carousels, flat 3D video, and VR180 3D video.
For local experimentation, run: