AvatarKit v1.3.4

Internal telemetry only — no changes to the public API or runtime behaviour.

Added

• The SDK now checks, one second after the first frame is reported as rendered, whether the view actually has anything on it, and reports a diagnostic when it is completely blank. Some devices pass the capability check and still render nothing; until now that failure was silent on our side and only surfaced as a user complaint. Costs a few milliseconds once per session and never blocks rendering.

Changed

• Diagnostics are now sent to a collection gateway instead of the storage backend directly, and the SDK no longer carries any credentials for that backend. Credentials shipped inside a redistributed SDK are readable by anyone who receives it.
• Diagnostic records now carry the client environment fields that the Web SDK has always included, so records from all three platforms line up field for field.
• Updated the bundled analytics dependency. It fixes a queue defect that could re-send events already delivered, and a regression present since its 3.0 release where the Wi-Fi-only sending mode was ignored and pending events were not flushed when the network came back.

Fixed

• End-to-end latency is now reported when the host application supplies the motion data, not only when the SDK connects to the driving service itself. The measurements were being taken in both cases and discarded in one of them.

Install

Swift Package Manager

.package(url: "https://github.com/spatius-ai/avatarkit-ios-release.git", from: "1.3.4")

CocoaPods

pod 'SpatiusAvatarKit', '1.3.4'

Pod page: https://cocoapods.org/pods/SpatiusAvatarKit

Compatibility

• iOS 16.0+
• Swift 6.2 / Xcode 16+
• Binary: AvatarKit.xcframework（ios-arm64 + ios-arm64-simulator，simulator slice 为 arm64-only）

AvatarKit v1.3.3

Internal telemetry improvements only. No changes to the public API or runtime behaviour.

See CHANGELOG.md for details.

AvatarKit v1.3.3-beta.1

Internal telemetry only — no public API or runtime behaviour changes.

• Avatar-loading and connection timings are now reported for failed attempts as well, each tagged with what went wrong. They were previously only sent on success, so the data could not tell a healthy integration apart from one where every load was failing. HTTP status codes alone could not fill the gap — this is what hid the earlier "Avatar data is invalid" incident, where the server answered 200 and decoding failed afterwards, leaving the request success rate at 100% throughout.
• Motion data received in .host mode now continues the trace started upstream, so one round of playback reads as a single trace end to end instead of two unrelated ones.

v1.3.2

修复 avatar 加载耗时上报缺失一段的问题（load_avatar 链路中 fetch_metadata 段被归到错误的记录下）。仅影响诊断数据，SDK 行为无变化。

SPM checksum: cf0a2a3166f7648a038a864f08c72837f1b84d5c06bcdd7adf338d55d56b3a0e

AvatarKit v1.3.1

Rolls up everything from the 1.3.1 beta line.

Added

• Opus audio support. AudioFormat.inputAudioFormat (.pcm default, or .opus) declares the format the host feeds into the SDK via send/yieldAudioData; .opus input is decoded back to PCM16 for local rendering and forwarded upstream as-is in direct mode. AudioFormat.opusBitrate tunes the target bitrate. Only effective in direct mode.

• DrivingServiceMode.rtc. Only for integrations that drive the avatar through the companion RTC SDK — if you are not using that package, keep .direct or .host as before. It is a reporting dimension and unlocks no API: RTC drives the avatar frame by frame through the existing rendering entry points, so runtime behaviour is unchanged either way.

  .package(url: "https://github.com/spatius-ai/avatarkit-ios-rtc.git", exact: "1.0.0-beta.6")

  Integration guide: https://docs.spatius.ai/

• Synchronous rendering entry points on AvatarView, for callers driven by an external frame clock: renderFrameSync(_:startIdle:), renderFromProtobufSync(_:) and generateTransitionToFrameSync(...). They behave like their async counterparts but have no suspension points, so consecutive frames keep their call order. The async versions remain available and unchanged.

Changed

