第十一章：移动端兼容与性能优化 —— 让音频应用在所有设备上流畅运行

// ❌ 错误：异步间隔导致 iOS 拒绝播放
button.addEventListener('click', async () => {
  const response = await fetch('music.mp3'); // 异步！iOS 会拒绝后续的 play()
  const blob = await response.blob();
  audio.src = URL.createObjectURL(blob);
  await audio.play(); // NotAllowedError
});
 
// ✅ 正确：先触发播放，再加载内容
button.addEventListener('click', () => {
  // 在同步上下文中立即调用 play()
  audio.play().catch(() => {});
 
  // 然后异步加载实际内容
  loadAndSwapSource(audio, 'music.mp3');
});
 
async function loadAndSwapSource(audio, url) {
  // 先播放一个空的或已缓存的音频"解锁"播放器
  // 然后切换到真实内容
  const response = await fetch(url);
  const blob = await response.blob();
  const wasPlaying = !audio.paused;
  audio.src = URL.createObjectURL(blob);
  if (wasPlaying) audio.play();
}

class IOSAudioUnlocker {
  constructor() {
    this.unlocked = false;
    this.audioCtx = null;
    this._pendingCallbacks = [];
  }
 
  // 在 App 初始化时调用，注册解锁监听
  setup(audioCtx) {
    this.audioCtx = audioCtx;
 
    if (audioCtx.state === 'running') {
      this.unlocked = true;
      return;
    }
 
    // 监听所有可能的用户交互事件
    const events = ['touchstart', 'touchend', 'mousedown', 'keydown', 'click'];
    const unlock = async () => {
      if (this.unlocked) return;
 
      try {
        // 方法一：resume AudioContext
        await audioCtx.resume();
 
        // 方法二：播放并立即暂停一个空 Buffer（更可靠）
        const buffer = audioCtx.createBuffer(1, 1, 22050);
        const source = audioCtx.createBufferSource();
        source.buffer = buffer;
        source.connect(audioCtx.destination);
        source.start(0);
        source.stop(0.001);
 
        if (audioCtx.state === 'running') {
          this.unlocked = true;
          events.forEach(e => document.removeEventListener(e, unlock));
 
          // 执行所有等待解锁的回调
          this._pendingCallbacks.forEach(cb => cb());
          this._pendingCallbacks = [];
 
          console.log('AudioContext 已在 iOS 上解锁');
        }
      } catch (err) {
        console.warn('AudioContext 解锁失败:', err);
      }
    };
 
    events.forEach(e =>
      document.addEventListener(e, unlock, { passive: true })
    );
  }
 
  // 等待解锁后执行
  whenUnlocked(callback) {
    if (this.unlocked) {
      callback();
    } else {
      this._pendingCallbacks.push(callback);
    }
  }
}
 
// 全局单例
const iosUnlocker = new IOSAudioUnlocker();
 
// App 启动时
const audioCtx = new (window.AudioContext || window.webkitAudioContext)();
iosUnlocker.setup(audioCtx);
 
// 需要播放时
iosUnlocker.whenUnlocked(() => {
  startPlayback();
});

// 兼容写法（覆盖所有版本）
const AudioContext = window.AudioContext || window.webkitAudioContext;
const audioCtx = new AudioContext();
 
// 同样需要处理的带前缀 API
const OfflineAudioContext =
  window.OfflineAudioContext || window.webkitOfflineAudioContext;

// 监听 AudioContext 状态变化
audioCtx.addEventListener('statechange', () => {
  console.log('AudioContext 状态:', audioCtx.state);
 
  if (audioCtx.state === 'suspended') {
    // 音频被中断（来电等）
    showInterruptedUI();
    pauseAllPlayback();
  } else if (audioCtx.state === 'running') {
    // 中断结束，恢复播放
    hideInterruptedUI();
    // 注意：iOS 不会自动恢复播放，需要用户手动触发
  }
});
 
// Page Visibility API：页面切到后台时处理
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    // 页面进入后台
    // iOS Safari 会暂停 AudioContext，但 <audio> 标签可以继续播放
    console.log('页面进入后台');
  } else {
    // 页面回到前台
    if (audioCtx.state === 'suspended') {
      // 不要在这里自动 resume，iOS 要求用户交互
      showResumePrompt();
    }
  }
});

