API Reference
Complete API documentation for the StorySplat Viewer.
createViewerFromSceneId (Recommended)
Creates a viewer by fetching scene data from the StorySplat API. This is the recommended way to embed scenes.
async function createViewerFromSceneId(
container: HTMLElement,
sceneId: string,
options?: ViewerFromSceneIdOptions
): Promise<ViewerInstance>
Parameters
| Parameter | Type | Description |
|---|---|---|
container |
HTMLElement |
DOM element to render the viewer in |
sceneId |
string |
Your StorySplat scene ID |
options |
ViewerFromSceneIdOptions |
Optional viewer settings |
Options
interface ViewerFromSceneIdOptions {
// API configuration
baseUrl?: string; // Default: 'https://discover.storysplat.com'
apiKey?: string; // For private scenes (future)
// Viewer options
autoPlay?: boolean;
showUI?: boolean;
backgroundColor?: string;
revealEffect?: 'fast' | 'medium' | 'slow' | 'none';
lazyLoad?: boolean;
lazyLoadThumbnail?: string;
lazyLoadButtonText?: string;
}
Example
import { createViewerFromSceneId } from 'storysplat-viewer';
const viewer = await createViewerFromSceneId(
document.getElementById('viewer'),
'f8dc96cf-6fc8-4d11-89bb-36c447c0d060',
{ autoPlay: true, revealEffect: 'medium' }
);
fetchSceneMeta
Fetch scene metadata without creating a viewer. Useful for previews and thumbnails.
async function fetchSceneMeta(
sceneId: string,
options?: { baseUrl?: string }
): Promise<SceneMetadata>
Returns
interface SceneMetadata {
name: string;
description: string;
thumbnailUrl: string;
userName: string;
views: number;
tags: string[];
createdAt: string | null;
}
Example
import { fetchSceneMeta } from 'storysplat-viewer';
const meta = await fetchSceneMeta('YOUR_SCENE_ID');
console.log(meta.name, meta.thumbnailUrl);
Error Classes
Handle specific error types when loading scenes:
import {
createViewerFromSceneId,
SceneNotFoundError,
SceneApiError
} from 'storysplat-viewer';
try {
const viewer = await createViewerFromSceneId(container, sceneId);
} catch (error) {
if (error instanceof SceneNotFoundError) {
console.error('Scene not found or not public');
} else if (error instanceof SceneApiError) {
console.error(`API error (${error.statusCode}):`, error.message);
}
}
createViewer
Creates an embedded viewer instance from scene data. Use this for self-hosted scenes.
function createViewer(
container: HTMLElement,
scene: SceneData,
options?: ViewerOptions
): ViewerInstance
Parameters
| Parameter | Type | Description |
|---|---|---|
container |
HTMLElement |
DOM element to render the viewer in |
scene |
SceneData |
Scene configuration |
options |
ViewerOptions |
Optional viewer settings |
Returns
ViewerInstance - The viewer instance with control methods.
createViewerFromUrl
Creates a viewer from a remote scene JSON URL.
function createViewerFromUrl(
container: HTMLElement,
url: string,
options?: ViewerOptions
): Promise<ViewerInstance>
generateHTML
Generates standalone HTML that can be hosted anywhere.
ViewerInstance
The object returned by createViewer.
Properties
| Property | Type | Description |
|---|---|---|
app |
pc.Application |
PlayCanvas application reference |
canvas |
HTMLCanvasElement |
Rendering canvas element |
Navigation Methods
goToWaypoint
Navigate to a specific waypoint by index.
nextWaypoint
Navigate to the next waypoint.
prevWaypoint
Navigate to the previous waypoint.
getCurrentWaypointIndex
Get the current waypoint index.
getWaypointCount
Get the total number of waypoints.
Camera Methods
setPosition
Set the camera position.
getPosition
Get the current camera position.
setRotation
Set the camera rotation (Euler angles in degrees).
getRotation
Get the current camera rotation.
Audio Methods
muteAll
Mute all scene audio (hotspots, waypoints, emitters).
unmuteAll
Unmute all scene audio.
isMuted
Check if audio is currently muted.
Splat Swap Methods
Control which splat is displayed when multiple splats are configured.
goToSplat
Switch to a specific splat by URL. Will preload if not already loaded.
goToOriginalSplat
Return to the original/initial splat.
getCurrentSplatUrl
Get the URL of the currently displayed splat.
isShowingOriginalSplat
Check if showing the original splat.
getAdditionalSplats
Get the list of additional splats available for swapping.
viewer.getAdditionalSplats(): Array<{
url: string;
name?: string;
waypointIndex: number;
percentage: number;
}>
Hotspot Methods
Programmatically interact with hotspots.
getHotspots
Get list of all hotspots in the scene.
viewer.getHotspots(): Array<{
id: string;
title?: string;
type: string;
position: { x: number; y: number; z: number };
}>
triggerHotspot
Open a hotspot popup by ID.
closeHotspot
Close the currently open hotspot popup.
Mode Methods
setCameraMode
Switch between tour and explore mode.
Note
In tour mode, navigation and playback methods are enabled. In explore mode, camera position/rotation methods are enabled.
getCameraMode
Get the current camera mode.
setExploreMode
Switch explore sub-mode (requires explore mode).
Playback Methods
Warning
Playback methods require tour mode. Call setCameraMode('tour') first.
play
Start waypoint or 4DGS playback.
pause
Pause playback.
stop
Stop playback and reset to beginning.
isPlaying
Check if currently playing.
Progress Methods
setProgress
Jump to a specific tour progress (0.0 to 1.0). Requires tour mode.
getProgress
Get the current tour progress.
4DGS Frame Methods
These methods are only available when frameSequence is configured.
setFrame
Jump to a specific frame.
getCurrentFrame
Get the current frame index.
getTotalFrames
Get the total number of frames.
setFps
Change the playback FPS.
getFps
Get the current FPS.
getFrameProgress
Get playback progress (0.0 to 1.0).
setFrameProgress
Set playback progress.
Lifecycle Methods
destroy
Clean up and remove the viewer.
resize
Manually trigger a resize (usually automatic).
Event Methods
on
Subscribe to an event.
off
Unsubscribe from an event.
SceneData
Configuration object for the scene.
interface SceneData {
// Scene metadata
name?: string;
// Splat source (one required)
splatUrl?: string;
sogUrl?: string;
compressedPlyUrl?: string;
fallbackUrls?: string[];
// 4DGS (alternative to splatUrl)
frameSequence?: {
frameUrls: string[];
fps?: number;
loop?: boolean;
preloadCount?: number;
autoplay?: boolean;
};
// Transform
scale?: { x: number; y: number; z: number };
splatScale?: number;
position?: number[];
rotation?: number[];
invertXScale?: boolean;
invertYScale?: boolean;
// Camera
defaultCameraMode?: 'orbit' | 'first-person' | 'drone';
allowedCameraModes?: string[];
cameraMovementSpeed?: number;
cameraRotationSensitivity?: number;
cameraPosition?: number[];
cameraRotation?: number[];
fov?: number;
playerHeight?: number;
// Content
waypoints?: WaypointData[];
hotspots?: HotspotData[];
skybox?: { url: string; rotation?: number };
// UI
uiColor?: string;
uiOptions?: {
showStartExperience?: boolean;
showWatermark?: boolean;
hideFullscreenButton?: boolean;
hideHelpButton?: boolean;
hideMuteButton?: boolean;
};
// Effects
revealEffect?: 'fast' | 'medium' | 'slow' | 'none';
// Navigation
includeScrollControls?: boolean;
autoPlayEnabled?: boolean;
}
ViewerOptions
Options for viewer creation.
interface ViewerOptions {
template?: 'standard' | 'minimal' | 'pro';
autoPlay?: boolean;
showUI?: boolean;
backgroundColor?: string;
revealEffect?: 'fast' | 'medium' | 'slow' | 'none';
}
WaypointData
Configuration for a waypoint.
interface WaypointData {
id?: string;
name?: string;
description?: string;
position?: { x: number; y: number; z: number };
rotation?: { x: number; y: number; z: number };
fov?: number;
duration?: number;
}
HotspotData
Configuration for a hotspot.
interface HotspotData {
id: string;
position: { x: number; y: number; z: number };
type: 'image' | 'video' | 'text' | 'link' | 'audio';
data: any;
scale?: number;
alwaysVisible?: boolean;
}
FrameSequencePlayer
Direct access to the 4DGS frame player (advanced usage).
import { FrameSequencePlayer } from 'storysplat-viewer';
const player = new FrameSequencePlayer(app, {
frameUrls: [...],
fps: 24,
loop: true,
preloadCount: 5,
}, {
onFrameChange: (frame, total) => {},
onLoadProgress: (loaded, total) => {},
onError: (error) => {},
});
// Control methods
player.play();
player.pause();
player.stop();
player.setFrame(10);
player.nextFrame();
player.previousFrame();
// Getters
player.getCurrentFrame();
player.getTotalFrames();
player.getProgress();
player.getIsPlaying();
// Setters
player.setFps(30);
player.setProgress(0.5);
player.setLoop(false);
// Transform (applies to all frames)
player.setPosition(0, 0, 0);
player.setRotation(0, 0, 0);
player.setScale(1, 1, 1);
// Cleanup
player.destroy();