• The direct-mode uplink now compresses audio to Opus by default (AudioFormat.opusUplinkEnabled, previously off). It cuts the upload to roughly 1/8 at the cost of client-side encoding, which matters most on the mobile networks where stalls actually happen. Pass opusUplinkEnabled: false to keep the raw PCM uplink. Unchanged for host mode (no uplink) and for .opus input (already compressed). If the configured sampleRate is not one of Opus's supported rates, the SDK logs a warning and falls back to raw PCM.
• Opus uplink encoding now streams: each second of audio is sent as soon as it is encoded, instead of waiting for the whole chunk to finish. When a host hands over a long utterance in one call, the first packet used to wait out the entire encode; playback now starts noticeably sooner.
• The region configuration now defaults to automatic selection: when left unset, the SDK picks the closest serving region at initialization. With nothing cached yet the first launch waits for the lookup; afterwards the cached region is used right away and refreshed in the background, taking effect on the next launch. An explicitly configured region continues to take precedence.
• initialize with a missing appID now fails fast instead of returning silently, matching Android. The accompanying message points to https://app.spatius.ai/ to obtain an app ID.

Fixed

• Idle animation no longer stops while the first animation frames of a round are still in flight, which could leave the avatar visibly frozen at the start of playback.
• In region: auto, the socket URL is now built per connection, so a session started before region resolution settled connects to the resolved region instead of the fallback one.
• The warning logged when animation falls behind audio now states what happened and what to do about it (feed audio at roughly twice real time), instead of the previous message that gave neither.

Removed

• Breaking: the per-call audioFormat parameter of AvatarController.yieldAudioData is gone; the signature is now yieldAudioData(_:end:). The audio format is taken from Configuration.audioFormat passed to AvatarSDK.initialize, which is also what the inputAudioFormat setting requires. Host-mode callers that passed a per-call format must drop the argument and set the format at initialization instead.

AvatarKit v1.3.1-beta.2

AvatarKit iOS SDK v1.3.1-beta.2 (pre-release).

• DrivingServiceMode.rtc, for integrations driven through the companion RTC SDK (reporting dimension; unlocks no API).
• Synchronous rendering entry points on AvatarView (renderFrameSync / renderFromProtobufSync / generateTransitionToFrameSync), for callers driven by an external frame clock.
• region auto-selection now uses the cached region immediately and refreshes in the background; a refreshed region applies on the next launch.
• Idle animation no longer stops while a round's first animation frames are still in flight.
• region: auto now builds the socket URL per connection, so sessions started before resolution settles reach the resolved region.
• Clearer warning when animation falls behind audio.

Binary: self-contained AvatarKit.xcframework (ios-arm64 + ios-arm64-simulator, arm64-only simulator slice).

AvatarKit v1.3.1-beta.1

AvatarKit iOS SDK v1.3.1-beta.1 (pre-release).

• Opus audio input support (AudioFormat.inputAudioFormat / opusUplinkEnabled / opusBitrate).
• region auto-selection by default.
• opusUplink sample-rate fallback; appID fail-fast.
• Telemetry alignment across platforms (internal).

Binary: self-contained AvatarKit.xcframework (ios-arm64 + ios-arm64-simulator, arm64-only simulator slice).

AvatarKit v1.3.0

Body-fixation / non-body-fixation avatar split (aligned with Web/Android), and a fail-fast AvatarError.incompatibleAvatarAsset pre-flight when an asset requires a newer SDK. See CHANGELOG for details.

AvatarKit v1.2.0

AvatarKit v1.2.0

First stable 1.2 release. No public API changes since 1.2.0-beta.1.

Fixed

• Fixed a crash when audio playback was interrupted by the system (e.g. an incoming phone call): the player node's IO layer could be torn down mid-schedule, raising an NSException. Such interruptions are now handled gracefully instead of crashing the app.
• Fixed local derive(assetPath:) rejecting valid assets whose optional fields (such as transform) were absent or null. Such assets are now accepted, matching the network loading path. Genuinely incompatible (legacy/corrupt) assets still throw AvatarError.incompatibleAvatarAsset.

AvatarKit v1.2.0-beta.1

AvatarKit v1.2.0-beta.1

Added

• Configurable frame-starvation handling: FrameStarvationMode (.audioIndependent default / .strictSync), AvatarController.frameStarvationMode, AvatarController.onPlaybackStall.
• New AvatarError.incompatibleAvatarAsset for unsupported (legacy) local asset formats.

Changed

• Avatars now load via the latest avatar asset format.

Fixed

• Backend mode: animation now stops together with the audio (no extra movement after audio ends).
• Direct mode: pre-connection audio is buffered and replayed once the session is confirmed (fixes mouth lagging the voice after fallback recovery).

Breaking Changes

• Local derive(assetPath:) accepts only the latest avatar asset format; legacy local assets throw AvatarError.incompatibleAvatarAsset. Re-download assets from the developer platform.