// iOS Safari 的格式支持检测（有些版本行为特殊）
function getIOSCompatibleFormats() {
  const audio = new Audio();
  return {
    // iOS 全版本支持
    aac:  audio.canPlayType('audio/aac') !== '',
    mp3:  audio.canPlayType('audio/mpeg') !== '',
    mp4:  audio.canPlayType('audio/mp4') !== '',
 
    // iOS 11+ 支持
    flac: audio.canPlayType('audio/flac') !== '',
 
    // iOS 15.4+ 才支持（很多用户版本更低！）
    opus: audio.canPlayType('audio/ogg; codecs="opus"') !== '',
    webm: audio.canPlayType('audio/webm') !== '',
  };
}
 
// iOS 安全的格式优先级
const IOS_FORMAT_PRIORITY = [
  { type: 'audio/aac',  ext: 'aac'  },
  { type: 'audio/mp4',  ext: 'm4a'  },
  { type: 'audio/mpeg', ext: 'mp3'  },
];

class AudioFocusManager {
  constructor(audioEl) {
    this.audio = audioEl;
    this.wasPlayingBeforeInterruption = false;
    this._setup();
  }
 
  _setup() {
    // 使用 Page Visibility API 模拟焦点变化
    document.addEventListener('visibilitychange', () => {
      if (document.hidden) {
        this.wasPlayingBeforeInterruption = !this.audio.paused;
        // Android 后台不暂停（除非系统强制）
      } else {
        // 回到前台
        if (this.wasPlayingBeforeInterruption && this.audio.paused) {
          // 尝试恢复（Android 通常允许）
          this.audio.play().catch(console.warn);
        }
      }
    });
 
    // 监听 Media Session API（Android Chrome 支持）
    if ('mediaSession' in navigator) {
      navigator.mediaSession.setActionHandler('pause', () => {
        this.audio.pause();
      });
      navigator.mediaSession.setActionHandler('play', () => {
        this.audio.play();
      });
    }
  }
}

class MediaSessionController {
  constructor(audioEl) {
    this.audio = audioEl;
 
    if (!('mediaSession' in navigator)) {
      console.warn('Media Session API 不支持');
      return;
    }
 
    this._setupActions();
  }
 
  // 更新媒体元数据（显示在通知栏）
  updateMetadata({ title, artist, album, artwork }) {
    navigator.mediaSession.metadata = new MediaMetadata({
      title,
      artist,
      album,
      artwork: artwork.map(art => ({
        src:   art.src,
        sizes: art.sizes || '512x512',
        type:  art.type  || 'image/jpeg',
      })),
    });
  }
 
  // 更新播放状态（让系统知道当前是否在播放）
  updatePlaybackState(state) {
    // state: 'playing' | 'paused' | 'none'
    navigator.mediaSession.playbackState = state;
  }
 
  // 更新进度条（系统通知栏的进度显示）
  updatePositionState() {
    if (!this.audio.duration) return;
    navigator.mediaSession.setPositionState({
      duration:     this.audio.duration,
      playbackRate: this.audio.playbackRate,
      position:     this.audio.currentTime,
    });
  }
 
  _setupActions() {
    const handlers = {
      'play':           () => this.audio.play(),
      'pause':          () => this.audio.pause(),
      'stop':           () => { this.audio.pause(); this.audio.currentTime = 0; },
      'seekbackward':   (d) => { this.audio.currentTime -= d.seekOffset || 10; },
      'seekforward':    (d) => { this.audio.currentTime += d.seekOffset || 10; },
      'seekto':         (d) => { if (d.seekTime) this.audio.currentTime = d.seekTime; },
      'previoustrack':  () => playPrevious(),
      'nexttrack':      () => playNext(),
    };
 
    Object.entries(handlers).forEach(([action, handler]) => {
      try {
        navigator.mediaSession.setActionHandler(action, handler);
      } catch (e) {
        // 部分浏览器不支持某些 action，忽略错误
      }
    });
 
    // 同步播放状态
    this.audio.addEventListener('play',  () => this.updatePlaybackState('playing'));
    this.audio.addEventListener('pause', () => this.updatePlaybackState('paused'));
    this.audio.addEventListener('timeupdate', () => this.updatePositionState());
  }
}
 
