Installation
Add the Flutter package from pub.dev: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.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: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.
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.
onRenderQualityChangedis called only when the reported tier changes, withRenderQualityChangeReason.autoDowngradeorRenderQualityChangeReason.autoUpgrade. It is not called forsetRenderQuality. - A current tier outside
minQuality–maxQualityis moved into that range as soon as automatic adjustment is turned on. - A call made before
initialize, aloadThresholdoutside 0.6–1.0, or aminQualityabovemaxQualityis ignored and an error is logged natively. autoRenderQualityEnabled()returns aFuture<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 atminHeightand is scaled down. Small views render noticeably sharper, at extra GPU cost.maxHeight: a view taller than this renders atmaxHeightand is scaled up, which saves GPU work on high-density screens.- A bound left
nullis not applied. - A non-positive bound, or a
minHeightabovemaxHeight, makes the call ignored: an error is logged natively and the current setting is kept. renderResolutionEnabled()andrenderResolutionConfig()are methods that return aFuture, unlike the native properties of the same names.
AudioFormat
Each avatar view has its own audio format, so two views in one app can run different sample rates. Pass it toAvatarWidget(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 withcontroller.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
inputAudioFormattoAudioCodec.opuspins the sample rate at 48000. Switching back toAudioCodec.pcmkeeps the current rate unless you passsampleRatein the same call. - Accepted sample rates are 8000, 16000, 22050, 24000, 32000, 44100, and 48000. An unsupported rate, or a
sampleRatepaired with Opus input, is logged by the SDK and leaves the format unchanged.
Load an avatar
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 anAvatarController 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 inpubspec.yaml.
AvatarWidget in the same Stack, with the image first.

