@spatius/avatarkit 1.3.1-beta.7 → 1.3.2

package/dist/index.js

@@ -1,8 +1,10 @@
-import { a as avatarViewRegistry, c as Message, d as BinaryReader, f as BinaryWriter, i as buildTraceparent, l as MessageType, o as AudioFormat, r as startPlaybackTrace, s as EgressType, t as AvatarSDK, u as TransportCompression } from "./AvatarSDK-CTprrfJk.js";
-import { At as RENDER_QUALITY_PARAMS, Ct as DEFAULT_REGION, Dt as FrameStarvationMode, Et as ErrorCode, Mt as TransitionType, Ot as LoadProgress, St as DEFAULT_OPUS_BITRATE, Tt as DrivingServiceMode, _t as AnimationType, b as recordMetric, bt as ConnectionState, c as logEvent, h as clockSync, ht as idManager, jt as RenderQuality, kt as LogLevel, l as logMetric, m as resolveMarks, p as monoTimestamp, t as logger, vt as AvatarError, wt as DEFAULT_REGION_REQUEST, xt as ConversationState, yt as AvatarState } from "./logger-DdmfSEn-.js";
-import { n as APP_CONFIG } from "./error-utils-BCZDCrc6.js";
-import { r as OggMuxer, t as OggPageSplitter } from "./OpusCodec-PWv7ynPp.js";
-import { t as AvatarDownloader } from "./AvatarDownloader-B1tJTnIb.js";
+import { a as EgressType, c as TransportCompression, i as AudioFormat, l as BinaryReader, o as Message, r as avatarViewRegistry, s as MessageType, t as AvatarSDK, u as BinaryWriter } from "./AvatarSDK-DqP8n0ex.js";
+import { At as FrameStarvationMode, C as recordMetric, Ct as ConnectionState, Dt as DEFAULT_REGION_REQUEST, Et as DEFAULT_REGION, Ft as TransitionType, Mt as LogLevel, Nt as RENDER_QUALITY_PARAMS, Ot as DrivingServiceMode, Pt as RenderQuality, St as AvatarState, Tt as DEFAULT_OPUS_BITRATE, bt as AnimationType, c as logEvent, g as clockSync, h as resolveMarks, jt as LoadProgress, kt as ErrorCode, l as logMetric, m as monoTimestamp, p as monoMarkFrom, t as logger, vt as idManager, wt as ConversationState, xt as AvatarError } from "./logger-gpv4NaPj.js";
+import { a as startLoadTrace, o as startPlaybackTrace, r as startConnectTrace, s as buildTraceparent } from "./otel-trace-M2fi3yoE.js";
+import { n as APP_CONFIG } from "./error-utils-D7aLxFrw.js";
+import { r as OggMuxer, t as OggPageSplitter } from "./OpusCodec-B0YtpenN.js";
+import { n as setOpusEncodeFrameSink } from "./OpusEncoderProxy-sMAwGYqf.js";
+import { t as AvatarDownloader } from "./AvatarDownloader-BDKn8AjO.js";
 //#region core/Avatar.ts
 var Avatar = class {
 	id;
@@ -309,8 +311,8 @@ var AnimationPlayer = class AnimationPlayer {
 	*/
 	async createAndInitializeStreamingPlayer() {
 		if (this.streamingPlayer) return;
-		const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-C6hgkvbK.js");
-		const { AvatarSDK } = await import("./AvatarSDK-CTprrfJk.js").then((n) => n.n);
+		const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-DXsCXseQ.js");
+		const { AvatarSDK } = await import("./AvatarSDK-DqP8n0ex.js").then((n) => n.n);
 		const audioFormat = AvatarSDK.getAudioFormat();
 		this.streamingPlayer = new StreamingAudioPlayer({
 			sampleRate: audioFormat.sampleRate,
@@ -930,9 +932,11 @@ var PendingAudioBuffer = class {
 };
 //#endregion
 //#region animation/AnimationWebSocketClient.ts
-/**
-* @internal
-*/
+var onOpusEncodeSegment = null;
+/** @internal 由 AvatarController 在每轮播放开始时装上、结束时卸下。 */
+function setOpusEncodeSegmentSink(fn) {
+	onOpusEncodeSegment = fn;
+}
 var AnimationWebSocketClient = class extends EventEmitter {
 	wsUrl;
 	reconnectAttempts;
@@ -948,6 +952,15 @@ var AnimationWebSocketClient = class extends EventEmitter {
 	sessionConfigured = false;
 	connectionStartTime = 0;
 	/**
+	* 连接发起时刻（`new WebSocket()` 之前）。
+	*
+	* `ws_connect_latency` 与 connect trace 都以它为起点。与 `connectionStartTime`
+	* 分开：那个是「连接建立成功」的时刻，用来算 session 时长，语义不同。
+	*/
+	connectStartMs = 0;
+	/** 握手完成（onopen）时刻，用来把连接拆成握手 / 会话确认两段。 */
+	wsOpenMs = 0;
+	/**
 	* Opus encoder proxy, created only when the SDK-decided uplink is Opus. Null
 	* means audio is sent as raw PCM. Scoped to one connection: created
 	* on connect, destroyed on disconnect. Runs the encode off the main thread via
@@ -1194,26 +1207,84 @@ var AnimationWebSocketClient = class extends EventEmitter {
 	* message so the server sees the stream close. Caller ensures socket/session
 	* are ready.
 	*/
+	/** 1 秒 PCM 的字节数（16-bit 单声道），用于把编码分段按音频秒数切开。 */
+	get audioBytesPerSecond() {
+		return (AvatarSDK.getAudioFormat().sampleRate || 16e3) * 2;
+	}
+	/**
+	* 编码 span 的跨**调用**累计状态（不足 1 秒的余量留到下一次 encode 调用）。
+	*
+	* `encodeSpanReqId` 用来判轮次切换：这几个字段是实例级的，不跟着 controller 每轮
+	* 重置的 traceActions 走，上一轮的余量留到下一轮会让段数虚增、时刻串到几秒前
+	* （实测 12 秒音频报出 24 段，且落在 send_audio 之前 4 秒）。
+	*/
+	encodeSpanReqId = null;
+	encodeSpanStart = null;
+	encodeSpanBytes = 0;
+	/**
+	* 把逐帧的编码时刻按**音频秒数**切成段，报给 trace。
+	*
+	* 与解码侧同一套口径：累计满 1 秒 PCM 收一段，边界用那一帧编完的真实时刻；
+	* 尾巴不足 1 秒的余量跨调用累计（流式喂时一块往往远不足 1 秒）。
+	*/
+	emitEncodeSegments(reqId, fallbackStart, frames, frameTs) {
+		if (frames.length === 0) return;
+		if (this.encodeSpanReqId !== reqId) {
+			this.encodeSpanReqId = reqId;
+			this.encodeSpanStart = null;
+			this.encodeSpanBytes = 0;
+		}
+		const oneSecondBytes = this.audioBytesPerSecond;
+		for (let i = 0; i < frames.length; i++) {
+			this.encodeSpanStart ??= fallbackStart;
+			this.encodeSpanBytes += frames[i];
+			if (this.encodeSpanBytes < oneSecondBytes) continue;
+			const endTs = monoMarkFrom(frameTs[i]);
+			onOpusEncodeSegment?.({
+				startTs: this.encodeSpanStart,
+				endTs,
+				pcmBytes: this.encodeSpanBytes
+			});
+			this.encodeSpanStart = endTs;
+			this.encodeSpanBytes = 0;
+		}
+	}
 	async encodeAndSendOpus(conversationId, audioData, end) {
 		try {
-			const pages = await this.opusEncoder.encode(conversationId, audioData, end);
-			if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
-			for (let i = 0; i < pages.length; i++) {
-				const isLast = end && i === pages.length - 1;
+			const encodeStartTs = monoTimestamp();
+			let pendingFrames = [];
+			let pendingTs = [];
+			setOpusEncodeFrameSink((frames, ts) => {
+				pendingFrames = frames;
+				pendingTs = ts;
+			});
+			const sendPage = (page, isLast) => {
+				if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
 				const message = {
 					type: MessageType.MESSAGE_CLIENT_AUDIO_INPUT,
 					clientAudioInput: {
 						reqId: conversationId,
-						audio: pages[i],
+						audio: page,
 						end: isLast,
 						traceContext: this.takeTraceContext(conversationId)
 					}
 				};
 				const writer = new BinaryWriter();
 				Message.encode(message, writer);
-				const bytes = writer.finish();
-				this.ws.send(bytes);
-			}
+				this.ws.send(writer.finish());
+			};
+			let held = null;
+			const pushPage = (page) => {
+				if (held) sendPage(held, false);
+				held = page;
+			};
+			await this.opusEncoder.encode(conversationId, audioData, end, (batch) => {
+				for (const page of batch) pushPage(page);
+			});
+			setOpusEncodeFrameSink(null);
+			this.emitEncodeSegments(conversationId, encodeStartTs, pendingFrames, pendingTs);
+			if (held === null && end) held = /* @__PURE__ */ new Uint8Array(0);
+			if (held) sendPage(held, end);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			logger.error("[AnimationWebSocketClient] Failed to send Opus audio:", message);
@@ -1229,8 +1300,8 @@ var AnimationWebSocketClient = class extends EventEmitter {
 	* Internal decision for the SDK's upstream audio format when the host feeds PCM:
 	* whether to encode PCM→Opus (true) or send raw PCM (false).
 	*
-	* Opus uplink is opt-in: without `opusUplinkEnabled: true` the uplink stays raw
-	* PCM, so the encode cost is only paid where it is wanted.
+	* Opus uplink is opt-OUT: it is on unless the host passes
+	* `opusUplinkEnabled: false`, which keeps the raw PCM uplink.
 	*
 	* Once opted in, the decision is still the SDK's: the backend (v2) supports Opus
 	* unconditionally and the encoder has a two-tier fallback (worker → main-thread
@@ -1240,7 +1311,7 @@ var AnimationWebSocketClient = class extends EventEmitter {
 	*/
 	shouldUseOpusUplink() {
 		const { opusUplinkEnabled } = AvatarSDK.getAudioFormat();
-		if (opusUplinkEnabled !== true) return false;
+		if (opusUplinkEnabled === false) return false;
 		return true;
 	}
 	/**
@@ -1281,7 +1352,7 @@ var AnimationWebSocketClient = class extends EventEmitter {
 			return;
 		}
 		try {
-			const { OpusEncoderProxy } = await import("./OpusEncoderProxy-DiW21sBK.js");
+			const { OpusEncoderProxy } = await import("./OpusEncoderProxy-sMAwGYqf.js").then((n) => n.t);
 			const bitrate = opusBitrate ?? 48e3;
 			this.opusEncoder = await OpusEncoderProxy.create(sampleRate, bitrate);
 			this.uplinkIsOpus = true;
@@ -1337,19 +1408,39 @@ var AnimationWebSocketClient = class extends EventEmitter {
 		if (connectionId) url.searchParams.set("connection_id", connectionId);
 		return url.toString();
 	}
+	/**
+	* 发一条建连 trace：`connect` 下挂 `ws_handshake` / `session_confirm` 两段。
+	*
+	* 在会话确认时一次性回填（两段的时刻都已知），而不是实时开 span——建连全程只有
+	* 两个边界点，回填式更简单，也与 init / load trace 的做法一致。
+	*/
+	emitConnectTrace(confirmMs) {
+		const start = this.connectStartMs;
+		const open = this.wsOpenMs;
+		if (start <= 0 || open <= 0) return;
+		const t = startConnectTrace(start, {
+			connection_id: idManager.getConnectionId() ?? "",
+			region: AvatarSDK.configuration?.region ?? ""
+		});
+		t.span("ws_handshake", start, open, { dur_ms: open - start });
+		t.span("session_confirm", open, confirmMs, { dur_ms: confirmMs - open });
+		t.end(true, confirmMs, { dur_ms: confirmMs - start });
+		this.wsOpenMs = 0;
+	}
 	connectWebSocket(url) {
 		return new Promise((resolve, reject) => {
 			try {
 				const urlForLog = this.sanitizeUrlForLog(url);
 				logger.log(`[AnimationWebSocketClient] Connecting to WebSocket: ${urlForLog}`);
-				const connectStartMs = Date.now();
+				this.connectStartMs = Date.now();
+				this.wsOpenMs = 0;
 				this.ws = new WebSocket(url);
 				this.ws.onopen = () => {
 					this.isConnecting = false;
 					this.currentRetryCount = 0;
 					this.isManuallyDisconnected = false;
 					this.connectionStartTime = Date.now();
-					logMetric("ws_connect_latency", this.connectionStartTime - connectStartMs, {}, { connection_id: idManager.getConnectionId() || "" });
+					this.wsOpenMs = this.connectionStartTime;
 					logger.log(`[AnimationWebSocketClient] WebSocket connected successfully`);
 					this.configureSession();
 					this.emit("connected");
@@ -1524,6 +1615,12 @@ var AnimationWebSocketClient = class extends EventEmitter {
 						idManager.setConnectionId(connectionId);
 						logger.log(`[AnimationWebSocketClient] Session confirmed, connection_id updated: ${connectionId}`);
 					} else logger.log("[AnimationWebSocketClient] Session confirmed by server");
+					if (this.connectStartMs > 0) {
+						const confirmMs = Date.now();
+						logMetric("ws_connect_latency", confirmMs - this.connectStartMs, {}, { connection_id: idManager.getConnectionId() || "" });
+						this.emitConnectTrace(confirmMs);
+						this.connectStartMs = 0;
+					}
 					this.flushPendingAudio();
 					this.emit("sessionConfirmed", connectionId);
 					return;
@@ -2056,7 +2153,7 @@ function resolveInputAudioFormat() {
 */
 function resolveUplinkAudioFormat() {
 	const fmt = AvatarSDK.getAudioFormat();
-	return fmt.inputAudioFormat === "opus" || fmt.opusUplinkEnabled === true ? "opus" : "pcm";
+	return fmt.inputAudioFormat === "opus" || fmt.opusUplinkEnabled !== false ? "opus" : "pcm";
 }
 var AvatarController = class {
 	networkLayer;
@@ -2185,9 +2282,24 @@ var AvatarController = class {
 	*/
 	traceActions = {
 		sends: [],
-		recvs: []
+		recvs: [],
+		decodes: [],
+		encodes: []
+	};
+	/** 上行编码分段的接收钩子，构造时装上、dispose 时卸下（见 setOpusEncodeSegmentSink）。 */
+	onEncodeSegment = (seg) => {
+		this.traceActions.encodes.push(seg);
+		this.markAudioTapAt(seg.pcmBytes, seg.endTs);
 	};
 	/**
+	* 解码 span 的聚合状态：累计满 1 秒 PCM 收一段。
+	*
+	* 跨 chunk 累计——宿主流式喂时一块可能远不足 1 秒，按块收段会碎成几百个 span。
+	* `decodeSpanStart` 是上一段的收尾时刻（null = 用本次 decode 的发起时刻当起点）。
+	*/
+	decodeSpanStart = null;
+	decodeSpanBytes = 0;
+	/**
 	* Highest Ogg granule forwarded so far this round, for Opus input. The granule
 	* accumulates across a stream, so a send's audio seconds is its own end granule
 	* minus this. Reset per conversation. -1 = nothing forwarded yet.
@@ -2208,6 +2320,7 @@ var AvatarController = class {
 		if (this.playbackMode === DrivingServiceMode.direct) this.networkLayer = new NetworkLayer(this);
 		if (typeof document !== "undefined") document.addEventListener("visibilitychange", this.handleVisibilityChange);
 		this.ensureInputOpusDecoder();
+		setOpusEncodeSegmentSink(this.onEncodeSegment);
 	}
 	handleVisibilityChange = () => {
 		if (document.visibilityState === "hidden") this.shouldReportPlaybackStats = false;
@@ -2457,9 +2570,14 @@ var AvatarController = class {
 			const resolved = resolveMarks(latency);
 			const tap0 = resolved["tap_0"];
 			if (typeof tap0 === "number") {
+				const latencyLabels = {
+					...labels,
+					input_audio_format: resolveInputAudioFormat(),
+					uplink_audio_format: resolveUplinkAudioFormat()
+				};
 				const emitDelta = (name, key) => {
 					const t = resolved[key];
-					if (typeof t === "number") recordMetric(name, t - tap0, labels);
+					if (typeof t === "number") recordMetric(name, t - tap0, latencyLabels);
 				};
 				emitDelta("playback_latency_tap_1_ms", "tap_1");
 				emitDelta("playback_latency_tap_2_ms", "tap_2");
@@ -2497,6 +2615,14 @@ var AvatarController = class {
 				actionMarks[`recv_start_${i}`] = r.startTs;
 				actionMarks[`recv_end_${i}`] = r.endTs;
 			});
+			this.traceActions.decodes.forEach((d, i) => {
+				actionMarks[`decode_start_${i}`] = d.startTs;
+				actionMarks[`decode_end_${i}`] = d.endTs;
+			});
+			this.traceActions.encodes.forEach((e, i) => {
+				actionMarks[`encode_start_${i}`] = e.startTs;
+				actionMarks[`encode_end_${i}`] = e.endTs;
+			});
 			const rm = resolveMarks(actionMarks);
 			const allEnds = [...this.traceActions.sends.map((_, i) => rm[`send_end_${i}`]), ...this.traceActions.recvs.map((_, i) => rm[`recv_end_${i}`])].filter((v) => typeof v === "number");
 			const allStarts = [...this.traceActions.sends.map((_, i) => rm[`send_start_${i}`]), ...this.traceActions.recvs.map((_, i) => rm[`recv_start_${i}`])].filter((v) => typeof v === "number");
@@ -2524,6 +2650,44 @@ var AvatarController = class {
 				});
 			});
 			arrival.end(arrivalEnd);
+			const decodeMarks = this.traceActions.decodes;
+			if (decodeMarks.length > 0) {
+				const firstStart = rm[`decode_start_0`];
+				if (typeof firstStart === "number") {
+					const decodeGroup = t.group("decode", firstStart, { view: "decode" });
+					let decodeEnd = firstStart;
+					decodeMarks.forEach((d, i) => {
+						const start = rm[`decode_start_${i}`];
+						const end = rm[`decode_end_${i}`];
+						if (typeof start !== "number" || typeof end !== "number") return;
+						decodeEnd = Math.max(decodeEnd, end);
+						decodeGroup.span(`decode_audio_${i + 1}`, start, floorEnd(start, end), {
+							dur_ms: Math.round(end - start),
+							audio_ms: Math.round(d.pcmBytes / this.audioBytesPerSecond * 1e3)
+						});
+					});
+					decodeGroup.end(decodeEnd);
+				}
+			}
+			const encodeMarks = this.traceActions.encodes;
+			if (encodeMarks.length > 0) {
+				const firstStart = rm[`encode_start_0`];
+				if (typeof firstStart === "number") {
+					const encodeGroup = t.group("encode", firstStart, { view: "encode" });
+					let encodeEnd = firstStart;
+					encodeMarks.forEach((e, i) => {
+						const start = rm[`encode_start_${i}`];
+						const end = rm[`encode_end_${i}`];
+						if (typeof start !== "number" || typeof end !== "number") return;
+						encodeEnd = Math.max(encodeEnd, end);
+						encodeGroup.span(`encode_audio_${i + 1}`, start, floorEnd(start, end), {
+							dur_ms: Math.round(end - start),
+							audio_ms: Math.round(e.pcmBytes / this.audioBytesPerSecond * 1e3)
+						});
+					});
+					encodeGroup.end(encodeEnd);
+				}
+			}
 			const renderEnd = this.playbackEndedAt > tap0 ? this.playbackEndedAt : tap0 + durationMs;
 			const emitPlaybackChain = (into, playLabel, stallLabel, chainStart, chainEnd, events) => {
 				const stalls = events.filter((e) => e.startTs >= chainStart && e.startTs <= chainEnd).sort((a, b) => a.startTs - b.startTs);
@@ -2630,7 +2794,7 @@ var AvatarController = class {
 		const { inputAudioFormat } = AvatarSDK.getAudioFormat();
 		if (inputAudioFormat !== "opus" || this.inputOpusDecoderProxy) return;
 		try {
-			const { OpusDecoderProxy } = await import("./OpusDecoderProxy-m0fVN_M2.js");
+			const { OpusDecoderProxy } = await import("./OpusDecoderProxy-vGagApTz.js");
 			this.inputOpusDecoderProxy = await OpusDecoderProxy.create();
 			this.inputDecodeChain = Promise.resolve();
 		} catch (error) {
@@ -2649,15 +2813,28 @@ var AvatarController = class {
 		if (!this.inputOpusDecoderProxy) {
 			if (resolveInputAudioFormat() === "opus") {
 				logger.error("[AvatarController] Opus input but decoder unavailable; dropping chunk to avoid playing raw Opus as PCM");
-				return /* @__PURE__ */ new Uint8Array(0);
+				return {
+					pcm: /* @__PURE__ */ new Uint8Array(0),
+					segments: [],
+					segmentTs: []
+				};
 			}
-			return new Uint8Array(data);
+			const raw = new Uint8Array(data);
+			return {
+				pcm: raw,
+				segments: raw.length > 0 ? [raw.length] : [],
+				segmentTs: raw.length > 0 ? [performance.now()] : []
+			};
 		}
 		try {
 			return await this.inputOpusDecoderProxy.decode(data);
 		} catch (error) {
 			logger.error("[AvatarController] Failed to decode input Opus audio:", error instanceof Error ? error.message : String(error));
-			return /* @__PURE__ */ new Uint8Array(0);
+			return {
+				pcm: /* @__PURE__ */ new Uint8Array(0),
+				segments: [],
+				segmentTs: []
+			};
 		}
 	}
 	/**
@@ -2705,6 +2882,7 @@ var AvatarController = class {
 			this.currentConversationId = this.generateAndLogNewConversationId();
 			this.reqEnd = false;
 		}
+		this.markFirstAudioTap();
 		const sendStartTs = monoTimestamp();
 		const isOpusInput = resolveInputAudioFormat() === "opus";
 		let sendAudioMs = isOpusInput ? 0 : audioData.byteLength / this.audioBytesPerSecond * 1e3;
@@ -2732,17 +2910,41 @@ var AvatarController = class {
 			const oggEnd = end;
 			this.inputDecodeChain = this.inputDecodeChain.then(async () => {
 				await this.ensureInputOpusDecoder();
-				const pcm = await this.normalizeInputAudioToPcm(oggForDecode);
+				const decodeStartTs = monoTimestamp();
+				const { pcm, segments, segmentTs } = await this.normalizeInputAudioToPcm(oggForDecode);
 				this.receivedAudioBytes += pcm.length;
-				this.markAudioTap(pcm.length);
+				for (let i = 0; i < segments.length; i++) {
+					this.decodeSpanBytes += segments[i];
+					if (this.decodeSpanBytes < this.audioBytesPerSecond) continue;
+					const endTs = monoMarkFrom(segmentTs[i]);
+					this.traceActions.decodes.push({
+						startTs: this.decodeSpanStart ?? decodeStartTs,
+						endTs,
+						pcmBytes: this.decodeSpanBytes
+					});
+					this.decodeSpanStart = endTs;
+					this.decodeSpanBytes = 0;
+				}
+				if (this.decodeSpanBytes > 0) {
+					const endTs = monoMarkFrom(segmentTs[segments.length - 1]);
+					this.traceActions.decodes.push({
+						startTs: this.decodeSpanStart ?? decodeStartTs,
+						endTs,
+						pcmBytes: this.decodeSpanBytes
+					});
+					this.decodeSpanStart = endTs;
+					this.decodeSpanBytes = 0;
+				}
 				this.addAudioChunkToBuffer(pcm, oggEnd);
 			}).catch((error) => {
 				logger.error("[AvatarController] Opus decode→buffer chain error:", error instanceof Error ? error.message : String(error));
 			});
 			this.networkLayer.sendAudioData(this.currentConversationId, audioData, end);
+			this.markAudioTap(sendAudioMs / 1e3 * this.audioBytesPerSecond);
 		} else {
 			this.receivedAudioBytes += audioData.byteLength;
-			this.markAudioTap(audioData.byteLength);
+			if (resolveUplinkAudioFormat() === "opus") this.markFirstAudioTap();
+			else this.markAudioTap(audioData.byteLength);
 			this.addAudioChunkToBuffer(new Uint8Array(audioData), end);
 			this.networkLayer.sendAudioData(this.currentConversationId, audioData, end);
 		}
@@ -2854,7 +3056,7 @@ var AvatarController = class {
 			const oggLast = isLast;
 			this.inputDecodeChain = this.inputDecodeChain.then(async () => {
 				await this.ensureInputOpusDecoder();
-				const pcm = await this.normalizeInputAudioToPcm(ogg);
+				const { pcm } = await this.normalizeInputAudioToPcm(ogg);
 				this.bufferHostPcm(pcm, oggLast);
 			}).catch((error) => {
 				logger.error("[AvatarController] Opus decode→buffer chain error:", error instanceof Error ? error.message : String(error));
@@ -2868,24 +3070,50 @@ var AvatarController = class {
 		return this.currentConversationId;
 	}
 	/**
+	* 记下 tap_0 —— 宿主送入首包音频的时刻，只抢零点、不参与分秒累计。
+	*
+	* 语义是「用户把第一块音频交给 SDK 的那一刻」，PCM 与 Opus 一视同仁：它是端到端
+	* 延迟的零点，上行发送、本地解码都发生在它之后，本就该被算进后续各段 Δ 里。
+	*
+	* 分秒（tap_N≥1）在各路径的「发出去」那一刻推进，见 markAudioTap / markAudioTapAt
+	* 的调用点。字节口径恒为 PCM（opus 输入由 granule 秒数折算），因为分母
+	* audioBytesPerSecond 按真实采样率算，直接用 Ogg 压缩字节会让 tap_N 几乎不递增。
+	* taps.set(0) 是 set-once，故这里先占、后面那次不会覆盖。
+	* @internal
+	*/
+	markFirstAudioTap() {
+		const marks = this.latencyMarks;
+		if (!marks.taps.has(0)) marks.taps.set(0, monoTimestamp());
+	}
+	/**
 	* 记一次音频 tap：tap_0=首包送入，之后每累计满整秒记一个 tap_N。
 	*
 	* **两种模式都走这里**（direct 由 send() 调、backend 由 bufferHostPcm 调），
 	* 所以只有这一份分秒逻辑。
 	*
-	* @param pcmByteLength 本块**解码后 PCM** 的字节数。必须是 PCM：分母
-	*   audioBytesPerSecond 按真实采样率算，若传 Opus 压缩字节（比 PCM 小 5-10 倍）
-	*   会让 tap_N 稀疏到几乎不递增。
+	* @param pcmByteLength 本块的 **PCM 口径**字节数。分母 audioBytesPerSecond 按真实
+	*   采样率算，直接传 Opus 压缩字节（比 PCM 小 5-10 倍）会让 tap_N 几乎不递增；
+	*   opus 输入不解码，故由 Ogg granule 的秒数折算成等价 PCM 字节再传进来。
 	* @internal
 	*/
 	markAudioTap(pcmByteLength) {
+		this.markAudioTapAt(pcmByteLength, monoTimestamp());
+	}
+	/**
+	* markAudioTap 的指定时刻版：这一秒音频「就绪」的时刻由调用方给，而不是取当下。
+	*
+	* 上行 Opus 的编码分段用它——那一秒的就绪时刻是它编完的时刻（回调触发时已过去
+	* 一小会儿），取 monoTimestamp() 会把编码后的排队/回调延迟算进 tap。
+	* @internal
+	*/
+	markAudioTapAt(pcmByteLength, at) {
 		const marks = this.latencyMarks;
-		if (!marks.taps.has(0)) marks.taps.set(0, monoTimestamp());
+		if (!marks.taps.has(0)) marks.taps.set(0, at);
 		marks.accumulatedBytes += pcmByteLength;
 		const currentDuration = marks.accumulatedBytes / this.audioBytesPerSecond;
 		let s = (marks.taps.size > 0 ? Math.max(...marks.taps.keys()) : 0) + 1;
 		while (currentDuration >= s) {
-			marks.taps.set(s, monoTimestamp());
+			marks.taps.set(s, at);
 			s++;
 		}
 	}
@@ -3149,8 +3377,12 @@ var AvatarController = class {
 		};
 		this.traceActions = {
 			sends: [],
-			recvs: []
+			recvs: [],
+			decodes: [],
+			encodes: []
 		};
+		this.decodeSpanStart = null;
+		this.decodeSpanBytes = 0;
 		this.lastOpusGranule = -1;
 	}
 	/**
@@ -3410,7 +3642,7 @@ var AvatarController = class {
 			const stateChanged = isOutOfBounds !== this.lastOutOfBoundsState;
 			const timeSinceLastLog = now - this.lastSyncLogTime;
 			if (stateChanged || timeSinceLastLog >= 1e3) {
-				logger.warn(`[PlaybackLoop] Frame index out of bounds! frameIndex: ${frameIndex}, maxAvailable: ${this.currentKeyframes.length - 1 + this.keyframesOffset}, using last frame`);
+				logger.warn(`[AvatarKit] Animation is running behind the audio: playback has reached ${(frameIndex / 25).toFixed(1)}s but only ${((this.currentKeyframes.length + this.keyframesOffset) / 25).toFixed(1)}s of animation has arrived, so the last available frame is being held. Send audio to the SDK faster than real time — at least 2s of audio per second of wall clock, ideally more — so animation frames can stay ahead of playback.`);
 				this.lastSyncLogTime = now;
 			}
 			this.lastOutOfBoundsState = isOutOfBounds;
@@ -3614,6 +3846,7 @@ var AvatarController = class {
 			this.animationPlayer.dispose();
 			this.animationPlayer = null;
 		}
+		setOpusEncodeSegmentSink(null);
 		if (this.inputOpusDecoderProxy) {
 			this.inputOpusDecoderProxy.destroy();
 			this.inputOpusDecoderProxy = null;
@@ -3799,6 +4032,7 @@ var AvatarManager = class AvatarManager {
 			if (task.status === "cancelled") return;
 			task.status = "failed";
 			const err = error instanceof Error ? error : new Error(String(error));
+			task._loadTrace?.end(false, Date.now(), { error: err.message });
 			this.notifyAllRequests(task, {
 				type: LoadProgress.failed,
 				error: err
@@ -3819,10 +4053,19 @@ var AvatarManager = class AvatarManager {
 		const { id, abortController } = task;
 		const signal = abortController.signal;
 		const startTime = Date.now();
+		const loadTrace = startLoadTrace(id, startTime, {
+			use_compressed_model: task.useCompressedModel,
+			source: "network"
+		});
+		task._loadTrace = loadTrace;
 		if (signal.aborted) throw new Error("Task cancelled");
 		task.status = "fetching-meta";
 		logger.log(`[AvatarManager] Fetching metadata for avatar ${id}...`);
+		const metaStart = Date.now();
+		loadTrace.span("prepare", startTime, metaStart);
 		const characterMeta = await this.avatarDownloader.getCharacterById(id, { signal });
+		const metaEnd = Date.now();
+		loadTrace.span("fetch_metadata", metaStart, metaEnd);
 		task.characterMeta = characterMeta;
 		if (signal.aborted) throw new Error("Task cancelled");
 		const cached = this.avatarCache.get(id);
@@ -3839,11 +4082,19 @@ var AvatarManager = class AvatarManager {
 					type: LoadProgress.downloading,
 					progress: 1
 				});
+				const hitEnd = Date.now();
+				loadTrace.span("prepare_assets", metaEnd, hitEnd, { cache_hit: true });
+				loadTrace.end(true, hitEnd, { cache_hit: true });
+				logMetric("fetch_avatar_latency", Date.now() - startTime, {
+					resolution: "default",
+					use_compressed_model: task.useCompressedModel,
+					cache_hit: true
+				}, { avatar_id: id });
 				return cached;
 			} else {
 				logger.log(`[AvatarManager] Avatar ${id} cache invalid: updatedAt=${cachedUpdatedAt}->${newUpdatedAt}, modelType=${cachedModelType}->${requestedModelType}, reloading...`);
 				this.avatarCache.delete(id);
-				const { PwaCacheManager } = await import("./pwa-cache-manager-BMKyJWXI.js").then((n) => n.n);
+				const { PwaCacheManager } = await import("./pwa-cache-manager-CcFR2ARt.js").then((n) => n.n);
 				await PwaCacheManager.clearCharacterCache(id);
 			}
 		}
@@ -3855,6 +4106,8 @@ var AvatarManager = class AvatarManager {
 		});
 		if (signal.aborted) throw new Error("Task cancelled");
 		task.status = "downloading";
+		const assetsStart = Date.now();
+		loadTrace.span("prepare_assets", metaEnd, assetsStart);
 		logger.log("[AvatarManager] Downloading resources...");
 		let downloadedCount = 0;
 		const resources = await this.avatarDownloader.preloadResources(characterMeta, {
@@ -3874,11 +4127,18 @@ var AvatarManager = class AvatarManager {
 		if (signal.aborted) throw new Error("Task cancelled");
 		logger.log("[AvatarManager] Creating Avatar instance...");
 		const avatar = new Avatar(id, characterMeta, resources, requestedModelType, false);
+		const loadEnd = Date.now();
+		loadTrace.span("load_assets", assetsStart, loadEnd, {
+			cache_hit: resources.cacheHit,
+			cache_type: resources.cacheType
+		});
+		loadTrace.end(true, loadEnd, { cache_hit: resources.cacheHit });
 		this.avatarCache.set(id, avatar);
 		logger.log("[AvatarManager] Avatar loaded successfully");
 		logMetric("fetch_avatar_latency", Date.now() - startTime, {
 			resolution: "default",
-			use_compressed_model: task.useCompressedModel
+			use_compressed_model: task.useCompressedModel,
+			cache_hit: resources.cacheHit
 		}, { avatar_id: id });
 		return avatar;
 	}