Direct Mode Integration for Web

What is Direct Mode for Web?

Direct Mode for Web is the simplest way to put a Spatius avatar in a browser app. @spatius/avatarkit connects directly to Motion Server, sends avatar speech audio, and renders motion locally — no agent worker or relay backend needed beyond a Session Token endpoint.

When to use

You have or generate avatar speech audio in the browser — your own TTS output, prerecorded clips, or agent audio fetched server-side.
You want the smallest backend footprint: a single Session Token endpoint.
You want the client to own rendering and don’t need backend-controlled audio or transport.

Run the demo

Web SDK quickstart

One quickstart with bundled sample audio plus optional realtime conversation.

Multi-framework reference

React, Vue, vanilla JavaScript, and Next.js reference clients.

Install

pnpm
npm
yarn

pnpm add @spatius/avatarkit

npm install @spatius/avatarkit

yarn add @spatius/avatarkit

Build tool configuration

Required: The SDK uses WASM files that need special build configuration. Configure your build tool before initializing the SDK, or .wasm requests will fail.

Vite
Next.js

Add the official plugin to vite.config.ts:

vite.config.ts

import { defineConfig } from 'vite'
import { avatarkitVitePlugin } from '@spatius/avatarkit/vite'

export default defineConfig({
  plugins: [
    avatarkitVitePlugin(),
  ],
})

What the plugin handles

Dev server: serves .wasm files with the correct MIME type
Build: copies WASM files to dist/assets/
Cloudflare Pages: generates a _headers file
Vite options: configures optimizeDeps, assetsInclude, assetsInlineLimit

Manual Vite configuration (without the plugin)

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    exclude: ['@spatius/avatarkit'],
  },
  assetsInclude: ['**/*.wasm'],
  build: {
    assetsInlineLimit: 0,
    rollupOptions: {
      output: {
        assetFileNames: (assetInfo) => {
          if (assetInfo.name?.endsWith('.wasm')) {
            return 'assets/[name][extname]'
          }
          return 'assets/[name]-[hash][extname]'
        },
      },
    },
  },
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      if (req.url?.endsWith('.wasm')) {
        res.setHeader('Content-Type', 'application/wasm')
      }
      next()
    })
  },
})

Wrap your config in next.config.mjs:

next.config.mjs

import { withAvatarkit } from '@spatius/avatarkit/next'

export default withAvatarkit({
  // ...your existing Next.js config
})

What the wrapper handles

Asset paths: patches Emscripten scriptDirectory to resolve from /_next/static/chunks/
WASM copy: copies .wasm files into static/chunks/ (client build only)
Response headers: adds application/wasm for /_next/static/chunks/*.wasm
Config chaining: preserves your existing webpack and headers configuration

Composing with other config wrappers

next.config.mjs

import { withAvatarkit } from '@spatius/avatarkit/next'
import withOtherPlugin from 'other-plugin'

export default withAvatarkit(withOtherPlugin({
  // ...your config
}))

For deeper toolchain explanation, see Toolchain Setup.

Minimum integration

The smallest end-to-end flow with @spatius/avatarkit:

Initialize the SDK

import { AvatarSDK, DrivingServiceMode } from '@spatius/avatarkit'

await AvatarSDK.initialize('your-app-id', {
  region: 'us-west',                             // optional, default: closest region
  drivingServiceMode: DrivingServiceMode.direct, // default
})

AvatarSDK.setSessionToken('your-session-token')

Load the avatar

import { AvatarManager } from '@spatius/avatarkit'

const avatar = await AvatarManager.shared.load('your-avatar-id', (progress) => {
  // progress.progress is in 0..1; multiply by 100 to render as a percentage.
  const percent = Math.round((progress.progress ?? 0) * 100)
  console.log(`Loading: ${percent}%`)
})

Mount the view

import { AvatarView } from '@spatius/avatarkit'

// Container must have non-zero width and height.
const container = document.getElementById('avatar-container')!
const avatarView = new AvatarView(avatar, container)

Initialize audio (inside a user gesture)

initializeAudioContext() must be called inside a user-gesture handler (a click, touchstart, or similar listener). Browsers reject AudioContext creation outside user gestures and the call fails silently.

button.addEventListener('click', async () => {
  await avatarView.controller.initializeAudioContext()
})

Connect and send audio

import { ConnectionState } from '@spatius/avatarkit'

await avatarView.controller.start()

await new Promise<void>((resolve, reject) => {
  avatarView.controller.onConnectionState = (state) => {
    if (state === ConnectionState.connected) resolve()
    else if (state === ConnectionState.failed) reject(new Error('Connection failed'))
  }
})

// Stream PCM16 mono audio at the configured sample rate (default 16 kHz)
avatarView.controller.send(audioChunk, /* end */ false)

// Mark end of the conversation round
avatarView.controller.send(lastChunk, /* end */ true)

For audio source and timing guidance, see Audio.

Cleanup

avatarView.controller.close()
avatarView.dispose()

For full API signatures, types, audio format details, lifecycle management, error codes, browser compatibility, and common issues, see Web SDK Reference.

Next steps

Web SDK reference

Complete Web SDK API: AvatarSDK, AvatarManager, AvatarView, AvatarController, types, errors.

Browse all demos

Every runnable demo by platform and integration path.

Start Here

Quickstarts

Platform Integrations

Standalone Integrations

Concepts

Examples & Support

Direct Mode Integration for Web

What is Direct Mode for Web?

When to use

Run the demo

Web SDK quickstart

Multi-framework reference

Install

Build tool configuration

Minimum integration

Next steps

Web SDK reference

Browse all demos

​What is Direct Mode for Web?

​When to use

​Run the demo

Web SDK quickstart

Multi-framework reference

​Install

​Build tool configuration

​Minimum integration

​Next steps

Web SDK reference

Browse all demos

What is Direct Mode for Web?

When to use

Run the demo

Install

Build tool configuration

Minimum integration

Next steps