Golang SDK

The Go SDK creates Spatius avatar sessions from backend services. It requests a short-lived session token from the Console API, opens the ingress WebSocket, sends audio, and returns motion data payloads through callbacks.

Install

go get github.com/spatius-ai/spatius-sdk-go

Repository: spatius-ai/spatius-sdk-go

Quick start

package main

import (
	"context"
	"log"
	"time"

	spatius "github.com/spatius-ai/spatius-sdk-go"
)

func main() {
	ctx := context.Background()

	session := spatius.NewAvatarSession(
		spatius.WithAPIKey("your-api-key"),
		spatius.WithAppID("your-app-id"),
		spatius.WithAvatarID("your-avatar-id"),
		spatius.WithExpireAt(time.Now().Add(5*time.Minute).UTC()),
		spatius.WithTransportFrames(func(data []byte, last bool) {
			// Handle motion data payloads.
		}),
		spatius.WithOnError(func(err error) {
			// Handle async session errors.
		}),
		spatius.WithOnClose(func() {
			// Handle connection close.
		}),
	)

	if err := session.Init(ctx); err != nil {
		log.Fatal(err)
	}
	defer session.Close()

	connectionID, err := session.Start(ctx)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("connection id: %s", connectionID)

	audioBytes := []byte{} // Replace with mono PCM audio bytes.
	reqID, err := session.SendAudio(audioBytes, true)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("request id: %s", reqID)
}

Region configuration

The SDK defaults to us-west when no region is provided, or when WithRegion receives an empty or whitespace-only value. See Regions for the current region list. To set a region:

session := spatius.NewAvatarSession(
	spatius.WithRegion("us-west"),
)

Session lifecycle

Create a session with NewAvatarSession.
Call Init(ctx) to exchange the API key and expiry time for a session token.
Call Start(ctx) to open the ingress WebSocket and configure the avatar session.
Call SendAudio(audio, end) for each audio chunk.
Call Interrupt() when playback should stop.
Call Close() when the session is done.

SendAudio returns the request ID associated with the audio. The callback passed to WithTransportFrames receives motion data payloads and a last flag. For audio source and timing guidance, see Audio.

Audio format

PCM 16-bit little-endian is the default input format:

session := spatius.NewAvatarSession(
	spatius.WithSampleRate(24000),
	spatius.WithAudioFormat(spatius.AudioFormatPCMS16LE),
)

The SDK also supports Ogg Opus sessions:

session := spatius.NewAvatarSession(
	spatius.WithAudioFormat(spatius.AudioFormatOggOpus),
	spatius.WithSampleRate(24000),
	spatius.WithBitrate(32000),
	spatius.WithOggOpusEncoder(nil),
)

Passing nil to WithOggOpusEncoder enables the default encoder config.

Authentication mode

By default, WebSocket authentication is sent in headers:

session := spatius.NewAvatarSession(
	spatius.WithUseQueryAuth(false),
)

For web-style query authentication, enable:

session := spatius.NewAvatarSession(
	spatius.WithUseQueryAuth(true),
)

LiveKit egress

Use LiveKit egress when Spatius should publish avatar output directly into a LiveKit room:

session := spatius.NewAvatarSession(
	spatius.WithLiveKitEgress(&spatius.LiveKitEgressConfig{
		URL:         "wss://your-livekit-server.com",
		APIToken:    "livekit-access-token",
		RoomName:    "room-name",
		PublisherID: "avatar-publisher",
		ExtraAttributes: map[string]string{
			"role": "avatar",
		},
		IdleTimeout: 60,
	}),
)

Prefer APIToken for new integrations. APIKey and APISecret remain available for older setups.

Options

Core options:

WithAPIKey(apiKey string) - Console API key.
WithAppID(appID string) - application ID.
WithAvatarID(avatarID string) - avatar ID.
WithExpireAt(expireAt time.Time) - session token expiry.
WithRegion(region string) - region used to select the Spatius region. Empty or whitespace-only values fall back to us-west.
WithConsoleEndpointURL(endpointURL string) - explicit Console API URL.
WithIngressEndpointURL(endpointURL string) - explicit ingress WebSocket URL.

Audio options:

WithSampleRate(sampleRate int) - input sample rate in Hz.
WithBitrate(bitrate int) - target bitrate for encoded sessions.
WithAudioFormat(audioFormat AudioFormat) - AudioFormatPCMS16LE or AudioFormatOggOpus.
WithOggOpusEncoder(config *OggOpusEncoderConfig) - enable client-side PCM to Ogg Opus encoding.

Callbacks:

WithTransportFrames(func([]byte, bool)) - receives motion data payloads.
WithOnEncodedAudio(func(string, []byte)) - receives internally encoded audio by request ID.
WithOnError(func(error)) - receives async session errors.
WithOnClose(func()) - runs when the session closes.

Egress options:

WithLiveKitEgress(config *LiveKitEgressConfig) - stream output to LiveKit.
WithAgoraEgress(config *AgoraEgressConfig) - stream output to Agora.

Changelog

See GitHub releases.

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Codes

Install

Quick start

Region configuration

Session lifecycle

Audio format

Authentication mode

LiveKit egress

Options

Changelog

​Install

​Quick start

​Region configuration

​Session lifecycle

​Audio format

​Authentication mode

​LiveKit egress

​Options

​Changelog

Install

Quick start

Region configuration

Session lifecycle

Audio format

Authentication mode

LiveKit egress

Options

Changelog