viewing spatials on the web with spatialjs

you've created amazing voxel content with spatialstudio - now it's time to bring those spatials to life on the web! in this tutorial, you'll discover spatialjs, our powerful webassembly-powered javascript library that enables seamless playback of .splv voxel videos in any modern browser.

introducing spatialjs

spatialjs is the web counterpart to spatialstudio, designed specifically for browser environments. while spatialstudio excels at creating voxel content in python, spatialjs brings that content to life on the web with high-performance rendering and interactive controls.

key features:

  • webassembly performance: lightning-fast voxel rendering using wasm
  • universal compatibility: works in all modern browsers without plugins
  • interactive controls: built-in playback controls and javascript api
  • responsive design: adapts to any screen size or container
  • custom elements: easy-to-use <splv-player> html tags

spatialjs is distributed via npm, making integration into modern web projects seamless:

npm install spatial-player

setting up spatialjs in your web project

installation and import

for modern web projects using bundlers like webpack, vite, or next.js:

// Import SpatialJS in your main JavaScript file
import SPLV from 'spatial-player';

// The import automatically registers custom elements:
// <splv-player> and <vv-player> are now available

vanilla html setup

for traditional html projects, you can include spatialjs via cdn:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>my spatial video</title>
</head>
<body>
    <!-- Include SpatialJS -->
    <script src="https://cdn.jsdelivr.net/npm/spatial-player@latest/dist/spatial-player.js"></script>
    
    <!-- Your spatial player will go here -->
</body>
</html>

embedding your first spatial player

let's start with a basic example using the example.splv file you created in the first tutorial:

<!-- Basic Spatial Player -->
<splv-player 
    id="myPlayer"
    src="/path/to/example.splv"
    video-controls="hover"
    style="width: 600px; height: 400px; border-radius: 8px;">
</splv-player>

understanding the attributes

src - the url to your .splv file

  • can be a relative path: src="./spatials/example.splv"
  • or an absolute url: src="https://cdn.example.com/spatials/example.splv"
  • make sure your web server serves .splv files with the correct mime type

video-controls - controls the visibility of playback controls

  • "show": always visible play/pause timeline
  • "hide": no visible controls (programmatic control only)
  • "hover": controls appear when user hovers (recommended for most cases)

javascript playback control

the real power of spatialjs comes from its programmatic control capabilities. once you have a player embedded, you can control it entirely through javascript:

basic playback control

// Get reference to the player element
const playerEl = document.getElementById('myPlayer');

// Play and pause controls
playerEl.set_playing(true);   // Start playing
playerEl.set_playing(false);  // Pause playback

// Volume control (0.0 to 1.0)
playerEl.set_volume(0.5);     // Set to 50% volume
playerEl.set_volume(1.0);     // Full volume
playerEl.set_volume(0.0);     // Mute

// Time seeking (in milliseconds)
playerEl.set_time(2500);      // Seek to 2.5 seconds
playerEl.set_time(0);         // Return to beginning

event-driven programming with callbacks

for advanced interactive applications, spatialjs supports event callbacks that let you respond to player events:

frame decoding callbacks

// Called every time a new frame is decoded and displayed
player.set_callback_frame_decoded((frameNumber) => {
    console.log(`frame ${frameNumber} decoded`);
    
    // Example: Update UI, sync with other elements, etc.
    document.getElementById('frame-counter').textContent = `frame: ${frameNumber}`;
});

video completion callbacks

// Called when the spatial video finishes playing
player.set_callback_spatial_finished(() => {
    console.log('spatial video completed');
    
    // Example: Show replay button, load next video, etc.
    document.getElementById('replay-btn').style.display = 'block';
});

responsive design considerations

make your spatial players work beautifully on all devices:

/* Responsive player styling */
.spatial-container {
    width: 100%;
    max-width: 800px;
    margin: 0 auto;
}

.spatial-container splv-player {
    width: 100%;
    height: 60vw; /* Maintain aspect ratio */
    max-height: 600px;
    min-height: 300px;
}

/* Mobile optimizations */
@media (max-width: 768px) {
    .spatial-container splv-player {
        height: 70vw;
        max-height: 400px;
    }
}

what you've accomplished

congratulations! you now know how to:

  • ✅ embed spatial players in web pages using <splv-player>
  • ✅ configure player appearance with custom attributes
  • ✅ control playback programmatically through javascript
  • ✅ create responsive, professional-looking spatial video experiences
  • ✅ use callbacks for advanced interactive features

your voxel creations can now be shared with the world through immersive web experiences that work across all modern browsers and devices.

what's next?

you've mastered displaying spatials on the web, but what if you want to create voxel content directly in the browser? in our final tutorial, "generating spatials in the browser with spatialjs (advanced)", you'll discover how to use spatialjs's encoding capabilities to create spatial videos entirely client-side using javascript and webassembly.

this advanced technique opens up possibilities for user-generated content, real-time simulations, and interactive voxel applications that generate content on the fly. get ready to explore the cutting edge of browser-based voxel creation!

← encoding basicsnext: browser generation →