@xmov/avatar 2.0.0-alpha.38

package/src/utils/float32-decoder.js

@@ -0,0 +1,130 @@
+/**
+ * Base64 字符串 → Uint8Array 字节流（工具函数，处理 2 字节对齐）
+ * @param base64Str 服务端返回的 Base64 编码字符串（int16 字节流 Base64 后）
+ * @returns Uint8Array 字节流（2 字节/元素，对应 int16）
+ */
+function base64ToUint8Array(base64Str) {
+  if (!base64Str || base64Str.trim() === '') {
+    return new Uint8Array(0);
+  }
+
+  const binaryStr = atob(base64Str);
+  const uint8Array = new Uint8Array(binaryStr.length);
+  for (let i = 0; i < binaryStr.length; i++) {
+    uint8Array[i] = binaryStr.charCodeAt(i);
+  }
+  return uint8Array;
+}
+
+/**
+ * 2 字节小端序 → int16 数值（兼容服务端 np.clip 范围：-32767~32767）
+ * @param byte0 小端序低位字节
+ * @param byte1 小端序高位字节
+ * @returns 有符号 int16 数值（严格限制在 -32767~32767，与服务端一致）
+ */
+function twoByteToInt16(byte0, byte1) {
+  // 小端序合并为无符号 16 位整数
+  const uint16 = (byte0 << 0) | (byte1 << 8);
+  // 无符号 → 有符号 int16（自动处理负数）
+  let int16Value = uint16 > 32767 ? uint16 - 65536 : uint16;
+  // 兼容服务端 np.clip：强制限制范围（防止异常数据超出）
+  return Math.max(-32767, Math.min(32767, int16Value));
+}
+
+/**
+ * 服务端 floats_to_scaled_int16_bytes 反向函数：Base64 → float32 数组
+ * 核心逻辑：Base64→int16字节流→int16数值（兼容round+clip）→÷0x7FFF→float32
+ * @param base64Str 服务端返回的 Base64 编码字符串
+ * @returns float32 精度的浮点数数组（与服务端原始 floats 一致）
+ */
+export function scaledInt16BytesToFloat32(base64Str) {
+  // 步骤1：Base64 → Uint8Array 字节流
+  const uint8Array = base64ToUint8Array(base64Str);
+
+  // 校验：int16 占 2 字节，必须 2 字节对齐
+  if (uint8Array.length === 0 || uint8Array.length % 2 !== 0) {
+    return [];
+  }
+
+  const SCALE_FACTOR = 0x7FFF; // 与服务端一致：32767
+  const length = uint8Array.length / 2; // 计算 int16 元素个数
+
+  // 批量处理：用 Float32Array 确保 float32 精度（与服务端输入对齐）
+  const buffer = new ArrayBuffer(4 * length);
+  const float32View = new Float32Array(buffer);
+
+  // 步骤2：遍历解析+反量化
+  for (let i = 0; i < length; i++) {
+    const byteIndex = i * 2;
+    const byte0 = uint8Array[byteIndex];     // 小端序低位字节
+    const byte1 = uint8Array[byteIndex + 1]; // 小端序高位字节
+
+    // 步骤2.1：解析 int16（兼容服务端 round+clip）
+    const int16Value = twoByteToInt16(byte0, byte1);
+
+    // 步骤2.2：反量化（除以缩放因子，还原原始浮点数）
+    const floatValue = int16Value / SCALE_FACTOR;
+
+    // 步骤2.3：强制 float32 精度（消除 JS float64 多余精度）
+    float32View[i] = floatValue;
+  }
+
+  // 转为普通数组返回（方便业务使用）
+  return Array.from(float32View);
+}
+
+/**
+ * 可选：带平滑滤波的版本（解决“脸色闪”问题，优化视觉效果）
+ * @param base64Str 服务端 Base64 字符串
+ * @param lastData 上一帧数据（用于平滑）
+ * @param alpha 平滑系数（0~1，默认0.2，越大响应越快，越小越平滑）
+ * @returns 平滑后的 float32 数组
+ */
+export function scaledInt16BytesToSmoothFloat32(base64Str, lastData = [], alpha = 0.2) {
+  const rawData = scaledInt16BytesToFloat32(base64Str);
+  // 首次无历史数据，直接返回原始数据
+  if (lastData.length !== rawData.length) return rawData;
+
+  // 一阶低通滤波：current = alpha*raw + (1-alpha)*last
+  return rawData.map((val, idx) => {
+    return alpha * val + (1 - alpha) * lastData[idx];
+  });
+}
+
+
+/**
+ * 解析后端传输的 float32 字节流为普通数组
+ * @param {string|ArrayBuffer|Uint8Array} bytes - 后端传来的二进制数据（注意格式兼容）
+ * @returns {number[]} 解析后的浮点数组（空数据返回空数组）
+ */
+/**
+ * 从 Uint8Array 解析出 float32 数组（核心修复版）
+ * @param {Uint8Array} uint8Arr - 后端传来的 Uint8Array 原始字节
+ * @returns {number[]} 解析后的浮点数组
+ */
+export function parseUint8ToFloat32(uint8Arr) {
+ // 空值处理
+  if (!uint8Arr || uint8Arr.length === 0) {
+    return [];
+  }
+
+
+  // 步骤1：校验总字节数是否为 4 的倍数（float32 每个元素占 4 字节）
+  if (uint8Arr.length % 4 !== 0) {
+    window.avatarSDKLogger.error('Uint8Array长度不是4的倍数，无法解析为float32数组');
+    return [];
+  }
+
+  // 步骤2：创建新的 ArrayBuffer 并拷贝字节（强制偏移量为 0）
+  // 核心：不管原偏移量是多少，拷贝后新数组偏移量=0，必然满足 4 的倍数
+  const alignedBuffer = new ArrayBuffer(uint8Arr.length);
+  const alignedUint8 = new Uint8Array(alignedBuffer);
+  alignedUint8.set(uint8Arr); // 把原始字节拷贝到新数组
+
+  // 步骤3：基于对齐的 ArrayBuffer 创建 Float32Array
+  const float32Arr = new Float32Array(alignedBuffer);
+
+  // 步骤4：转普通数组返回
+  const result = Array.from(float32Arr);
+  return result;
+}