// 使用
const session = new MediaSessionController(audio);
session.updateMetadata({
  title:   '夜空中最亮的星',
  artist:  '逃跑计划',
  album:   'PLAN A',
  artwork: [{ src: 'cover.jpg', sizes: '512x512' }],
});

// 检测是否在 WebView 中运行
function isAndroidWebView() {
  const ua = navigator.userAgent;
  return /Android/.test(ua) && /wv/.test(ua);
}
 
// WebView 中的音频处理策略
if (isAndroidWebView()) {
  // WebView 默认禁用自动播放，需要原生层配置：
  // webView.getSettings().setMediaPlaybackRequiresUserGesture(false);
 
  // 检测是否支持特定格式
  const audio = new Audio();
  if (audio.canPlayType('audio/ogg') === '') {
    // 部分 WebView 不支持 OGG，强制使用 MP3
    console.warn('WebView 不支持 OGG，切换到 MP3');
  }
}

// 1. 复用 AudioContext（全局单例，不要每次创建新的）
class AudioContextManager {
  static _instance = null;
 
  static getInstance() {
    if (!this._instance) {
      this._instance = new (window.AudioContext || window.webkitAudioContext)({
        // 低延迟模式（移动端谨慎使用，耗电更多）
        latencyHint: 'playback', // 'interactive' | 'balanced' | 'playback'
        sampleRate: 44100,       // 明确指定采样率，避免重采样开销
      });
    }
    return this._instance;
  }
}
 
// 2. 不用时挂起 AudioContext，节省 CPU
async function suspendWhenIdle(audioCtx) {
  if (audioCtx.state === 'running') {
    await audioCtx.suspend();
    console.log('AudioContext 已挂起，节省 CPU');
  }
}
 
// 3. 及时断开不用的节点
function disconnectUnusedNodes(nodes) {
  nodes.forEach(node => {
    try {
      node.disconnect();
    } catch (e) {
      // 已断开的节点 disconnect() 会抛出，忽略
    }
  });
}

class AudioBufferCache {
  constructor(maxSize = 50) {
    this.cache   = new Map();   // url → AudioBuffer
    this.maxSize = maxSize;
    this.loading = new Map();   // url → Promise（防止重复请求）
  }
 
  async get(url, audioCtx) {
    // 已缓存
    if (this.cache.has(url)) {
      return this.cache.get(url);
    }
 
    // 正在加载中（防止并发重复请求）
    if (this.loading.has(url)) {
      return this.loading.get(url);
    }
 
    // 发起新的加载
    const promise = this._load(url, audioCtx);
    this.loading.set(url, promise);
 
    try {
      const buffer = await promise;
      this._set(url, buffer);
      return buffer;
    } finally {
      this.loading.delete(url);
    }
  }
 
  async _load(url, audioCtx) {
    const response    = await fetch(url);
    const arrayBuffer = await response.arrayBuffer();
    return audioCtx.decodeAudioData(arrayBuffer);
  }
 
  _set(url, buffer) {
    // LRU：超出容量时删除最早的条目
    if (this.cache.size >= this.maxSize) {
      const firstKey = this.cache.keys().next().value;
      this.cache.delete(firstKey);
    }
    this.cache.set(url, buffer);
  }
 
  // 预加载一组音频
  async preload(urls, audioCtx, onProgress) {
    let loaded = 0;
    await Promise.all(urls.map(async url => {
      await this.get(url, audioCtx);
      loaded++;
      onProgress?.(loaded / urls.length);
    }));
  }
 
  clear() { this.cache.clear(); }
 
  get size() { return this.cache.size; }
}
 
// 全局缓存实例
const bufferCache = new AudioBufferCache(30);
 
// 游戏场景：预加载所有音效
await bufferCache.preload(
  ['shoot.mp3', 'explosion.mp3', 'pickup.mp3', 'bgm.mp3'],
  audioCtx,
  (progress) => console.log(`预加载进度: %`)
);

