@spatius/avatarkit 1.3.1-beta.6 → 1.3.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-08-07
+
+Rolls up everything from the 1.3.1 beta line.
+
+### Added
+- `DrivingServiceMode.rtc`. Use it **only** when driving the avatar through the companion RTC SDK, `@spatius/avatarkit-rtc`; on `direct` / `backend` nothing changes. It is a telemetry dimension and unlocks no API — declaring it lets RTC-driven sessions be told apart from plain `backend` traffic on the dashboards.
+- 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` (default `48000`) tunes the target bitrate. Only effective in direct mode.
+
+### 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).
+- The `region` configuration now defaults to automatic selection: when left unset, the SDK picks the closest serving region at initialization. Passing an explicit `region` continues to force that region, unchanged. If automatic selection can't be reached, the SDK falls back to a default region and continues initializing.
+- Opus uplink encoding 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.
+- If the configured `sampleRate` is not one of Opus's supported rates, `initialize` logs a warning and falls back to a raw PCM uplink instead of silently failing to build the encoder.
+- `initialize` with a missing `appId` now fails fast (throws) with an updated message pointing to https://app.spatius.ai/ to obtain an app ID.
+
+### Fixed
+- Fixed playback failing to start when the first audio arrived slightly after the animation frames (both host and direct modes) — playback now begins correctly instead of stalling.
+- Fixed an intermittent burst of harsh noise at the start of Opus-input playback: on a fast start the first audio could be played before the Opus decoder finished initializing. Opus input is now always decoded before playback, so no raw Opus is ever played as PCM.
+- Fixed the idle animation freezing (and a delayed start) in direct mode with Opus input when animation frames arrived before the decoded audio: playback now waits for both audio and animation to be ready, and the avatar keeps looping idle smoothly until the round actually begins.
+- Fixed playback getting stuck when audio was sent while the connection was still being established and the session later reconnected: the audio clock could freeze, leaving the avatar frozen on a single frame instead of animating in sync with the audio.
+- Fixed the avatar not returning to idle after a playback round finished in that same send-then-connect scenario; it now correctly transitions back to idle when playback ends.
+
+## [1.3.1-beta.7] - 2026-08-02
+
+### Changed
+- Internal telemetry changes only; no changes to the public API or runtime behavior.
+
 ## [1.3.1-beta.6] - 2026-08-01
 
 ### Changed

package/dist/{AvatarDownloader-Dfi7wtgQ.js → AvatarDownloader-DyhenPKd.js}

@@ -1,8 +1,8 @@
 import { n as __exportAll } from "./rolldown-runtime-B-1-B7_t.js";
-import { t as AvatarSDK } from "./AvatarSDK-CnZqa_X4.js";
-import { Et as ErrorCode, c as logEvent, gt as generateTraceId, l as logMetric, t as logger, vt as AvatarError, y as recordHttpClientDuration } from "./logger-fAU8oahT.js";
-import { n as APP_CONFIG, r as getFlameCdnBase, t as errorToMessage } from "./error-utils-CqKOrHrY.js";
-import { t as PwaCacheManager } from "./pwa-cache-manager-CwXaM3xR.js";
+import { t as AvatarSDK } from "./AvatarSDK-DgPvHU4L.js";
+import { S as recordHttpClientDuration, c as logEvent, kt as ErrorCode, l as logMetric, t as logger, v as hostOf, xt as AvatarError, yt as generateTraceId } from "./logger-BOpQ7u0w.js";
+import { n as APP_CONFIG, r as getFlameCdnBase, t as errorToMessage } from "./error-utils-BogEllAd.js";
+import { t as PwaCacheManager } from "./pwa-cache-manager-C7NbU52Q.js";
 //#region core/AvatarDownloader.ts
 var AvatarDownloader_exports = /* @__PURE__ */ __exportAll({ AvatarDownloader: () => AvatarDownloader });
 /**
@@ -47,20 +47,46 @@ function getCacheInfo(url, response) {
 	};
 }
 /**
-* Simple download helper with CORS proxy support for development
-* Static resources don't need appId and token headers
-* 
-* Features:
-* - Supports AbortSignal for cancellation
-* - Automatic retry (default 3 times, no delay)
-* - PWA cache integration
-* 
-* @param url 资源 URL
-* @param options 下载选项
-* @returns ArrayBuffer and cache information
+* 把整次角色加载的资产下载汇总成**一条** Transaction。
+*
+* 成败取「最差的一片」：任一片 transport error 即整次记 transport error；否则取
+* 状态码最大的那个（4xx/5xx 会盖过 200）。这样后端按状态码切出的成功率，含义是
+* 「这次加载的资产是否全部拿到」——与用户实际体验一致，一片挂了角色就出不来。
+*
+* duration 传整体耗时而非单片，与 `download_avatar_assets_latency` 同口径。
 */
+function recordAssetTransaction(outcomes, durationMs, operation = ASSET_OPERATION) {
+	const real = outcomes.filter((o) => !o.skipped);
+	if (real.length === 0) {
+		recordHttpClientDuration({
+			operation,
+			method: "GET",
+			durationMs,
+			statusCode: 200,
+			cacheHit: true
+		});
+		return;
+	}
+	recordHttpClientDuration({
+		operation,
+		method: "GET",
+		durationMs,
+		statusCode: real.some((o) => o.statusCode === void 0) ? void 0 : real.reduce((max, o) => Math.max(max, o.statusCode ?? 0), 0),
+		serverAddress: real[0].host,
+		cacheHit: false
+	});
+}
+/**
+* Transaction 的 `operation` 取值。必须低基数：资产 URL 带 avatar id 与文件名，
+* 直接当维度会让时间序列随角色数无限增长。要定位「哪个文件挂了」用
+* `download_avatar_assets_failed` log，它带 resource/url/error。
+*/
+var ASSET_OPERATION = "/assets/character";
+var TEMPLATE_OPERATION = "/assets/template";
 async function downloadResource(url, options) {
-	const { signal, characterId, resourceType, maxRetries = 3 } = options || {};
+	const { signal, characterId, resourceType, maxRetries = 3, outcomes } = options || {};
+	const outcomeSlotIndex = outcomes ? outcomes.length : -1;
+	if (outcomes) outcomes.push({ host: hostOf(url) });
 	if (signal?.aborted) throw new Error("Download cancelled");
 	try {
 		let cached = null;
@@ -79,6 +105,10 @@ async function downloadResource(url, options) {
 			cacheInfo.cacheHit = true;
 			cacheInfo.cacheType = "pwa";
 			cacheInfo.pwaCacheSubtype = pwaCacheSubtype;
+			if (outcomes && outcomeSlotIndex >= 0) outcomes[outcomeSlotIndex] = {
+				host: "",
+				skipped: true
+			};
 			return {
 				data: cached,
 				cacheInfo
@@ -87,8 +117,11 @@ async function downloadResource(url, options) {
 		let lastError = null;
 		for (let attempt = 1; attempt <= maxRetries; attempt++) {
 			if (signal?.aborted) throw new Error("Download cancelled");
+			const outcomeSlot = { host: hostOf(url) };
+			if (outcomes) outcomes[outcomeSlotIndex] = outcomeSlot;
 			try {
 				const response = await fetch(url, { signal });
+				outcomeSlot.statusCode = response.status;
 				if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
 				const arrayBuffer = await response.arrayBuffer();
 				const contentLength = response.headers.get("content-length");
@@ -146,32 +179,41 @@ var AvatarDownloader = class {
 				cache_hit: true,
 				cache_type: "pwa"
 			});
+			recordAssetTransaction([], duration, TEMPLATE_OPERATION);
 			return { unifiedModel: cached };
 		}
 		const maxRetries = 3;
 		let lastError = null;
-		for (let attempt = 1; attempt <= maxRetries; attempt++) try {
-			const response = await fetch(url);
-			if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
-			let buffer;
-			if (APP_CONFIG.flame.unifiedModelPath.endsWith(".gz")) {
-				const decompressedStream = response.body.pipeThrough(new DecompressionStream("gzip"));
-				buffer = await new Response(decompressedStream).arrayBuffer();
-			} else buffer = await response.arrayBuffer();
-			logger.log(`✅ Unified template loaded (${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB)`);
-			PwaCacheManager.putTemplateResource(url, buffer).catch((err) => {
-				logger.warn(`[loadUnifiedTemplate] Failed to cache:`, err);
-			});
-			logMetric("template_resources_load_measure", Date.now() - startTime, {
-				file_count: 1,
-				cache_hit: false,
-				cache_type: "none"
-			});
-			return { unifiedModel: buffer };
-		} catch (err) {
-			lastError = err instanceof Error ? err : new Error(String(err));
-			if (attempt < maxRetries) logger.warn(`[loadUnifiedTemplate] Attempt ${attempt}/${maxRetries} failed, retrying...`);
+		const templateOutcomes = [];
+		for (let attempt = 1; attempt <= maxRetries; attempt++) {
+			const outcomeSlot = { host: hostOf(url) };
+			templateOutcomes[0] = outcomeSlot;
+			try {
+				const response = await fetch(url);
+				outcomeSlot.statusCode = response.status;
+				if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+				let buffer;
+				if (APP_CONFIG.flame.unifiedModelPath.endsWith(".gz")) {
+					const decompressedStream = response.body.pipeThrough(new DecompressionStream("gzip"));
+					buffer = await new Response(decompressedStream).arrayBuffer();
+				} else buffer = await response.arrayBuffer();
+				logger.log(`✅ Unified template loaded (${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB)`);
+				PwaCacheManager.putTemplateResource(url, buffer).catch((err) => {
+					logger.warn(`[loadUnifiedTemplate] Failed to cache:`, err);
+				});
+				logMetric("template_resources_load_measure", Date.now() - startTime, {
+					file_count: 1,
+					cache_hit: false,
+					cache_type: "none"
+				});
+				recordAssetTransaction(templateOutcomes, Date.now() - startTime, TEMPLATE_OPERATION);
+				return { unifiedModel: buffer };
+			} catch (err) {
+				lastError = err instanceof Error ? err : new Error(String(err));
+				if (attempt < maxRetries) logger.warn(`[loadUnifiedTemplate] Attempt ${attempt}/${maxRetries} failed, retrying...`);
+			}
 		}
+		recordAssetTransaction(templateOutcomes, Date.now() - startTime, TEMPLATE_OPERATION);
 		throw lastError || /* @__PURE__ */ new Error(`Failed to download unified template after ${maxRetries} attempts`);
 	}
 	/**
@@ -252,6 +294,8 @@ var AvatarDownloader = class {
 		};
 		const characterData = {};
 		const cacheInfos = [];
+		/** 各片的 HTTP 结果，收尾时汇总成一条 Transaction（见 recordAssetTransaction）。 */
+		const httpOutcomes = [];
 		const parallelStartTime = Date.now();
 		const downloadPromises = filesToLoad.map(async ({ key, url, filename, optional }) => {
 			updateProgress(filename, false);
@@ -259,7 +303,8 @@ var AvatarDownloader = class {
 				const { data: arrayBuffer, cacheInfo } = await downloadResource(url, {
 					signal,
 					characterId: characterMeta.characterId ?? void 0,
-					resourceType: "character"
+					resourceType: "character",
+					outcomes: httpOutcomes
 				});
 				if (key === "shape") characterData.shape = arrayBuffer;
 				else if (key === "pointCloud") characterData.pointCloud = arrayBuffer;
@@ -297,7 +342,11 @@ var AvatarDownloader = class {
 				};
 			}
 		});
-		await Promise.all(downloadPromises);
+		try {
+			await Promise.all(downloadPromises);
+		} finally {
+			recordAssetTransaction(httpOutcomes, Date.now() - totalStartTime);
+		}
 		const parallelDuration = Date.now() - parallelStartTime;
 		const totalDuration = Date.now() - totalStartTime;
 		if (!characterData.shape || !characterData.pointCloud) {
@@ -324,7 +373,11 @@ var AvatarDownloader = class {
 			parallel_duration: parallelDuration,
 			total_size: totalSize
 		});
-		return characterData;
+		return {
+			data: characterData,
+			cacheHit,
+			cacheType
+		};
 	}
 	/**
 	* Preload all resources (template + character data + camera info + settings)
@@ -333,7 +386,7 @@ var AvatarDownloader = class {
 	async preloadResources(characterMeta, options) {
 		const { progressCallback = null, signal, useCompressedModel = false } = options || {};
 		if (signal?.aborted) throw new Error("Preload cancelled");
-		const [characterData, preloadCameraSettings] = await Promise.all([this.loadCharacterData(characterMeta, {
+		const [characterResult, preloadCameraSettings] = await Promise.all([this.loadCharacterData(characterMeta, {
 			signal,
 			useCompressedModel,
 			progressCallback: (info) => {
@@ -344,9 +397,11 @@ var AvatarDownloader = class {
 			}
 		}), this.loadCameraSettings(characterMeta, { signal })]);
 		return {
-			characterData,
+			characterData: characterResult.data,
 			preloadCameraSettings,
-			characterSettings: characterMeta.characterSettings
+			characterSettings: characterMeta.characterSettings,
+			cacheHit: characterResult.cacheHit,
+			cacheType: characterResult.cacheType
 		};
 	}
 	/**