Volumetric video player for the web. Lifelike 3D content in the browser — flat screen, VR, or AR — with a single JavaScript import.
Live demos: Player · Vanilla UI · React · Three.js · PlayCanvas
- WebGPU + WASM — hardware-accelerated volumetric playback at scale
- Cross-platform — 2D, VR, and AR from one SDK; optimized for Meta Quest 3/3S, Pico 4 Ultra, Apple Vision Pro
- Adaptive streaming — seek, buffer, and switch scenes seamlessly
- Developer-first — React hooks, Three.js mesh, PlayCanvas, vanilla JS — pick your stack
- XR built-in — hand tracking, grab-to-move, spatial audio, environment relighting
- Modular — zero required deps; tree-shake what you don't need
| File | Description |
|---|---|
GraciaWebCore.js |
WASM engine — core playback runtime (zero JS dependencies) |
GraciaSDK.js |
Tree-shakeable ES module — player, Three.js, React hooks, XR |
GraciaAIO.js |
Self-contained demo bundle (includes Three.js, React, styled player, mount helper) |
GraciaSDK.js loads peer dependencies on demand — only what you use. GraciaAIO.js bundles third-party libraries unmodified under their original licenses.
npm install github:gracia-labs/web-sdk # core SDK
npm install github:gracia-labs/web-sdk three # + Three.js
npm install github:gracia-labs/web-sdk playcanvas # + PlayCanvas
npm install github:gracia-labs/web-sdk react # + React hooksOr add directly to package.json:
"@gracia/web-sdk": "github:gracia-labs/web-sdk"All peer dependencies are optional — install only what your integration needs:
| Peer dependency | Required for |
|---|---|
three |
SplatsMesh, XROverlay, XR controls |
playcanvas |
GraciaSplats |
react |
useGraciaPlayer, useGraciaPlaylist, GraciaReactPlayer |
react-dom |
mountGraciaPlayer, GraciaReactPlayer |
@react-three/fiber |
XR UI panels (R3F-based) |
@react-three/uikit |
XR UI panels |
@preact/signals-core |
XR UI reactive state |
@pmndrs/pointer-events |
XR pointer events |
The fastest path is the styled player — drop-in UI with playback, seek, scene switching, fullscreen, and VR/AR where supported. Default styles are auto-installed and scoped under .gr-player.
React apps import from @gracia/web-sdk/core. Plain HTML pages import from @gracia/web-sdk/aio (React bundled inside).
import { GraciaReactPlayer } from "@gracia/web-sdk/core";
export function Player() {
return (
<GraciaReactPlayer
streaming={[{ streamingId: "content-id", token: "view-token", label: "Demo" }]}
localFiles
sceneSelector="menu"
/>
);
}With the Vite plugin, WASM is wired at build time — no moduleUrl prop needed. Streaming tokens resolve against the Gracia market API by default.
<script type="importmap">{ "imports": {
"@gracia/web-sdk/aio": "/path/to/GraciaAIO.<hash>.js",
"@gracia/web-sdk/wasm": "/path/to/GraciaWebCore.<hash>.js"
} }</script>
<div id="player"></div>
<script type="module">
import { mountGraciaPlayer } from "@gracia/web-sdk/aio";
const player = mountGraciaPlayer(document.querySelector("#player"), {
streaming: [{ streamingId: "content-id", token: "view-token", label: "Demo" }],
localFiles: true,
sceneSelector: "menu",
moduleUrl: "@gracia/web-sdk/wasm",
});
player.update({ streaming: [{ streamingId: "next-id", token: "view-token", label: "Next" }] });
player.unmount();
</script>Run the local demo: clone the repo, bun install && bun serve, then open https://localhost:6931.
Each HTML demo is self-contained — open the source for a full working integration.
| Integration | Demo | Source | Description |
|---|---|---|---|
Styled player — GraciaReactPlayer / mountGraciaPlayer |
Player | examples/plain/pages/index.html |
Recommended starting point — pretty player, playlist, local files, XR |
Vanilla JS — GraciaApp + custom UI |
Vanilla UI | examples/plain/pages/vanilla.html |
Low-level GraciaApp with hand-built controls (no styled player) |
React hooks — useGraciaPlayer |
React | examples/plain/pages/react.html |
Declarative integration with hooks and playlist |
Three.js — SplatsMesh |
Three.js | examples/plain/pages/three.html |
Splats as a standard Three.js mesh with environment relighting |
PlayCanvas — GraciaSplats |
PlayCanvas | examples/plain/pages/playcanvas.html |
Splats with depth testing and automatic shadow casting |
| Stack | Source | Description |
|---|---|---|
| React + Vite + TypeScript | examples/react-vite |
Production-ready Vite setup with GraciaReactPlayer, WASM serving, Strict Mode, and cleanup patterns |
The SDK ships a unified Vite plugin that handles WASM serving, content-hash cache busting, dynamic import warning suppression, and build-time defines — all in one call:
import { graciaPlugin } from "@gracia/web-sdk/vite-plugin";
export default defineConfig({
plugins: [react(), ...graciaPlugin({ bundle: "core" })],
});The plugin provides:
- Manifest + aliases: reads
gracia-manifest.json, resolves@gracia/web-sdk/core|aio|wasm - Dev: serves hashed WASM during Vite dev
- Build: copies WASM to
assets/with its content-hashed filename - Optional dedupe: pass
dedupe: truefor React/Three apps - Defines: injects
__GRACIA_MODULE_URL__for the player; optionally__GRACIA_STREAMING_BASE_URL__whenstreamingBaseUrlis set
Custom streaming API — omit streamingBaseUrl to use the default market endpoint. Pass it only when your app needs a different URL (for example a dev proxy):
...graciaPlugin({
bundle: "core",
streamingBaseUrl: "/api/market/api/v1/streaming/content", // non-default only
})GraciaWebCore.js is precompiled Emscripten glue — serve it as a static file, not processed by your bundler.
Webpack — read the manifest and copy the hashed WASM file:
import manifest from "@gracia/web-sdk/manifest";
const wasmHash = manifest.files["GraciaWebCore.js"].hash;
const hashedName = `GraciaWebCore.${wasmHash}.js`;
new CopyPlugin({
patterns: [{
from: `node_modules/@gracia/web-sdk/${hashedName}`,
to: `assets/${hashedName}`,
}],
});Then reference it:
useGraciaPlayer({ containerRef, moduleUrl: `/assets/GraciaWebCore.${wasmHash}.js` });The SDK uses content-hash filenames for cache busting. After npm install, the package includes a manifest at @gracia/web-sdk/manifest (dist/gracia-manifest.json) with hashed filenames for each artifact:
import manifest from "@gracia/web-sdk/manifest";
const wasmHash = manifest.files["GraciaWebCore.js"].hash; // e.g. "a1b2c3d4e5f67890"
const hashedName = `GraciaWebCore.${wasmHash}.js`; // copy this to your public assetsVite users: graciaPlugin handles this automatically — no manual steps needed.
Non-Vite users: read the manifest to get the hashed filename, copy the corresponding hashed file from dist/ to your public assets, and pass the URL as moduleUrl. This ensures browsers fetch the correct version after SDK upgrades.
Server cache headers (recommended):
| Pattern | Cache-Control |
|---|---|
*.<hash>.js |
public, max-age=31536000, immutable |
*.js (non-hashed) |
no-cache, must-revalidate |
*.html |
no-cache, no-store, must-revalidate |
| Export | Description |
|---|---|
GraciaPlayer |
Core player — play, pause, seek, render |
GraciaApp |
High-level standalone player with camera, XR, mode switching |
SplatsMesh |
Three.js Mesh subclass for scene graph integration |
GraciaSplats |
PlayCanvas integration — splats with depth testing and shadow casting |
| Hook / export | Description |
|---|---|
useGraciaPlayer(options) |
Manages player lifecycle, returns reactive state |
useGraciaPlaylist(gracia) |
Multi-source playlist with next/prev/goTo |
GraciaReactPlayer |
Styled React player component |
mountGraciaPlayer |
Vanilla mount helper for the styled player |
GRACIA_PLAYER_DEFAULT_CSS |
Default player CSS string |
installGraciaPlayerStyles |
Installs scoped default styles into document.head or a shadow root |
GraciaReactPlayer and mountGraciaPlayer share the same props. Pass sources or streaming (streamingId + token); when both are set, streaming wins. Metadata resolves against the market API by default — override only via graciaPlugin({ streamingBaseUrl }) or buildApiSources(items, baseUrl).
| Prop | Default | Description |
|---|---|---|
sources / streaming |
— | Pre-built scenes, or id + token pairs the player resolves |
controls |
true |
Built-in playback, scene, and XR UI |
sceneSelector |
"stepper" |
"tabs" or "menu" for playlists |
cameraControls |
false |
2D camera selector (orbit / trackball / fly) |
localFiles |
false |
When true, adds open-file control for .mint / .sog from disk |
muted |
false |
Initial mute on first ready only |
xrOverlay |
modern UI | false disables in-headset UI |
style / className |
— | Root styles; use --gr-player-* variables (no theme prop) |
| callbacks | — | onReady, onProgress, onModeChange, onSceneChange, onError, … |
eventLogger |
— | Low-level UI/error events |
Imperative handle (ref.current or mountGraciaPlayer(...).player): play, pause, seek, next/prev/goTo, setMode, setCameraControls, toggleFullscreen, openLocalFile. See examples/react-vite and index.html.
For custom UI, use useGraciaPlayer, useGraciaPlaylist, and XROverlay instead.
| Export | Description |
|---|---|
XROverlay |
Full XR experience — hand tracking, grab-to-move, UI panels |
ClassicControls |
Compact VR control panel |
ModernControls |
Full-featured VR control panel with mute, lock, drag-to-reposition |
| Export | Description |
|---|---|
buildApiSources(items, baseUrl) |
Resolve streaming IDs into playable sources |
fetchStreamingMetadata(baseUrl, id, token) |
Fetch metadata for a streaming source |
ENV_PRESETS / presetToLightProbe |
Environment lighting presets for AR |
EnvLighting |
Environment lighting for AR scenes |
| Mode | Key |
|---|---|
| 2D | pw |
| VR | vr |
| AR | ar |
- WebGPU —
navigator.gpurequired (support): Chrome 113+, Edge 113+, Safari 18+, Firefox Nightly (flag) - HTTPS — WebGPU and WebXR require a secure context on non-localhost origins
- WebXR — VR/AR modes only (Meta Quest Browser, etc.)
One option for delivering your content is Gracia's own reliable streaming infrastructure — scenes are hosted and served for you, with per-scene access control. See docs.gracia.ai/streaming-usage for how to use it.
Thanks to Martin Valigursky for help with the PlayCanvas integration.
This repository is covered by two licenses, both in the single LICENSE file:
| What | License | Where |
|---|---|---|
Gracia Web SDK — GraciaWebCore.js, GraciaSDK.js, GraciaAIO.js, WASM modules, type definitions, and other distributed SDK artifacts |
Proprietary | LICENSE — Part A |
| Examples, samples & documentation — wherever located | MIT | LICENSE — Part B |
All other files are © Gracia Labs. Third-party dependencies keep their own licenses. For special or enterprise licensing, contact support@gracia.ai.
Proprietary — Gracia Labs. All rights reserved.