Skip to content

StorySplat Viewer Overview

The storysplat-viewer npm package provides a powerful, customizable viewer for Gaussian Splatting content on the web.

Features

  • High Performance - Built on PlayCanvas engine for smooth rendering
  • Multiple Formats - Supports PLY, SOG, SPLAT, and compressed PLY
  • 4DGS Support - Play back volumetric video frame sequences
  • Interactive - Orbit, fly, and tour camera modes
  • Rich Content - Waypoints, hotspots, custom meshes, particles
  • Mobile Ready - Touch controls and responsive design
  • Customizable - UI theming and event hooks

Installation

npm install storysplat-viewer

yarn add storysplat-viewer

pnpm add storysplat-viewer

<!-- Bundled build - includes PlayCanvas, single script! -->
<script src="https://cdn.jsdelivr.net/npm/storysplat-viewer@2/dist/storysplat-viewer.bundled.umd.js"></script>

<!-- If you need a specific PlayCanvas version -->
<script src="https://cdn.jsdelivr.net/npm/playcanvas@2.14.3/build/playcanvas.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/storysplat-viewer@2/dist/storysplat-viewer.umd.js"></script>

Quick Example

import { createViewerFromSceneId } from 'storysplat-viewer';

// Fetches scene from StorySplat API, always up-to-date
const viewer = await createViewerFromSceneId(
  document.getElementById('container'),
  'YOUR_SCENE_ID'
);

From Scene Data (Self-Hosted)

import { createViewer } from 'storysplat-viewer';
import sceneData from './my-scene.json';

const viewer = createViewer(document.getElementById('container'), sceneData);

Use Cases

Embed a Scene from StorySplat

The easiest way - just use your scene ID:

import { createViewerFromSceneId } from 'storysplat-viewer';

const viewer = await createViewerFromSceneId(
  document.getElementById('viewer'),
  'YOUR_SCENE_ID',
  { revealEffect: 'medium' }
);

Embed a Self-Hosted Scene

For version-controlled or self-hosted scenes:

import { createViewer } from 'storysplat-viewer';
import sceneData from './my-scene.json';

const viewer = createViewer(container, sceneData, {
  revealEffect: 'medium'
});

Control Playback

Navigate through waypoints programmatically:

const viewer = await createViewerFromSceneId(container, sceneId);

// Start autoplay
viewer.play();

// Or navigate manually
viewer.nextWaypoint();
viewer.goToWaypoint(2);

// Listen to events
viewer.on('waypointChange', ({ index }) => {
  console.log('Now at waypoint:', index);
});

Volumetric Video (4DGS)

Play back a 4D Gaussian Splat sequence:

import { createViewer } from 'storysplat-viewer';

const viewer = createViewer(container, {
  frameSequence: {
    frameUrls: frameUrls, // Array of frame URLs
    fps: 24,
    loop: true,
  },
});

viewer.play();

Architecture

┌─────────────────────────────────────────────┐
│                 Your App                     │
├─────────────────────────────────────────────┤
│           storysplat-viewer                  │
│  ┌─────────────┐  ┌─────────────────────┐  │
│  │ createViewer │  │ FrameSequencePlayer │  │
│  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────┤
│              PlayCanvas Engine               │
└─────────────────────────────────────────────┘

Browser Support

Browser Version Notes
Chrome 90+ Full support
Firefox 90+ Full support
Safari 15+ Full support
Edge 90+ Full support
Mobile Chrome 90+ Touch controls
Mobile Safari 15+ Touch controls

WebGPU

For best performance, use a browser with WebGPU support. The viewer falls back to WebGL2 automatically.

Next Steps