// 对象池：复用 AudioBufferSourceNode（避免频繁创建销毁）
class AudioSourcePool {
  constructor(audioCtx, poolSize = 10) {
    this.ctx      = audioCtx;
    this.poolSize = poolSize;
    this.active   = new Set();   // 正在播放的节点
  }
 
  play(buffer, options = {}) {
    // 超出池大小时，停止最早的节点
    if (this.active.size >= this.poolSize) {
      const oldest = this.active.values().next().value;
      oldest.stop();
      this.active.delete(oldest);
    }
 
    const source = this.ctx.createBufferSource();
    source.buffer             = buffer;
    source.playbackRate.value = options.playbackRate || 1;
    source.loop               = options.loop || false;
 
    // 连接到目标（可以是效果链或直接输出）
    const dest = options.destination || this.ctx.destination;
    source.connect(dest);
 
    source.addEventListener('ended', () => {
      this.active.delete(source);
    });
 
    source.start(options.when || 0, options.offset || 0);
    this.active.add(source);
    return source;
  }
 
  stopAll() {
    this.active.forEach(source => {
      try { source.stop(); } catch (e) {}
    });
    this.active.clear();
  }
}

class MobileOptimizedVisualizer {
  constructor(analyser, canvas) {
    this.analyser = analyser;
    this.canvas   = canvas;
    this.ctx      = canvas.getContext('2d', {
      // 告知浏览器不需要读取像素（优化 GPU 内存）
      willReadFrequently: false,
      // 关闭抗锯齿（移动端性能优先）
      antialias: false,
    });
 
    // 根据设备性能降级
    this.quality = this._detectQuality();
 
    // 移动端降低 FFT 精度
    if (this.quality === 'low') {
      this.analyser.fftSize = 512;  // 桌面用 2048，移动端用 512
    } else if (this.quality === 'medium') {
      this.analyser.fftSize = 1024;
    }
 
    this.bufferLength = this.analyser.frequencyBinCount;
    this.dataArray    = new Uint8Array(this.bufferLength);
 
    // 帧率控制
    this.targetFPS    = this.quality === 'low' ? 24 : 60;
    this.frameInterval = 1000 / this.targetFPS;
    this.lastFrameTime = 0;
 
    this.animId = null;
  }
 
  _detectQuality() {
    // 通过 hardwareConcurrency 估算设备性能
    const cores = navigator.hardwareConcurrency || 2;
    const mem   = navigator.deviceMemory || 2; // GB，部分浏览器支持
 
    if (cores <= 2 || mem <= 1) return 'low';
    if (cores <= 4 || mem <= 2) return 'medium';
    return 'high';
  }
 
  start() {
    const loop = (timestamp) => {
      this.animId = requestAnimationFrame(loop);
 
      // 帧率限制：跳过不需要渲染的帧
      if (timestamp - this.lastFrameTime < this.frameInterval) return;
      this.lastFrameTime = timestamp;
 
      this._draw();
    };
    requestAnimationFrame(loop);
  }
 
  stop() {
    cancelAnimationFrame(this.animId);
    this.animId = null;
  }
 
  _draw() {
    this.analyser.getByteFrequencyData(this.dataArray);
 
    const { ctx, canvas } = this;
    const W = canvas.width, H = canvas.height;
 
    // 低质量模式：减少绘制细节
    const barCount = this.quality === 'low' ? 32 : 64;
 
    ctx.fillStyle = '#0a0a1a';
    ctx.fillRect(0, 0, W, H);
 
    const barWidth = W / barCount;
    for (let i = 0; i < barCount; i++) {
      // 降采样：从完整数据中取样
      const dataIndex = Math.floor(i / barCount * this.bufferLength);
      const value     = this.dataArray[dataIndex] / 255;
      const barH      = value * H * 0.9;
 
      ctx.fillStyle = `hsl(, 90%, 55%)`;
      ctx.fillRect(i * barWidth, H - barH, barWidth - 1, barH);
    }
  }
}

class AudioResourceManager {
  constructor() {
    this.objectURLs   = new Set(); // 追踪所有创建的 Object URL
    this.audioContexts = new Set();
    this.streams      = new Set();
  }
 
  // 创建并追踪 Object URL
  createObjectURL(blob) {
    const url = URL.createObjectURL(blob);
    this.objectURLs.add(url);
    return url;
  }
 
