@spatius/avatarkit 1.3.1-beta.2 → 1.3.1-beta.4

package/dist/pwa-cache-manager-D3nj4sd5.js

@@ -0,0 +1,151 @@
+import { n as __exportAll } from "./rolldown-runtime-B-1-B7_t.js";
+import { t as logger } from "./logger-C3fw-NWP.js";
+//#region utils/pwa-cache-manager.ts
+/**
+* PWA Cache Manager
+* Manages Service Worker Cache for character resources and template resources
+* @internal
+*/
+var pwa_cache_manager_exports = /* @__PURE__ */ __exportAll({ PwaCacheManager: () => PwaCacheManager });
+/**
+* PWA Cache Manager
+* Manages character resources cache (per character) and template resources cache (versioned)
+*/
+var PwaCacheManager = class PwaCacheManager {
+	static TEMPLATE_RESOURCE_VERSION = "1.0.0";
+	static TEMPLATE_CACHE_NAME = `spatius-sdk-template-cache-${PwaCacheManager.TEMPLATE_RESOURCE_VERSION}`;
+	static TEMPLATE_VERSION_STORAGE_KEY = "spatius-sdk-template-cache-version";
+	static CHARACTER_CACHE_PREFIX = "spatius-sdk-character-";
+	static CHARACTER_CACHE_SUFFIX = "-cache";
+	static MAX_CHARACTER_CACHE_ENTRIES = 1e3;
+	/**
+	* Check if Cache API is supported
+	* @internal
+	*/
+	static isSupported() {
+		return typeof caches !== "undefined";
+	}
+	/**
+	* Get character cache name
+	* @internal
+	*/
+	static getCharacterCacheName(characterId) {
+		return `${PwaCacheManager.CHARACTER_CACHE_PREFIX}${characterId}${PwaCacheManager.CHARACTER_CACHE_SUFFIX}`;
+	}
+	/**
+	* Get character resource from cache
+	* @internal
+	*/
+	static async getCharacterResource(characterId, url) {
+		if (!PwaCacheManager.isSupported()) return null;
+		try {
+			const cacheName = PwaCacheManager.getCharacterCacheName(characterId);
+			const response = await (await caches.open(cacheName)).match(url);
+			if (response) {
+				const arrayBuffer = await response.arrayBuffer();
+				logger.log(`[PwaCacheManager] Character resource cache hit: ${url}`);
+				return arrayBuffer;
+			}
+			return null;
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to get character resource from cache:`, error);
+			return null;
+		}
+	}
+	/**
+	* Put character resource into cache
+	* @internal
+	*/
+	static async putCharacterResource(characterId, url, data) {
+		if (!PwaCacheManager.isSupported()) return;
+		try {
+			const cacheName = PwaCacheManager.getCharacterCacheName(characterId);
+			const cache = await caches.open(cacheName);
+			const keys = await cache.keys();
+			if (keys.length >= PwaCacheManager.MAX_CHARACTER_CACHE_ENTRIES) {
+				const oldestKey = keys[0];
+				await cache.delete(oldestKey);
+				logger.log(`[PwaCacheManager] Character cache full, deleted oldest entry: ${oldestKey.url}`);
+			}
+			await cache.put(url, new Response(data));
+			logger.log(`[PwaCacheManager] Character resource cached: ${url}`);
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to put character resource to cache:`, error);
+		}
+	}
+	/**
+	* Get template resource from cache
+	* @internal
+	*/
+	static async getTemplateResource(url) {
+		if (!PwaCacheManager.isSupported()) return null;
+		try {
+			const response = await (await caches.open(PwaCacheManager.TEMPLATE_CACHE_NAME)).match(url);
+			if (response) {
+				const arrayBuffer = await response.arrayBuffer();
+				logger.log(`[PwaCacheManager] Template resource cache hit: ${url}`);
+				return arrayBuffer;
+			}
+			return null;
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to get template resource from cache:`, error);
+			return null;
+		}
+	}
+	/**
+	* Put template resource into cache
+	* Template resources have no quantity limit, permanently retained until version update
+	* @internal
+	*/
+	static async putTemplateResource(url, data) {
+		if (!PwaCacheManager.isSupported()) return;
+		try {
+			await (await caches.open(PwaCacheManager.TEMPLATE_CACHE_NAME)).put(url, new Response(data));
+			logger.log(`[PwaCacheManager] Template resource cached: ${url}`);
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to put template resource to cache:`, error);
+		}
+	}
+	/**
+	* Clear character cache
+	* @internal
+	*/
+	static async clearCharacterCache(characterId) {
+		if (!PwaCacheManager.isSupported()) return;
+		try {
+			const cacheName = PwaCacheManager.getCharacterCacheName(characterId);
+			await caches.delete(cacheName);
+			logger.log(`[PwaCacheManager] Character cache cleared: ${characterId}`);
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to clear character cache:`, error);
+		}
+	}
+	/**
+	* Check template cache version, clear cache if version changed
+	* Uses independent template resource version (not dependent on SDK version), allowing different SDK versions to share the same template resource cache
+	* @returns true if version changed and cache was cleared, false otherwise
+	* @internal
+	*/
+	static async checkTemplateCacheVersion() {
+		if (!PwaCacheManager.isSupported()) return false;
+		try {
+			const currentTemplateVersion = PwaCacheManager.TEMPLATE_RESOURCE_VERSION;
+			const storedVersion = localStorage.getItem(PwaCacheManager.TEMPLATE_VERSION_STORAGE_KEY);
+			if (storedVersion !== currentTemplateVersion) {
+				if (storedVersion) {
+					const oldCacheName = `spatius-sdk-template-cache-${storedVersion}`;
+					await caches.delete(oldCacheName).catch(() => {});
+				}
+				localStorage.setItem(PwaCacheManager.TEMPLATE_VERSION_STORAGE_KEY, currentTemplateVersion);
+				logger.log(`[PwaCacheManager] Template cache version changed: ${storedVersion} -> ${currentTemplateVersion}, old cache cleared`);
+				return true;
+			}
+			return false;
+		} catch (error) {
+			logger.warn(`[PwaCacheManager] Failed to check template cache version:`, error);
+			return false;
+		}
+	}
+};
+//#endregion
+export { pwa_cache_manager_exports as n, PwaCacheManager as t };

package/dist/rolldown-runtime-B-1-B7_t.js

@@ -0,0 +1,33 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+export { __exportAll as n, __toESM as r, __commonJSMin as t };

package/dist/types/character.d.ts

@@ -21,10 +21,10 @@ export interface Animations {
     audioMono?: ResourceHolder;
 }
 export interface CustomAnimation {
-    key: string;
-    pbUrl: string;
-    wavUrl: string;
-    remark: string;
+    /** Animation clip name. */
+    name: string;
+    /** The clip's resource (local/remote URLs), mirroring other asset resources. */
+    resource?: Resource;
 }
 export interface CharacterAsset {
     characterId: string;

package/dist/types/index.d.ts

@@ -35,6 +35,59 @@ export interface AudioFormat {
     readonly channelCount: 1;
     /** Sample rate, supported: 8000, 16000, 22050, 24000, 32000, 44100, 48000, default: 16000 */
     readonly sampleRate: number;
+    /**
+     * Opus target bitrate in bits/sec, used when the SDK encodes the upstream to Opus.
+     * Defaults to 48000. Higher = better quality but more upload; tune against the
+     * bandwidth/quality tradeoff for your content.
+     */
+    readonly opusBitrate?: number;
+    /**
+     * Whether the SDK may compress the direct-mode uplink as Opus. Default false —
+     * the uplink is raw PCM unless you opt in.
+     *
+     * Opus cuts the upload to roughly an eighth, at the cost of encoding on the
+     * client. Off by default so bandwidth is traded for CPU only where that is
+     * wanted — low-end devices (e.g. learning tablets) should not be asked to
+     * encode audio they cannot afford to.
+     *
+     * Only effective in direct mode: host mode has no uplink, and Opus input is
+     * already Opus so there is nothing to encode. Independent of
+     * `inputAudioFormat`, which describes what the host feeds in.
+     */
+    readonly opusUplinkEnabled?: boolean;
+    /**
+     * Format of the audio the host feeds INTO the SDK (via `send` / `yieldAudioData`).
+     * Fixed at SDK initialization for the whole session; do not change it per call.
+     *
+     * - 'pcm' (default): the host provides raw PCM16 mono.
+     * - 'opus': the host provides Opus. The SDK decodes it back to PCM16 for local
+     *   playback. Independent of the SDK's own upstream format to the driving
+     *   service, which the SDK decides internally.
+     *
+     * Under 'opus', the SDK accepts either shape that TTS providers hand out, and
+     * tells them apart from the bytes — it is not declared separately:
+     *
+     * - **Ogg Opus**, as file-style APIs return it (Azure
+     *   `ogg-48khz-16bit-mono-opus`, Google `OGG_OPUS`). Any chunk boundary is fine.
+     * - **Bare Opus packets, ONE PER CALL**, as streaming APIs push them over a
+     *   WebSocket. The SDK wraps these into Ogg for you. They cannot be batched: an
+     *   Opus packet carries no length of its own, so several concatenated into one
+     *   buffer have no recoverable boundaries.
+     *
+     * Requirements, all reported via `onError` with
+     * {@link ErrorCode.invalidAudioInput} rather than failing silently:
+     *
+     * - **Mono only.** The driving service's lip-sync model consumes mono; request
+     *   it from your provider rather than relying on a downmix.
+     * - **One shape per conversation.** Do not switch between Ogg and bare packets
+     *   mid-round.
+     * - **Ogg or bare packets only.** WebM, MP4, WAV and CAF are not demuxed, even
+     *   when the Opus inside them would be valid.
+     *
+     * The configured {@link sampleRate} does not apply: Opus always decodes at
+     * 48 kHz, and the SDK reports that rate for the session.
+     */
+    readonly inputAudioFormat?: 'pcm' | 'opus';
 }
 export declare enum RenderQuality {
     standard = "standard",
@@ -129,6 +182,13 @@ export declare enum ErrorCode {
     audioOnlyInitFailed = "audioOnlyInitFailed",
     /** No audio data to play */
     noAudio = "noAudio",
+    /**
+     * Audio handed to the SDK does not match `audioFormat.inputAudioFormat`.
+     * Raised for Opus input that is neither Ogg Opus nor a bare Opus packet
+     * (e.g. WebM or MP4, which the SDK does not demux), is stereo, or switches
+     * shape mid-conversation. The error message names the specific problem.
+     */
+    invalidAudioInput = "invalidAudioInput",
     /** Audio context not initialized */
     audioContextNotInitialized = "audioContextNotInitialized",
     /** Animation player not initialized */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spatius/avatarkit",
   "type": "module",
-  "version": "1.3.1-beta.2",
+  "version": "1.3.1-beta.4",
   "packageManager": "pnpm@10.18.2",
   "description": "AvatarKit SDK - Real-time Avatar Rendering SDK for Web",
   "author": "AvatarKit Team",
@@ -62,7 +62,7 @@
   "peerDependencies": {
     "@webgpu/types": "*",
     "next": ">=13.0.0",
-    "vite": "^5.0.0"
+    "vite": ">=5.0.0"
   },
   "peerDependenciesMeta": {
     "vite": {
@@ -78,10 +78,15 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.218.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.218.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "0.218.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.218.0",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-logs": "^0.218.0",
+    "@opentelemetry/sdk-metrics": "2.7.1",
+    "@opentelemetry/sdk-trace-web": "2.7.1",
     "@opentelemetry/semantic-conventions": "^1.41.1",
     "nanoid": "^5.1.6",
+    "opusscript": "0.1.1",
     "posthog-js": "^1.310.1"
   },
   "devDependencies": {
@@ -90,7 +95,7 @@
     "fflate": "0.8.3",
     "tsx": "^4.20.6",
     "typescript": "^5.0.0",
-    "vite": "^5.0.0",
+    "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4"
   }
 }