Viewer Commands

Commands let your page drive the viewer — play, pause, change quality, jump to an annotation, push a fresh session token. Whether you're using the SDK or sending raw postMessage calls, the surface is the same.

With the SDK

The SDK returns a ViewerHandle from Moshpit.viewer(...). Every method below dispatches a command:

JavaScript

const viewer = Moshpit.viewer('#moshpit-viewer', {
  publicKey: 'mpk_...',
  sessionEndpoint: '/api/moshpit/viewer-session',
  splatId: 'YOUR_SPLAT_ID',
});
 
viewer.on('ready', () => {
  viewer.play();
  viewer.setQuality('high');
  viewer.goToAnnotation(2);
});

Command reference

Command	SDK signature	What it does
`play`	`viewer.play()`	Start animation playback (autoplay)
`pause`	`viewer.pause()`	Pause animation playback
`mute`	`viewer.mute()`	Mute the viewer's audio
`unmute`	`viewer.unmute()`	Unmute the viewer's audio
`fullscreen`	`viewer.fullscreen()`	Request fullscreen on the iframe
`setQuality`	`viewer.setQuality(quality)`	Force a render-quality preset
`goToAnnotation`	`viewer.goToAnnotation(index)`	Move the camera to the annotation at `index`
`updateSession`	(see below)	Replace the active session token without reloading the iframe

`setQuality(quality)`

quality is one of 'auto', 'high', 'medium', 'low'. The named presets apply the Scene's saved settings for the detected device family: desktop, mobile, or iOS. For LOD Scenes, these settings control the detail range, point budget, and rendering resolution. Their visible difference depends on the Scene's saved presets and available detail levels.

'auto' restores the viewer's default preset, currently Medium. It uses the saved settings for the detected device family; it does not continuously adjust quality based on FPS.

Call setQuality after the viewer emits ready. Quality changes preserve the camera view and take effect in the running viewer without reloading the iframe or replaying the intro animation. The viewer's built-in Low, Medium, and High controls use the same quality handler as the SDK command.

`goToAnnotation(index)`

index is the zero-based position of an annotation in the splat's annotation list. If the index is out of range, the call is ignored.

Without the SDK

Send the same commands as postMessage payloads. Always use the explicit Moshpit origin — never '*':

JavaScript

const iframe = document.getElementById('moshpit-viewer');
 
iframe.contentWindow.postMessage(
  {
    source: 'moshpit-sdk',
    type: 'command',
    target: 'viewer',
    command: 'play',
  },
  'https://moshpit.studio',
);

For commands that take a value (setQuality, goToAnnotation, updateSession), put the value in the value field:

JavaScript

iframe.contentWindow.postMessage(
  {
    source: 'moshpit-sdk',
    type: 'command',
    target: 'viewer',
    command: 'setQuality',
    value: 'high',
  },
  'https://moshpit.studio',
);
 
iframe.contentWindow.postMessage(
  {
    source: 'moshpit-sdk',
    type: 'command',
    target: 'viewer',
    command: 'updateSession',
    value: { sessionToken: 'NEW_TOKEN', expiresAt: '2026-05-08T13:30:00Z' },
  },
  'https://moshpit.studio',
);

The full message envelope and origin rules are documented at PostMessage Protocol.

What's next

Viewer Events — what comes back from the iframe.
SDK Options — what you pass when creating the viewer.

Next.js Integration

Events