  // 追踪 MediaStream
  trackStream(stream) {
    this.streams.add(stream);
    return stream;
  }
 
  // 追踪 AudioContext
  trackContext(ctx) {
    this.audioContexts.add(ctx);
    return ctx;
  }
 
  // 释放单个资源
  revokeObjectURL(url) {
    URL.revokeObjectURL(url);
    this.objectURLs.delete(url);
  }
 
  // 停止并释放 MediaStream
  releaseStream(stream) {
    stream.getTracks().forEach(t => t.stop());
    this.streams.delete(stream);
  }
 
  // 全量释放（页面卸载时调用）
  releaseAll() {
    // 释放所有 Object URL
    this.objectURLs.forEach(url => URL.revokeObjectURL(url));
    this.objectURLs.clear();
 
    // 停止所有 MediaStream
    this.streams.forEach(stream => {
      stream.getTracks().forEach(t => t.stop());
    });
    this.streams.clear();
 
    // 关闭所有 AudioContext
    this.audioContexts.forEach(ctx => {
      if (ctx.state !== 'closed') ctx.close();
    });
    this.audioContexts.clear();
 
    console.log('所有音频资源已释放');
  }
}
 
const resourceManager = new AudioResourceManager();
 
// 页面卸载时全量释放
window.addEventListener('beforeunload', () => {
  resourceManager.releaseAll();
});
 
// SPA 路由切换时释放
router.beforeEach((to, from, next) => {
  if (from.meta.hasAudio) {
    resourceManager.releaseAll();
  }
  next();
});

class AdaptiveAudioLoader {
  constructor() {
    this.connectionType = this._getConnectionType();
    this._monitorNetwork();
  }
 
  _getConnectionType() {
    const conn = navigator.connection ||
                 navigator.mozConnection ||
                 navigator.webkitConnection;
 
    if (!conn) return 'unknown';
 
    // effectiveType: 'slow-2g' | '2g' | '3g' | '4g'
    return conn.effectiveType || 'unknown';
  }
 
  _monitorNetwork() {
    const conn = navigator.connection;
    if (!conn) return;
 
    conn.addEventListener('change', () => {
      const prev = this.connectionType;
      this.connectionType = this._getConnectionType();
      console.log(`网络类型变化: [] → []`);
      this._onNetworkChange(prev, this.connectionType);
    });
  }
 
  _onNetworkChange(prev, current) {
    // 网络变差时降低音质
    if (this._isWorse(prev, current)) {
      this.switchToLowQuality();
    }
    // 网络变好时可以提升音质
    else if (this._isBetter(prev, current)) {
      this.switchToHighQuality();
    }
  }
 
  _isWorse(prev, current) {
    const order = ['4g', '3g', '2g', 'slow-2g'];
    return order.indexOf(current) > order.indexOf(prev);
  }
 
  _isBetter(prev, current) {
    return this._isWorse(current, prev);
  }
 
  // 根据网络条件选择最优音频 URL
  getBestAudioUrl(urls) {
    // urls: { hq: '...256k.aac', mq: '...128k.aac', lq: '...64k.aac' }
    const qualityMap = {
      '4g':      'hq',
      '3g':      'mq',
      '2g':      'lq',
      'slow-2g': 'lq',
      'unknown': 'mq',
    };
 
    const quality = qualityMap[this.connectionType] || 'mq';
    return urls[quality] || urls.mq || urls.lq;
  }
 
  // 获取推荐的 preload 策略
  getPreloadStrategy() {
    if (this.connectionType === 'slow-2g' || this.connectionType === '2g') {
      return 'none';     // 弱网不预加载
    } else if (this.connectionType === '3g') {
      return 'metadata'; // 中等网络只加载元数据
    }
    return 'auto';       // 好网络可以预加载
  }
 
  switchToLowQuality() {
    console.log('网络变差，切换到低码率音频');
    // 触发 HLS/DASH 的 ABR 逻辑，或直接切换 src
  }
 
  switchToHighQuality() {
    console.log('网络变好，可以切换到高码率音频');
  }
}
 
// 使用
const networkAdapter = new AdaptiveAudioLoader();
 
