@spatius/avatarkit 1.3.1-beta.6 → 1.3.1

package/dist/core/AvatarController.d.ts

@@ -95,6 +95,16 @@ export declare class AvatarController {
      * frames received). Reset per conversation alongside latencyMarks.
      */
     private traceActions;
+    /** 上行编码分段的接收钩子，构造时装上、dispose 时卸下（见 setOpusEncodeSegmentSink）。 */
+    private readonly onEncodeSegment;
+    /**
+     * 解码 span 的聚合状态：累计满 1 秒 PCM 收一段。
+     *
+     * 跨 chunk 累计——宿主流式喂时一块可能远不足 1 秒，按块收段会碎成几百个 span。
+     * `decodeSpanStart` 是上一段的收尾时刻（null = 用本次 decode 的发起时刻当起点）。
+     */
+    private decodeSpanStart;
+    private decodeSpanBytes;
     /**
      * 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

package/dist/{error-utils-CqKOrHrY.js → error-utils-BogEllAd.js}

@@ -1,4 +1,4 @@
-import { mt as isDebugMode } from "./logger-fAU8oahT.js";
+import { _t as isDebugMode } from "./logger-BOpQ7u0w.js";
 //#region config/app-config.ts
 var GLOBAL_FLAME_CDN_BASE = "https://cdn.spatialwalk.cloud/public";
 var CN_FLAME_CDN_BASE = "https://cdn.spatialwalk.top/public";

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-CnZqa_X4.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-fAU8oahT.js";
-import { n as APP_CONFIG } from "./error-utils-CqKOrHrY.js";
-import { r as OggMuxer, t as OggPageSplitter } from "./OpusCodec-D9DcUV65.js";
-import { t as AvatarDownloader } from "./AvatarDownloader-Dfi7wtgQ.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-DgPvHU4L.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-BOpQ7u0w.js";
+import { a as startPlaybackTrace, i as startLoadTrace, o as buildTraceparent } from "./otel-trace-Ct4T48nC.js";
+import { n as APP_CONFIG } from "./error-utils-BogEllAd.js";
+import { r as OggMuxer, t as OggPageSplitter } from "./OpusCodec-CXU7ysrU.js";
+import { n as setOpusEncodeFrameSink } from "./OpusEncoderProxy-CzY-VckE.js";
+import { t as AvatarDownloader } from "./AvatarDownloader-DyhenPKd.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-D4q7c1U0.js");
-		const { AvatarSDK } = await import("./AvatarSDK-CnZqa_X4.js").then((n) => n.n);
+		const { StreamingAudioPlayer } = await import("./StreamingAudioPlayer-CIJmBp3z.js");
+		const { AvatarSDK } = await import("./AvatarSDK-DgPvHU4L.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;
@@ -1194,26 +1198,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 +1291,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 +1302,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 +1343,7 @@ var AnimationWebSocketClient = class extends EventEmitter {
 			return;
 		}
 		try {
-			const { OpusEncoderProxy } = await import("./OpusEncoderProxy-9YIZ7nIt.js");
+			const { OpusEncoderProxy } = await import("./OpusEncoderProxy-CzY-VckE.js").then((n) => n.t);
 			const bitrate = opusBitrate ?? 48e3;
 			this.opusEncoder = await OpusEncoderProxy.create(sampleRate, bitrate);
 			this.uplinkIsOpus = true;
@@ -2056,7 +2118,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 +2247,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 +2285,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;
@@ -2442,9 +2520,11 @@ var AvatarController = class {
 		recordMetric("playback_animation_frame_count", this.receivedAnimationFrames, labels);
 		recordMetric("playback_avg_fps", Math.round(stats.avgFps), labels);
 		recordMetric("playback_jank_frame_count", stats.jankFrameCount, labels);
-		recordMetric("playback_gpu_render_p50_ms", Math.round(stats.gpuRenderP50Ms), labels);
-		recordMetric("playback_gpu_render_p90_ms", Math.round(stats.gpuRenderP90Ms), labels);
-		recordMetric("playback_gpu_render_p95_ms", Math.round(stats.gpuRenderP95Ms), labels);
+		if (stats.gpuRenderP50Ms > 0) {
+			recordMetric("playback_gpu_render_p50_ms", Math.round(stats.gpuRenderP50Ms), labels);
+			recordMetric("playback_gpu_render_p90_ms", Math.round(stats.gpuRenderP90Ms), labels);
+			recordMetric("playback_gpu_render_p95_ms", Math.round(stats.gpuRenderP95Ms), labels);
+		}
 		recordMetric("playback_stall_count", stall.count, labels);
 		recordMetric("playback_stall_max_ms", stall.max_ms, labels);
 		recordMetric("playback_stall_total_ms", stall.total_ms, labels);
@@ -2455,9 +2535,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");
@@ -2495,6 +2580,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");
@@ -2522,6 +2615,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);
@@ -2628,7 +2759,7 @@ var AvatarController = class {
 		const { inputAudioFormat } = AvatarSDK.getAudioFormat();
 		if (inputAudioFormat !== "opus" || this.inputOpusDecoderProxy) return;
 		try {
-			const { OpusDecoderProxy } = await import("./OpusDecoderProxy-Ar_dFXRB.js");
+			const { OpusDecoderProxy } = await import("./OpusDecoderProxy-Cq8Z_MZY.js");
 			this.inputOpusDecoderProxy = await OpusDecoderProxy.create();
 			this.inputDecodeChain = Promise.resolve();
 		} catch (error) {
@@ -2647,15 +2778,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: []
+			};
 		}
 	}
 	/**
@@ -2703,6 +2847,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;
@@ -2730,17 +2875,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);
 		}
@@ -2852,7 +3021,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));
@@ -2866,24 +3035,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++;
 		}
 	}
@@ -3147,8 +3342,12 @@ var AvatarController = class {
 		};
 		this.traceActions = {
 			sends: [],
-			recvs: []
+			recvs: [],
+			decodes: [],
+			encodes: []
 		};
+		this.decodeSpanStart = null;
+		this.decodeSpanBytes = 0;
 		this.lastOpusGranule = -1;
 	}
 	/**
@@ -3408,7 +3607,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;
@@ -3612,6 +3811,7 @@ var AvatarController = class {
 			this.animationPlayer.dispose();
 			this.animationPlayer = null;
 		}
+		setOpusEncodeSegmentSink(null);
 		if (this.inputOpusDecoderProxy) {
 			this.inputOpusDecoderProxy.destroy();
 			this.inputOpusDecoderProxy = null;
@@ -3797,6 +3997,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
@@ -3817,10 +4018,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);
@@ -3837,11 +4047,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-CwXaM3xR.js").then((n) => n.n);
+				const { PwaCacheManager } = await import("./pwa-cache-manager-C7NbU52Q.js").then((n) => n.n);
 				await PwaCacheManager.clearCharacterCache(id);
 			}
 		}
@@ -3853,6 +4071,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, {
@@ -3872,11 +4092,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;
 	}
@@ -3911,7 +4138,13 @@ var AvatarManager = class AvatarManager {
 	* @returns Avatar instance, or undefined if not in cache
 	*/
 	retrieve(id) {
-		return this.avatarCache.get(id);
+		const trace = startLoadTrace(id, Date.now(), { source: "cache" });
+		const cached = this.avatarCache.get(id);
+		trace.end(true, Date.now(), {
+			result: cached ? "hit" : "miss",
+			cache_hit: cached !== void 0
+		});
+		return cached;
 	}
 	/**
 	* Clear cached avatar for specified ID

package/dist/internal-telemetry.d.ts

@@ -1,23 +1,4 @@
-/**
- * Internal telemetry surface for the companion RTC SDK.
- *
- * `@spatius/avatarkit-rtc` reports into the same OpenObserve backend and shares
- * this SDK's OTel providers, so its spans must sit on the same calibrated
- * timeline. Without that, a client whose wall clock is off puts RTC spans at a
- * time that does not line up with the server-side records they need to be read
- * against.
- *
- * Deliberately NOT re-exported from the package root: this is a bridge between
- * two first-party packages, not API for integrators. It exposes conversion only
- * — nothing here can alter the clock baseline.
- *
- * NOTE: nothing in this file may be tagged `@internal`. The dts plugin runs with
- * `stripInternal: true`, which erases such declarations from the emitted `.d.ts`
- * — the entry would still export both functions at runtime while shipping an
- * empty `export {}` type file, leaving the RTC package with no types.
- *
- * @packageDocumentation
- */
+import { Attributes } from '@opentelemetry/api';
 /**
  * Convert a `performance.now()` reading taken earlier into a timeline
  * timestamp (epoch ms), preferring the server-calibrated baseline and falling
@@ -35,3 +16,47 @@ export declare function resolveMonoTimestamp(mono: number): number;
  * resolve either way; this only reports whether they are server-aligned yet.
  */
 export declare function isClockCalibrated(): boolean;