package/src/utils/fpsTracker.ts

@@ -0,0 +1,100 @@
+export interface FPSStats {
+  current: number;
+  average: number;
+  min: number;
+  max: number;
+  droppedFrames: number;
+  totalFrames: number;
+}
+
+export class FPSTracker {
+  private frameTimestamps: number[] = [];
+  private maxSamples: number;
+  private lastFrameTime: number = 0;
+  private frameCount: number = 0;
+  private lastUpdateTime: number = 0;
+  private currentFPS: number = 0;
+  private totalFrames: number = 0;
+  private totalTime: number = 0;
+  private droppedFrames: number = 0;
+  private totalRenderedFrames: number = 0;
+
+  constructor(maxSamples: number = 60) {
+    this.maxSamples = maxSamples;
+  }
+
+  tick(rendered: boolean = true): void {
+    const now = performance.now();
+    
+    if (this.lastFrameTime > 0) {
+      const delta = now - this.lastFrameTime;
+      this.frameTimestamps.push(delta);
+      
+      if (this.frameTimestamps.length > this.maxSamples) {
+        this.frameTimestamps.shift();
+      }
+      
+      this.totalFrames++;
+      this.totalTime += delta;
+      
+      if (rendered) {
+        this.frameCount++;
+        this.totalRenderedFrames++;
+      } else {
+        this.droppedFrames++;
+      }
+      
+      if (now - this.lastUpdateTime >= 1000) {
+        this.currentFPS = Math.round(this.frameCount * 1000 / (now - this.lastUpdateTime));
+        this.frameCount = 0;
+        this.lastUpdateTime = now;
+      }
+    }
+    
+    this.lastFrameTime = now;
+  }
+
+  getStats(): FPSStats {
+    if (this.frameTimestamps.length === 0) {
+      return { current: 0, average: 0, min: 0, max: 0, droppedFrames: 0, totalFrames: 0 };
+    }
+    
+    const avgDelta = this.frameTimestamps.reduce((a, b) => a + b, 0) / this.frameTimestamps.length;
+    const minDelta = Math.min(...this.frameTimestamps);
+    const maxDelta = Math.max(...this.frameTimestamps);
+    
+    return {
+      current: this.currentFPS,
+      average: this.frameTimestamps.length > 0 ? Math.round(1000 / avgDelta) : 0,
+      min: minDelta > 0 ? Math.round(1000 / maxDelta) : 0,
+      max: maxDelta > 0 ? Math.round(1000 / minDelta) : 0,
+      droppedFrames: this.droppedFrames,
+      totalFrames: this.totalFrames,
+    };
+  }
+
+  getCurrentFPS(): number {
+    return this.currentFPS;
+  }
+
+  getAverageFPS(): number {
+    if (this.totalTime === 0) return 0;
+    return Math.round(this.totalFrames * 1000 / this.totalTime);
+  }
+
+  reset(): void {
+    this.frameTimestamps = [];
+    this.lastFrameTime = 0;
+    this.frameCount = 0;
+    this.lastUpdateTime = 0;
+    this.currentFPS = 0;
+    this.totalFrames = 0;
+    this.totalTime = 0;
+    this.droppedFrames = 0;
+    this.totalRenderedFrames = 0;
+  }
+
+  getDroppedFrames(): number {
+    return this.droppedFrames;
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,182 @@
+// @ts-ignore
+const DefineENV = ENV
+export function isDEV() {
+  return DefineENV === "development";
+}
+export function isSupportMES() {
+  const ua = navigator.userAgent;
+  const vendor = navigator.vendor;
+
+  // 检查 userAgent 中是否包含 Chrome
+  const hasChrome = /Chrome/.test(ua);
+
+  // 检查 vendor 是否为 Google Inc.
+  const isGoogleVendor = /Google Inc/.test(vendor);
+
+  // Edge（基于 Chromium 的新版 Edge 也包含 Chrome 标识）
+  const isEdge = /Edg/.test(ua);
+
+  // MediaSource 支持性检查（可选）
+  const hasMediaSource = typeof (window as any).MediaSource !== "undefined";
+
+  return hasChrome && (isGoogleVendor || isEdge) && hasMediaSource;
+}
+
+export function getStyleStr(styles: Record<string, any>) {
+  return Object.entries(styles).map(([key, value]) => {
+    // 处理zIndex等数字属性转字符串
+    const val = typeof value === 'number' ? value.toString() : value;
+    // 驼峰转短横线（如zIndex → z-index）
+    const cssKey = key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+    return `${cssKey}:${val};`;
+  }).join('');
+}
+
+export function updateCanvasXOffset(canvas, offset_PX) {
+  // 1. 获取当前 transform 样式
+  const currentTransform = canvas.style.transform || '';
+  
+  // 2. 正则匹配现有 translateX 的值（提取数字）
+  const translateXRegex = /translateX\((-?\d+(\.\d+)?)px\)/;
+  
+  // 3. 计算新的偏移量（初始为0，匹配到则取原有值）
+  
+  // 4. 移除原有 translateX，拼接新值（保留其他 transform 效果）
+  const newTransform = currentTransform
+    .replace(translateXRegex, '') // 移除旧的 translateX
+    .trim() + ` translateX(${offset_PX}px)`; // 添加新的 translateX
+  
+  // 5. 应用新样式（去除多余空格）
+  canvas.style.transform = newTransform.replace(/\s+/g, ' ').trim();
+}
+
+// 生成设备指纹
+export function generateFingerprint() {
+  const screenSize = `${screen.width}x${screen.height}`;
+  const userAgent = navigator.userAgent;
+  const language = navigator.language;
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const fingerprint = encodeURIComponent(`${screenSize}|${userAgent}|${language}|${timezone}`); 
+  return btoa(fingerprint);
+}
+
+// 获取设备品牌及型号及版本号
+export function getDeviceInfo() {
+  const ua = navigator.userAgent;
+  let deviceBrand = 'Unknown Brand';
+  let deviceModel = 'Unknown Model';
+  let deviceVersion = 'Unknown Version';
+  let browserType = 'Unknown Browser';
+  let browserVersion = 'Unknown Version';
+  
+  // 获取操作系统版本
+  const windowsMatch = ua.match(/Windows NT (\d+\.\d+)/);
+  const androidMatch = ua.match(/Android (\d+\.\d+(\.\d+)?)/);
+  const iosMatch = ua.match(/OS (\d+_\d+(\._\d+)?) like Mac OS X/);
+  
+  if (windowsMatch) {
+    deviceVersion = `Windows NT ${windowsMatch[1]}`;
+  } else if (androidMatch) {
+    deviceVersion = `Android ${androidMatch[1]}`;
+  } else if (iosMatch) {
+    deviceVersion = `iOS ${iosMatch[1].replace(/_/g, '.')}`;
+  } else if (ua.includes('Macintosh')) {
+    deviceVersion = 'Macintosh';
+  } else if (ua.includes('Linux')) {
+    deviceVersion = 'Linux';
+  }
+  
+  // 匹配品牌 - 更准确的匹配逻辑
+  // 首先检查苹果设备
+  if (ua.includes('iPhone') || ua.includes('iPad') || ua.includes('iPod')) {
+    deviceBrand = 'Apple';
+    if (ua.includes('iPhone')) deviceModel = 'iPhone';
+    else if (ua.includes('iPad')) deviceModel = 'iPad';
+    else if (ua.includes('iPod')) deviceModel = 'iPod';
+  }
+  // 检查 Android 设备
+  else if (ua.includes('Android')) {
+    deviceBrand = 'Android';
+    deviceModel = 'Android';
+  }
+  // 检查 Windows 设备
+  else if (ua.includes('Windows')) {
+    deviceBrand = 'Windows';
+    if (ua.includes('Windows Phone')) deviceModel = 'Windows Phone';
+    else deviceModel = 'Windows Desktop';
+  }
+  // 检查 Linux 设备
+  else if (ua.includes('Linux')) {
+    deviceBrand = 'Linux';
+    deviceModel = 'Linux';
+  }
+  
+  // 匹配浏览器类型和版本
+  const chromeMatch = ua.match(/Chrome\/(\d+\.\d+\.\d+\.\d+)/);
+  const safariMatch = ua.match(/Version\/(\d+\.\d+(\.\d+)?) Safari/);
+  const firefoxMatch = ua.match(/Firefox\/(\d+\.\d+(\.\d+)?)\b/);
+  const edgeMatch = ua.match(/Edg\/(\d+\.\d+\.\d+\.\d+)/);
+  const operaMatch = ua.match(/Opera\/(\d+\.\d+)/);
+  const ieMatch = ua.match(/MSIE (\d+\.\d+)/);
+  
+  if (chromeMatch) {
+    browserType = 'Chrome';
+    browserVersion = chromeMatch[1];
+  } else if (safariMatch) {
+    browserType = 'Safari';
+    browserVersion = safariMatch[1];
+  } else if (firefoxMatch) {
+    browserType = 'Firefox';
+    browserVersion = firefoxMatch[1];
+  } else if (edgeMatch) {
+    browserType = 'Edge';
+    browserVersion = edgeMatch[1];
+  } else if (operaMatch) {
+    browserType = 'Opera';
+    browserVersion = operaMatch[1];
+  } else if (ieMatch) {
+    browserType = 'IE';
+    browserVersion = ieMatch[1];
+  }
+  
+  return {
+    device_id: generateFingerprint(),
+    device_brand: deviceBrand,
+    device_model: deviceModel,
+    os_version: deviceVersion,
+    browser: browserType,
+    browser_version: browserVersion,
+    browser_ua: ua,
+  };
+}
+
+// ---------------------- 扩展：支持小数的版本（可选） ----------------------
+/**
+ * 校验scale格式（支持小数）并返回合法值
+ * @param {unknown} scale - 待校验的scale值
+ * @param {string} tag - 日志标签
+ * @returns {number | string} 合法值，非法返回1
+ */
+export function validateScaleWithDecimal(scale: unknown, tag: string): number | string {
+  const validVhRegex = /^\d+(\.\d+)?vh$/; // 支持 "1.5vh"、"10vh"
+  const validNumberStrRegex = /^\d+(\.\d+)?$/; // 支持 "2.8"、"5"
+
+  if (typeof scale === 'number') {
+    return scale;
+  }
+
+  if (typeof scale === 'string' && (validVhRegex.test(scale) || validNumberStrRegex.test(scale))) {
+    return scale;
+  }
+
+  (window as any).avatarSDKLogger?.warn(
+    tag,
+    'scale 必须是数字、带小数的数字字符串或者"xxxvh"格式（xxx为数字/小数）'
+  );
+  return 1;
+}
+
+export function isharmony() {
+  const userAgent = (navigator.userAgent || "").toLowerCase();
+  return /openharmony|arkweb/.test(userAgent);
+}

package/src/utils/logger.js

@@ -0,0 +1,36 @@
+// logger.js - 改进的单例日志系统
+let isLoggingEnabled = false;
+
+function executeLog(consoleMethod, ...args) {
+  // 边界防护：1. 开关关闭 2. 控制台方法不存在（兼容异常环境）
+  if (!isLoggingEnabled || typeof consoleMethod !== 'function') {
+    return;
+  }
+  // 统一拼接前缀，执行原生控制台方法
+  consoleMethod( ...args);
+}
+
+const sdkLog = {
+  log: (...args) => executeLog(console.log, ...args),
+  info: (...args) => executeLog(console.info, ...args),
+  warn: (...args) => executeLog(console.warn, ...args),
+  error: (...args) => executeLog(console.error, ...args)
+};
+
+
+// 对外暴露的配置方法
+function setLoggingEnabled(enabled) {
+  isLoggingEnabled = enabled;
+  // 可选：添加日志说明当前日志状态变化
+  if (!enabled) {
+    console.log('[AVATAR SDK] version:', VERSION, '日志已禁用');
+  } else {
+    console.log('[AVATAR SDK] version:', VERSION, '日志已启用');
+  }
+}
+
+// 定义完整的日志对象
+window.avatarSDKLogger = {
+  ...sdkLog,
+  setEnabled: setLoggingEnabled
+};

package/src/utils/media-recorder-timestamp.ts

@@ -0,0 +1,79 @@
+type EpochClock = () => number;
+
+function monotonicEpochNow() {
+  const clock = globalThis.performance;
+  if (
+    clock
+    && Number.isFinite(clock.timeOrigin)
+    && typeof clock.now === "function"
+  ) {
+    return clock.timeOrigin + clock.now();
+  }
+  return Date.now();
+}
+
+/** Normalizes browser-specific BlobEvent.timecode units to epoch milliseconds. */
+export class MediaRecorderTimestamp {
+  private readonly startedAt: number;
+  private readonly now: EpochClock;
+  private timecodeScale: 1 | 1000 | null = null;
+  private firstTimecode: number | null = null;
+  private lastTimecode: number | null = null;
+  private lastObservedAt: number | null = null;
+  private lastTimestamp: number | null = null;
+
+  constructor(
+    private readonly chunkMs: number,
+    now: EpochClock = monotonicEpochNow,
+  ) {
+    this.now = now;
+    this.startedAt = now();
+  }
+
+  resolve(timecode: number): number {
+    const observedAt = this.now();
+    const validTimecode = Number.isFinite(timecode) && timecode >= 0;
+
+    if (validTimecode && this.firstTimecode === null) {
+      this.firstTimecode = timecode;
+    }
+
+    if (
+      validTimecode
+      && this.timecodeScale === null
+      && this.lastTimecode !== null
+      && timecode > this.lastTimecode
+    ) {
+      const timecodeDelta = timecode - this.lastTimecode;
+      const observedDelta = this.lastObservedAt === null ? 0 : observedAt - this.lastObservedAt;
+      const expectedDelta = observedDelta >= this.chunkMs / 4 ? observedDelta : this.chunkMs;
+      const millisecondError = Math.abs(timecodeDelta - expectedDelta);
+      const secondError = Math.abs(timecodeDelta * 1000 - expectedDelta);
+      this.timecodeScale = secondError < millisecondError ? 1000 : 1;
+    }
+
+    let timestamp = observedAt - this.chunkMs;
+    const relativeTimecode = validTimecode && this.firstTimecode !== null
+      ? timecode - this.firstTimecode
+      : null;
+    if (
+      relativeTimecode !== null
+      && relativeTimecode >= 0
+      && (this.timecodeScale !== null || relativeTimecode === 0)
+    ) {
+      timestamp = this.startedAt + relativeTimecode * (this.timecodeScale ?? 1);
+    }
+
+    if (this.lastTimestamp !== null) {
+      // A non-empty MediaRecorder Blob must not collapse into an already-used
+      // AU bucket when a browser repeats or resets its timecode.
+      timestamp = Math.max(timestamp, this.lastTimestamp + this.chunkMs);
+    }
+
+    const resolved = Math.max(Math.round(this.startedAt), Math.round(timestamp));
+    this.lastTimecode = validTimecode ? timecode : this.lastTimecode;
+    this.lastObservedAt = observedAt;
+    this.lastTimestamp = resolved;
+    return resolved;
+  }
+}

package/src/utils/pcmAnalyzer.ts

@@ -0,0 +1,154 @@
+/**
+ * PCM 音频参数分析工具
+ * 用于检测和分析 PCM 音频数据的基本参数
+ */
+
+export interface PCMAudioParams {
+  sampleRate: number;        // 采样率 (Hz)
+  channels: number;          // 声道数 (1=单声道, 2=双声道)
+  bitDepth: number;          // 位深度 (8, 16, 24, 32)
+  format: string;            // 格式 (S16LE, S24LE, F32LE 等)
+  encoding: string;          // 编码方式 (PCM)
+  bytesPerSample: number;    // 每个采样点的字节数
+  sampleCount?: number;      // 样本数量（如果提供了数据）
+  duration?: number;         // 时长（秒）（如果提供了数据）
+}
+
+/**
+ * 分析 PCM 音频数据的基本参数
+ * @param pcmData PCM 音频数据（Uint8Array）
+ * @param knownSampleRate 已知的采样率（可选，如果不提供则使用默认值 24000）
+ * @returns PCM 音频参数
+ */
+export function analyzePCMParams(
+  pcmData?: Uint8Array,
+  knownSampleRate?: number
+): PCMAudioParams {
+  // 根据代码中的配置，PCM 音频使用固定参数
+  const sampleRate = knownSampleRate || 24000;
+  const channels = 1; // 单声道
+  const bitDepth = 16; // 16位
+  const format = 'S16LE'; // Signed 16-bit Little Endian
+  const encoding = 'PCM'; // 未压缩的 PCM 编码
+  const bytesPerSample = 2; // 16位 = 2字节/采样点
+
+  let sampleCount: number | undefined;
+  let duration: number | undefined;
+
+  if (pcmData) {
+    // 计算样本数量
+    sampleCount = Math.floor(pcmData.length / bytesPerSample);
+    // 计算时长（秒）
+    duration = sampleCount / sampleRate;
+  }
+
+  return {
+    sampleRate,
+    channels,
+    bitDepth,
+    format,
+    encoding,
+    bytesPerSample,
+    sampleCount,
+    duration,
+  };
+}
+
+/**
+ * 检测 PCM 数据的可能参数（通过分析数据特征）
+ * 注意：这种方法只能提供推测，最准确的参数应该从服务器配置中获取
+ * @param pcmData PCM 音频数据
+ * @returns 检测到的参数（可能不准确）
+ */
+export function detectPCMParams(pcmData: Uint8Array): Partial<PCMAudioParams> {
+  const dataLength = pcmData.length;
+  
+  // 检测位深度和字节序
+  // 由于数据是 16 位，每个样本占 2 字节
+  const bytesPerSample = 2; // 根据代码，固定为 2 字节（16位）
+  const bitDepth = 16;
+  
+  // 检测声道数（通过数据长度和样本对齐）
+  // 如果数据长度是 2 的倍数，可能是单声道
+  // 如果数据长度是 4 的倍数，可能是双声道
+  let channels = 1;
+  if (dataLength % 4 === 0) {
+    // 可能是双声道（2 通道 × 2 字节 = 4 字节/样本）
+    // 但根据代码，这里固定为单声道
+    channels = 1;
+  }
+  
+  // 尝试检测采样率（这个很难准确检测，只能推测）
+  // 如果知道数据时长和样本数，可以反推采样率
+  const sampleCount = Math.floor(dataLength / bytesPerSample);
+  
+  return {
+    channels,
+    bitDepth,
+    format: 'S16LE', // 根据代码，固定为 S16LE
+    encoding: 'PCM',
+    bytesPerSample,
+    sampleCount,
+  };
+}
+
+/**
+ * 格式化显示 PCM 参数
+ * @param params PCM 音频参数
+ * @returns 格式化的字符串
+ */
+export function formatPCMParams(params: PCMAudioParams): string {
+  const parts = [
+    `采样率: ${params.sampleRate} Hz`,
+    `声道: ${params.channels === 1 ? '单声道 (Mono)' : `双声道 (Stereo, ${params.channels} channels)`}`,
+    `位深度: ${params.bitDepth} bit`,
+    `格式: ${params.format}`,
+    `编码: ${params.encoding}`,
+    `每样本字节数: ${params.bytesPerSample} bytes`,
+  ];
+
+  if (params.sampleCount !== undefined) {
+    parts.push(`样本数: ${params.sampleCount.toLocaleString()}`);
+  }
+
+  if (params.duration !== undefined) {
+    parts.push(`时长: ${params.duration.toFixed(3)} 秒 (${(params.duration * 1000).toFixed(0)} ms)`);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * 从音频渲染器获取当前 PCM 配置
+ * @param audioRenderer 音频渲染器实例
+ * @returns PCM 音频参数
+ */
+export function getPCMParamsFromRenderer(audioRenderer: any): PCMAudioParams {
+  // 尝试从 AudioWorklet 或 Audio 播放器获取配置
+  let sampleRate = 24000; // 默认值
+  let channels = 1;
+  let bitDepth = 16;
+  let format = 'S16LE';
+  let bytesPerSample = 2;
+
+  // 检查 AudioWorklet
+  if (audioRenderer?.audio?.audioCtx) {
+    sampleRate = audioRenderer.audio.audioCtx.sampleRate || 24000;
+  }
+
+  // 检查旧的 Audio 播放器
+  if (audioRenderer?.audio?.SAMPLE_RATE) {
+    sampleRate = audioRenderer.audio.SAMPLE_RATE;
+  }
+
+  // 根据代码，PCM 音频固定使用这些参数
+  return {
+    sampleRate,
+    channels,
+    bitDepth,
+    format,
+    encoding: 'PCM',
+    bytesPerSample,
+  };
+}
+