const audioUrl = networkAdapter.getBestAudioUrl({
  hq: 'music-256k.aac',
  mq: 'music-128k.aac',
  lq: 'music-64k.aac',
});
 
audio.preload = networkAdapter.getPreloadStrategy();
audio.src     = audio
}

audio.preload = networkAdapter.getPreloadStrategy();
audio.src     = audioUrl;

class BufferHealthMonitor {
  constructor(audioEl) {
    this.audio        = audioEl;
    this.stallCount   = 0;     // 卡顿次数
    this.stallStart   = 0;     // 卡顿开始时间
    this.totalStall   = 0;     // 累计卡顿时长（ms）
    this._setup();
  }
 
  _setup() {
    // 监听卡顿开始
    this.audio.addEventListener('waiting', () => {
      this.stallStart = Date.now();
      this.stallCount++;
      console.warn(`卡顿 #，缓冲量: s`);
      this._onStall();
    });
 
    // 监听卡顿结束
    this.audio.addEventListener('playing', () => {
      if (this.stallStart > 0) {
        this.totalStall += Date.now() - this.stallStart;
        this.stallStart = 0;
      }
    });
  }
 
  // 获取当前缓冲健康度（0~1）
  getBufferHealth() {
    const buffered = this.audio.buffered;
    if (!buffered.length || !this.audio.duration) return 0;
 
    const currentTime = this.audio.currentTime;
    for (let i = 0; i < buffered.length; i++) {
      if (buffered.start(i) <= currentTime && currentTime <= buffered.end(i)) {
        const aheadSeconds = buffered.end(i) - currentTime;
        // 缓冲超过 10 秒认为健康
        return Math.min(1, aheadSeconds / 10);
      }
    }
    return 0;
  }
 
  _onStall() {
    const health = this.getBufferHealth();
 
    if (this.stallCount >= 3 && health < 0.2) {
      // 频繁卡顿且缓冲很少，建议降质
      console.warn('频繁卡顿，建议切换到低码率版本');
      this.audio.dispatchEvent(new CustomEvent('qualitydowngrade'));
    }
  }
 
  getReport() {
    return {
      stallCount:    this.stallCount,
      totalStallMs:  this.totalStall,
      bufferHealth:  this.getBufferHealth(),
    };
  }
}

class AudioCapabilityDetector {
  constructor() {
    this.results = {};
    this._detect();
  }
 
  _detect() {
    const audio = new Audio();
 
    this.results = {
      // 基础播放
      htmlAudio:          typeof Audio !== 'undefined',
 
      // Web Audio API
      webAudioAPI:        !!(window.AudioContext || window.webkitAudioContext),
      audioWorklet:       !!(window.AudioContext?.prototype?.audioWorklet),
      offlineAudio:       !!(window.OfflineAudioContext || window.webkitOfflineAudioContext),
 
      // 媒体相关
      mediaRecorder:      typeof MediaRecorder !== 'undefined',
      getUserMedia:       !!(navigator.mediaDevices?.getUserMedia),
      mediaSession:       'mediaSession' in navigator,
      mediaSource:        typeof MediaSource !== 'undefined',
 
      // 格式支持
      formats: {
        mp3:      audio.canPlayType('audio/mpeg')              !== '',
        aac:      audio.canPlayType('audio/aac')               !== '',
        ogg:      audio.canPlayType('audio/ogg; codecs=vorbis') !== '',
        opus:     audio.canPlayType('audio/ogg; codecs=opus')  !== '',
        webmOpus: audio.canPlayType('audio/webm; codecs=opus') !== '',
        flac:     audio.canPlayType('audio/flac')              !== '',
        wav:      audio.canPlayType('audio/wav')               !== '',
      },
 
      // 平台检测
      platform: {
        isIOS:         /iPad|iPhone|iPod/.test(navigator.userAgent),
        isAndroid:     /Android/.test(navigator.userAgent),
        isSafari:      /^((?!chrome|android).)*safari/i.test(navigator.userAgent),
        isWebView:     /wv/.test(navigator.userAgent),
        isMobile:      /Mobi|Android/i.test(navigator.userAgent),
      },
 
      // 性能相关
      performance: {
        cores:   navigator.hardwareConcurrency || 2,
        memory:  navigator.deviceMemory        || 2,
        // 估算性能等级
        tier:    this._getPerformanceTier(),
      },
    };
  }
 
