Skip to content

Installation

Detailed installation instructions for all StorySplat components.

StorySplat Viewer (npm package)

Package Manager

npm install storysplat-viewer

yarn add storysplat-viewer

pnpm add storysplat-viewer

CDN

For quick prototyping or static sites:

<!-- UMD build (global variable) -->
<script src="https://unpkg.com/storysplat-viewer@latest/dist/storysplat-viewer.umd.js"></script>
<script>
  const { createViewer } = StorySplatViewer;
</script>

<!-- ES Module -->
<script type="module">
  import { createViewer } from 'https://unpkg.com/storysplat-viewer@latest/dist/index.esm.js';
</script>

TypeScript Support

TypeScript definitions are included automatically. No additional packages needed.

import {
  createViewer,
  type SceneData,
  type ViewerInstance,
  type ViewerOptions
} from 'storysplat-viewer';

StorySplat Tools (Desktop App)

Download

Download the latest version for your platform:

Platform Download
Windows StorySplat-Tools-Setup.exe
macOS (Intel) StorySplat-Tools-x64.dmg
macOS (Apple Silicon) StorySplat-Tools-arm64.dmg
Linux StorySplat-Tools.AppImage

Windows Installation

  1. Download the installer
  2. Run StorySplat-Tools-Setup.exe
  3. Follow the installation wizard
  4. Launch from Start Menu or Desktop shortcut

macOS Installation

  1. Download the .dmg file for your Mac type
  2. Open the DMG and drag StorySplat Tools to Applications
  3. First launch: Right-click → Open (to bypass Gatekeeper)
  4. Grant permissions when prompted (camera, file access)

Linux Installation

# Make AppImage executable
chmod +x StorySplat-Tools.AppImage

# Run
./StorySplat-Tools.AppImage

Python Environment (for AI Features)

StorySplat Tools uses Python for image-to-splat conversion. The app manages this automatically, but here's what happens:

Automatic Setup

On first use of AI features:

  1. App detects if Python 3.10+ is available
  2. Creates isolated virtual environment
  3. Installs required packages (PyTorch, etc.)
  4. Downloads AI models on first use

Manual Python Installation

If Python isn't detected:

# Install Python 3.11 (recommended)
winget install Python.Python.3.11

# Using Homebrew
brew install python@3.11

# Ubuntu/Debian
sudo apt install python3.11 python3.11-venv

# Fedora
sudo dnf install python3.11

NVIDIA CUDA Support

For GPU-accelerated processing:

  1. Install NVIDIA drivers for your GPU
  2. StorySplat Tools will detect CUDA capability
  3. If PyTorch CUDA isn't working, use the "Reinstall with CUDA" button in Settings

CUDA Requirements

  • NVIDIA GPU with CUDA Compute Capability 3.5+
  • CUDA Toolkit 11.8 or 12.x (handled by PyTorch)
  • Python 3.11 recommended for best CUDA compatibility

CLI Tools (@storysplat/splat-tools)

Global Installation

npm install -g @storysplat/splat-tools

One-off Usage (npx)

npx @storysplat/splat-tools <command>

Verify Installation

splat-tools --version
splat-tools --help

Troubleshooting

Viewer Issues

"WebGL not supported"

  • Update your browser to the latest version
  • Check if hardware acceleration is enabled
  • Try a different browser

Splat not loading

  • Check browser console for CORS errors
  • Verify the splat URL is accessible
  • Ensure your server sends correct CORS headers

Tools Issues

"Python not found"

  • Install Python 3.10 or newer
  • Ensure Python is in your system PATH
  • Restart StorySplat Tools after installing Python

"PyTorch CUDA not available"

  1. Check that you have an NVIDIA GPU
  2. Install/update NVIDIA drivers
  3. Click "Reinstall with CUDA" in Settings
  4. If using Python 3.12+, ensure latest PyTorch version

AI model download fails

  • Check internet connection
  • Verify firewall isn't blocking downloads
  • Try using a VPN if in a restricted region

Getting Help