Skip to main content

Installation

Add the Flutter package from pub.dev:
The package supports iOS and Android Flutter apps.

License

AvatarKit is proprietary software licensed by SPATIALWALK PTE. LTD. Use is subject to the Spatius Terms of Service. Third-party components retain their own license terms; see the notices included with the SDK.

Import

Initialize

Initialize AvatarKit once before loading avatars or creating an avatar view.
Use DrivingServiceMode.direct for Direct Mode. initialize fails fast when appID is missing, rather than returning silently. Get an App ID from app.spatius.ai.

Device support

Call this before initialization when your app needs to decide whether to show an avatar:
The method returns Future<DeviceSupport> and uses the native rendering and performance checks. Run it while the app is in the foreground. Rendering verification failures or timeouts produce renderNotSupported; valid native cached results are reused. Initialization also starts the native check automatically. Completion of Flutter’s initialize Future means the native initialization request was accepted, not that the asynchronous rendering check finished. If rendering verification fails, native initialization does not complete successfully and logs an error. Use checkDeviceSupport() for an explicit UI decision; there is no separate initialization onError callback.
isDeviceSupported() is deprecated but remains available. It returns true only when the detailed result is DeviceSupport.supported.

Configuration

The audio format is not part of Configuration. Set it per view with AvatarWidget(audioFormat:); see AudioFormat.

RenderQuality

RenderQuality.ultra is the default and highest-quality tier. Use high or standard only when you intentionally trade visual quality for lower rendering cost.
setRenderQuality takes effect on the next rendered frame. Call it after initialize: a call made before is ignored and an error is logged natively, on both iOS and Android. Pass the initial tier as Configuration.renderQuality instead. Calling setRenderQuality turns automatic adjustment off.

Automatic render quality

setAutoRenderQuality lets the SDK lower the render quality one step at a time when the GPU cannot keep up. It is off by default.
  • The SDK judges the load only from frames rendered while the Avatar is idle.
  • Besides the three tiers, the SDK uses one intermediate step between each pair of tiers. onRenderQualityChanged is called only when the reported tier changes, with RenderQualityChangeReason.autoDowngrade or RenderQualityChangeReason.autoUpgrade. It is not called for setRenderQuality.
  • A current tier outside minQuality–maxQuality is moved into that range as soon as automatic adjustment is turned on.
  • A call made before initialize, a loadThreshold outside 0.6–1.0, or a minQuality above maxQuality is ignored and an error is logged natively.
  • autoRenderQualityEnabled() returns a Future<bool>, unlike the native property of the same name.

Render resolution

setRenderResolutionConfig keeps the render buffer height of every avatar view, in physical pixels, within [minHeight, maxHeight]. Aspect ratio and the view’s layout size are unchanged; the system scales the buffer to fit, and the quality tier’s render scale still applies on top. It is off by default.
  • minHeight: a view shorter than this renders at minHeight and is scaled down. Small views render noticeably sharper, at extra GPU cost.
  • maxHeight: a view taller than this renders at maxHeight and is scaled up, which saves GPU work on high-density screens.
  • A bound left null is not applied.
  • A non-positive bound, or a minHeight above maxHeight, makes the call ignored: an error is logged natively and the current setting is kept.
  • renderResolutionEnabled() and renderResolutionConfig() are methods that return a Future, unlike the native properties of the same names.
Deprecated: AvatarSDK.setRenderResolutionCap({required bool enabled, int maxHeight = 1440}). Use setRenderResolutionConfig(enabled: enabled, config: RenderResolutionConfig(maxHeight: maxHeight)) instead. It keeps working and will be removed in the next GA release. A non-positive maxHeight is ignored and an error is logged.

AudioFormat

Each avatar view has its own audio format, so two views in one app can run different sample rates. Pass it to AvatarWidget(audioFormat:) when you create the view; it defaults to 16 kHz PCM. The value is used when the native view is created, so changing the widget property afterwards has no effect. Use AvatarController.setAudioFormat to change it at runtime.
Audio that does not match the declared inputAudioFormat is reported through AvatarController.onError as AvatarError.invalidAudioInput. AudioFormat has value equality and converts with toJson() / AudioFormat.fromJson().

Change the audio format at runtime

Read the format in effect for a view with controller.audioFormat(). It returns the format after the SDK’s normalization, for example 48000 Hz for Opus input.
setAudioFormat({sampleRate, inputAudioFormat, opusBitrate, opusUplinkEnabled}) changes the format of a live view without tearing the SDK down. Every parameter is optional; null keeps the current value.
  • Any change interrupts whatever is playing and, in Direct Mode, disconnects. Call start() again and feed audio in the new format.
  • Switching inputAudioFormat to AudioCodec.opus pins the sample rate at 48000. Switching back to AudioCodec.pcm keeps the current rate unless you pass sampleRate in the same call.
  • Accepted sample rates are 8000, 16000, 22050, 24000, 32000, 44100, and 48000. An unsupported rate, or a sampleRate paired with Opus input, is logged by the SDK and leaves the format unchanged.

Load an avatar

To create an Avatar from a local asset path instead, use derive. Await completion before constructing AvatarWidget; the native SDK prepares the required shared template and downloads it if needed. A known SDK error raised during load or derive is thrown as a Flutter AvatarError value; any other failure is thrown as a PlatformException. derive throws AvatarError.avatarAssetMissing on both iOS and Android when the asset is missing.

Render and control playback

The Flutter view creates an AvatarController when the platform view is ready. Keep that controller and use it for lifecycle, state, and audio operations.
AvatarError is an enum, so a switch over it without a default case must list every value. AvatarError.renderBlankCanvas is reported through onError when the view reported its first frame, but one second later nothing visible had been drawn. It is reported at most once per view; an Avatar moved entirely out of the view or scaled to nothing by its transform is reported the same way.

Render over an Avatar Background

Download the optional 16:9 background from Spatius Studio, add it to your Flutter assets, and declare it in pubspec.yaml.
Place the background and AvatarWidget in the same Stack, with the image first.
For square or portrait display windows, center this 16:9 stage inside a clipped outer widget. See Avatar Background for the shared cropping rules. For Direct Mode audio input, start the connection and send PCM chunks:
For audio source and timing guidance, see Audio.

Demos

Flutter Direct Mode demo