  _getPerformanceTier() {
    const cores  = navigator.hardwareConcurrency || 2;
    const memory = navigator.deviceMemory        || 2;
    if (cores >= 8 && memory >= 8)  return 'high';
    if (cores >= 4 && memory >= 4)  return 'medium';
    return 'low';
  }
 
  // 根据能力生成推荐配置
  getRecommendedConfig() {
    const { platform, performance, formats } = this.results;
 
    return {
      // 推荐的音频格式
      preferredFormat: (() => {
        if (platform.isIOS)         return formats.aac  ? 'aac'  : 'mp3';
        if (formats.webmOpus)       return 'webmOpus';
        if (formats.opus)           return 'opus';
        if (formats.ogg)            return 'ogg';
        return 'mp3';
      })(),
 
      // 是否使用 Web Audio API
      useWebAudio: this.results.webAudioAPI && performance.tier !== 'low',
 
      // 可视化复杂度
      vizComplexity: performance.tier, // 'high' | 'medium' | 'low'
 
      // FFT 大小
      fftSize: { high: 2048, medium: 1024, low: 512 }[performance.tier],
 
      // 是否启用音效处理
      enableEffects: performance.tier !== 'low',
 
      // preload 策略
      preload: platform.isMobile ? 'metadata' : 'auto',
 
      // iOS 专项
      requiresUserGesture: platform.isIOS || platform.isSafari,
    };
  }
 
  // 打印完整报告
  report() {
    console.group('音频能力检测报告');
    console.log('平台:', this.results.platform);
    console.log('格式支持:', this.results.formats);
    console.log('API 支持:', {
      webAudio:      this.results.webAudioAPI,
      audioWorklet:  this.results.audioWorklet,
      mediaRecorder: this.results.mediaRecorder,
      getUserMedia:  this.results.getUserMedia,
      mediaSession:  this.results.mediaSession,
    });
    console.log('性能等级:', this.results.performance.tier);
    console.log('推荐配置:', this.getRecommendedConfig());
    console.groupEnd();
  }
}
 
// 全局单例
const capabilities = new AudioCapabilityDetector();
capabilities.report();
const config = capabilities.getRecommendedConfig();

class CrossPlatformAudioPlayer {
  constructor(container) {
    this.container   = container;
    this.capabilities = new AudioCapabilityDetector();
    this.config      = this.capabilities.getRecommendedConfig();
    this.resources   = new AudioResourceManager();
    this.network     = new AdaptiveAudioLoader();
 
    this.audio       = new Audio();
    this.audioCtx    = null;
    this.iosUnlocker = null;
 
    this._applyBaseConfig();
    this._setupWebAudio();
    this._setupMediaSession();
    this._setupEventHandlers();
  }
 
  _applyBaseConfig() {
    // 根据平台配置 audio 元素
    this.audio.preload     = this.config.preload;
    this.audio.crossOrigin = 'anonymous';
 
    // iOS：不使用 autoplay，等待用户手势
    if (this.config.requiresUserGesture) {
      this.audio.autoplay = false;
    }
  }
 
  _setupWebAudio() {
    if (!this.config.useWebAudio) {
      console.log('低端设备，跳过 Web Audio API 初始化');
      return;
    }
 
    const AudioCtx = window.AudioContext || window.webkitAudioContext;
    this.audioCtx  = new AudioCtx({
      latencyHint: 'playback',
      sampleRate:  44100,
    });
    this.resources.trackContext(this.audioCtx);
 
    // iOS 解锁
    if (this.config.requiresUserGesture) {
      this.iosUnlocker = new IOSAudioUnlocker();
      this.iosUnlocker.setup(this.audioCtx);
    }
 
    // 连接 audio 元素到 Web Audio（仅高中端设备）
    if (this.config.vizComplexity !== 'low') {
      this.mediaSource = this.audioCtx.createMediaElementSource(this.audio);
      this.analyser    = this.audioCtx.createAnalyser();
      this.analyser.fftSize = this.config.fftSize;
      this.masterGain  = this.audioCtx.createGain();
 
      this.mediaSource
        .connect(this.analyser)
        .connect(this.masterGain)
        .connect(this.audioCtx.destination);
    }
  }
 