+/**
+ * Handle for one round's trace.
+ *
+ * Declared here rather than re-exported from `utils/otel-trace`: the dts build
+ * excludes `utils/**`, so a type imported from there resolves to a file absent
+ * from the published package — which fails the whole module's type resolution,
+ * not just that one name.
+ *
+ * Structurally identical to the internal `PlaybackTrace`; the compiler checks
+ * the two match at `startPlaybackTrace`'s return below.
+ */
+export interface PlaybackTrace {
+    /** Add one interval span under the round's root. */
+    span(name: string, startMs: number, endMs: number, attrs?: Attributes, isError?: boolean): void;
+    /** Open a container span; spans added to the returned handle nest under it. */
+    group(name: string, startMs: number, attrs?: Attributes): SpanGroup;
+    /** Close the round's root span. */
+    end(ok?: boolean, endTimeMs?: number, attrs?: Attributes): void;
+}
+/** Sub-handle returned by {@link PlaybackTrace.group}. */
+export interface SpanGroup {
+    span(name: string, startMs: number, endMs: number, attrs?: Attributes, isError?: boolean): void;
+    end(endTimeMs?: number, attrs?: Attributes): void;
+}
+/**
+ * Open one round's trace: `driven.request` → `playback` → the caller's spans.
+ *
+ * Shared with the RTC SDK rather than reimplemented there, so both packages
+ * emit the same tree. The root's ids derive from the conversation id, which is
+ * what lets the backend's spans join a round without threading state through;
+ * reproducing that separately would mean two definitions of one wire contract.
+ */
+export declare function startPlaybackTrace(conversationId: string, startTimeMs?: number, attrs?: Attributes): PlaybackTrace;
+/**
+ * Record one measurement onto avatarkit's metric pipeline.
+ *
+ * Must go through here rather than the RTC SDK reaching for the global meter
+ * itself: a metrics export is skipped entirely unless that round carried real
+ * business data, and the flag saying so lives in this module. A histogram
+ * written directly through the global provider lands in the same instrument but
+ * leaves the flag clear, so the whole batch — RTC's readings included — is
+ * dropped before it is sent.
+ */
+export declare function recordMetric(name: string, value: number, attributes?: Attributes): void;