# Embedding the Viewer

The [SuperSplat Viewer](https://developer.playcanvas.com/user-manual/supersplat/viewer.md) is published on npm as [`@playcanvas/supersplat-viewer`](https://www.npmjs.com/package/@playcanvas/supersplat-viewer). It's a self-contained static web app you can drop into your own site, point at any splat file, and configure via URL parameters or a JSON settings document.

## Installing

```bash
npm install @playcanvas/supersplat-viewer
```

The package exports the viewer's `index.html`, `index.css`, and `index.js` as strings, ready to template into your build pipeline:

```ts
import { html, css, js } from '@playcanvas/supersplat-viewer';

// The full markup of the viewer page
console.log(html);

// The viewer's stylesheet
console.log(css);

// The viewer's compiled JS bundle
console.log(js);
```

This is the same machinery the [Editor's HTML export](https://developer.playcanvas.com/user-manual/supersplat/viewer/self-hosting.md) uses internally to produce a single-file viewer. Use it when you want to build your own templated bundle — e.g. injecting a particular `settings.json`, swapping in a custom skybox, or replacing the default poster image — without paying the runtime cost of loading the viewer from a CDN.

## URL parameters

If you'd rather host the viewer's built files yourself and configure each instance through query parameters, the following are supported:

| Parameter | Description | Default |
| --------- | ----------- | ------- |
| `settings` | URL of the [Experience Settings](https://developer.playcanvas.com/user-manual/supersplat/studio/experience-settings.md) JSON file | `./settings.json` |
| `content` | URL of the scene file (`.ply`, `.sog`, `.meta.json`, `.lod-meta.json`, `.compressed.ply`) | `./scene.compressed.ply` |
| `skybox` | URL of an equirectangular skybox image | _(none)_ |
| `poster` | URL of an image to show while the scene loads | _(none)_ |
| `noui` | Hide the viewer's built-in UI | _(off)_ |
| `noanim` | Start with any animation track paused | _(off)_ |
| `ministats` | Show runtime CPU/GPU performance graphs | _(off)_ |
| `unified` | Force [unified rendering](https://developer.playcanvas.com/user-manual/gaussian-splatting/rendering-architecture.md) | _(off)_ |
| `aa` | Enable antialiasing (not supported in unified mode) | _(off)_ |

These flags are subject to change as the viewer evolves; check the [project README](https://github.com/playcanvas/supersplat-viewer#readme) for the current set.

## Settings JSON

The `settings` URL parameter points at an [Experience Settings](https://developer.playcanvas.com/user-manual/supersplat/studio/experience-settings.md) v2 document — the same JSON format [Studio](https://developer.playcanvas.com/user-manual/supersplat/studio.md) saves whenever you hit Save. See the [Experience Settings reference](https://developer.playcanvas.com/user-manual/supersplat/studio/experience-settings.md) for the full schema, defaults, and migration notes.

A complete minimal `settings.json` (every field the v2 schema requires, populated with the defaults the [Studio](https://developer.playcanvas.com/user-manual/supersplat/studio.md) emits for a fresh scene):

```json
{
  "version": 2,
  "tonemapping": "linear",
  "highPrecisionRendering": false,
  "background": {
    "color": [0, 0, 0]
  },
  "postEffectSettings": {
    "sharpness": { "enabled": false, "amount": 0 },
    "bloom":     { "enabled": false, "intensity": 0.1, "blurLevel": 2 },
    "grading":   { "enabled": false, "brightness": 1, "contrast": 1, "saturation": 1, "tint": [1, 1, 1] },
    "vignette":  { "enabled": false, "intensity": 0.5, "inner": 0.3, "outer": 0.75, "curvature": 1 },
    "fringing":  { "enabled": false, "intensity": 0.5 }
  },
  "cameras": [
    { "initial": { "position": [0, 1, -1], "target": [0, 0, 0], "fov": 75 } }
  ],
  "animTracks": [],
  "annotations": [],
  "startMode": "default"
}
```

For full coverage of every field — post effects parameters, annotations, animation keyframes, tonemapping options, etc. — see the [Experience Settings](https://developer.playcanvas.com/user-manual/supersplat/studio/experience-settings.md) reference.

## Programmatic publishing

If you want to publish splats and update their settings without going through the Editor or Studio UIs, the [Splat Publishing API](https://developer.playcanvas.com/user-manual/api/splat-publish/) exposes the underlying REST endpoints.

## See also

- [SuperSplat Viewer overview](https://developer.playcanvas.com/user-manual/supersplat/viewer.md) — what the viewer is and when to reach for it
- [Self-Hosting](https://developer.playcanvas.com/user-manual/supersplat/viewer/self-hosting.md) — single-file HTML export from the Editor
- [Experience Settings](https://developer.playcanvas.com/user-manual/supersplat/studio/experience-settings.md) — the JSON contract the viewer reads
- [Splat Publishing API](https://developer.playcanvas.com/user-manual/api/splat-publish/) — REST endpoints for programmatic publishing