  _setupMediaSession() {
    if (!this.capabilities.results.mediaSession) return;
    this.session = new MediaSessionController(this.audio);
  }
 
  _setupEventHandlers() {
    // 卡顿监控
    this.bufferMonitor = new BufferHealthMonitor(this.audio);
 
    // 质量降级事件
    this.audio.addEventListener('qualitydowngrade', () => {
      if (this._currentUrls?.lq) {
        console.log('自动降级到低码率');
        this._loadUrl(this._currentUrls.lq);
      }
    });
 
    // AudioContext 状态恢复
    if (this.audioCtx) {
      this.audioCtx.addEventListener('statechange', () => {
        if (this.audioCtx.state === 'suspended' && !document.hidden) {
          // 非后台状态下的意外挂起（如 iOS 中断）
          this._showResumePrompt();
        }
      });
    }
  }
 
  // 加载音频（自动选择最优格式和码率）
  async load(trackInfo) {
    // trackInfo: { title, artist, artwork, urls: { hq, mq, lq } }
    this._currentUrls = trackInfo.urls;
 
    // 根据网络选择码率
    const url = this.network.getBestAudioUrl(trackInfo.urls);
 
    await this._loadUrl(url);
 
    // 更新 Media Session 元数据
    this.session?.updateMetadata({
      title:   trackInfo.title,
      artist:  trackInfo.artist,
      artwork: trackInfo.artwork || [],
    });
  }
 
  async _loadUrl(url) {
    const currentTime = this.audio.currentTime;
    const wasPlaying  = !this.audio.paused;
 
    this.audio.src = url;
    this.audio.load();
 
    // 恢复播放位置
    if (currentTime > 0) {
      await new Promise(resolve => {
        this.audio.addEventListener('loadedmetadata', resolve, { once: true });
      });
      this.audio.currentTime = currentTime;
    }
 
    if (wasPlaying) await this.play();
  }
 
  // 安全播放（处理所有平台差异）
  async play() {
    // iOS：确保 AudioContext 已解锁
    if (this.iosUnlocker && !this.iosUnlocker.unlocked) {
      return new Promise(resolve => {
        this.iosUnlocker.whenUnlocked(async () => {
          await this._doPlay();
          resolve();
        });
      });
    }
    return this._doPlay();
  }
 
  async _doPlay() {
    // 恢复 AudioContext
    if (this.audioCtx?.state === 'suspended') {
      await this.audioCtx.resume();
    }
 
    try {
      await this.audio.play();
      this.session?.updatePlaybackState('playing');
    } catch (err) {
      if (err.name === 'NotAllowedError') {
        this._showPlayPrompt(); // 显示"点击播放"提示
      } else {
        console.error('播放失败:', err);
      }
    }
  }
 
  pause() {
    this.audio.pause();
    this.session?.updatePlaybackState('paused');
 
    // 暂停时挂起 AudioContext 节省电量
    if (this.audioCtx?.state === 'running') {
      this.audioCtx.suspend();
    }
  }
 
  setVolume(value) {
    // Web Audio 可用时通过 GainNode 控制，否则直接设置 audio.volume
    if (this.masterGain) {
      this.masterGain.gain.setTargetAtTime(
        Math.max(0, Math.min(2, value)),
        this.audioCtx.currentTime,
        0.02
      );
    } else {
      this.audio.volume = Math.max(0, Math.min(1, value));
    }
  }
 
  _showPlayPrompt() {
    const prompt = document.createElement('div');
    prompt.className = 'play-prompt';
    prompt.textContent = '点击任意位置开始播放';
    this.container.appendChild(prompt);
 
    document.addEventListener('click', async () => {
      prompt.remove();
      await this.play();
    }, { once: true });
  }
 
  _showResumePrompt() {
    console.log('音频被系统中断，等待用户恢复');
    // 显示恢复提示 UI
  }
 
  destroy() {
    this.audio.pause();
    this.audio.src = '';
    this.bufferMonitor = null;
    this.resources.releaseAll();
  }
}