第三章：音频事件系统 —— 掌握媒体播放的每一个生命周期节点

// 错误示范：轮询检测，浪费性能且不可靠
setInterval(() => {
  if (audio.readyState === 4) {
    doSomething();
  }
}, 100);

// 正确示范：事件驱动，精准响应
audio.addEventListener('canplaythrough', () => {
  doSomething();
}, { once: true });

audio.addEventListener('loadstart', () => {
  console.log('开始加载资源...');
  showLoadingUI();
});

audio.addEventListener('durationchange', () => {
  if (isFinite(audio.duration)) {
    durationDisplay.textContent = formatTime(audio.duration);
  }
});

audio.addEventListener('loadedmetadata', () => {
  console.log(`总时长: s`);
  console.log(`可 seek 范围: ~`);
  initProgressBar(audio.duration);
});

audio.addEventListener('loadeddata', () => {
  console.log('当前帧数据已就绪');
  hideInitialPlaceholder();
});

audio.addEventListener('progress', () => {
  const buffered = audio.buffered;
  if (buffered.length > 0) {
    const bufferedEnd = buffered.end(buffered.length - 1);
    const percent = (bufferedEnd / audio.duration) * 100;
    bufferBar.style.width = `%`;
  }
});

audio.addEventListener('canplay', () => {
  playButton.disabled = false; // 解锁播放按钮
});

audio.addEventListener('canplaythrough', () => {
  console.log('缓冲充足，可以流畅播放');
  if (shouldAutoPlay) {
    audio.play();
  }
}, { once: true });

audio.addEventListener('play', () => {
  play# 第三章：音频事件系统 —— 掌握媒体播放的每一个生命周期节点
 
> 前两章我们搞清楚了 `<audio>` 的结构和 `HTMLMediaElement` 的属性方法。但一个真正健壮的播放器，靠的不是"主动查询状态"，而是**被动监听事件**——让浏览器在正确的时机告诉你发生了什么。这一章，我们把 `HTMLMediaElement` 的完整事件系统彻底梳理清楚。
 
---
 
## **一、为什么事件系统如此重要？**
 
音频加载和播放是一个**异步过程**。你设置了 `src`，但数据不会瞬间到位；你调用了 `play()`，但声音不会立刻响起。整个过程涉及网络请求、解码、缓冲、渲染管线……每一个阶段都有对应的事件通知你。
 
如果你不理解事件的触发顺序，就会写出这样的代码：
 
```javascript
audio.src = 'music.mp3';
console.log(audio.duration); // NaN —— 元数据还没加载！
audio.currentTime = 30;      // 无效 —— 还不知道总时长！

audio.addEventListener('loadstart', () => {
  console.log('开始加载，networkState:', audio.networkState); // 2
  showLoadingUI();
});

audio.addEventListener('durationchange', () => {
  if (isFinite(audio.duration)) {
    totalTimeEl.textContent = formatTime(audio.duration);
  } else {
    totalTimeEl.textContent = 'LIVE'; // 直播流
  }
});

audio.addEventListener('loadedmetadata', () => {
  console.log('总时长:', audio.duration);
  console.log('可 seek 范围:', audio.seekable.end(0));
 
  // 安全地执行需要时长的初始化操作
  initProgressBar(audio.duration);
 
  // 如果有"记住上次播放位置"的需求，在这里恢复
  const savedTime = localStorage.getItem('lastPosition');
  if (savedTime) audio.currentTime = parseFloat(savedTime);
});

audio.addEventListener('progress', () => {
  if (audio.buffered.length > 0 && audio.duration) {
    const bufferedEnd = audio.buffered.end(audio.buffered.length - 1);
    const bufferedPercent = (bufferedEnd / audio.duration) * 100;
    bufferBar.style.width = `%`;
  }
});

audio.addEventListener('canplay', () => {
  hideLoadingSpinner();
  playBtn.disabled = false;
});

audio.addEventListener('canplaythrough', () => {
  console.log('数据充足，可以流畅播放');
  // 如果设置了 autoplay，此时是触发自动播放的好时机
  if (shouldAutoPlay) audio.play();
});

audio.addEventListener('play', () => {
  // 更新 UI 为"播放中"状态
  playBtn.textContent = '⏸';
  playBtn.setAttribute('aria-label', '暂停');
});

audio.addEventListener('playing', () => {
  hideBufferingIndicator(); // 缓冲结束，隐藏 loading 圈
});

audio.addEventListener('pause', () => {
  playBtn.textContent = '▶';
  // 保存播放位置
  localStorage.setItem('lastPosition', audio.currentTime);
});

audio.addEventListener('ended', () => {
  playBtn.textContent = '▶';
  audio.currentTime = 0;
 
  // 自动播放下一首
  playNextSong();
});

audio.addEventListener('timeupdate', () => {
  const percent = (audio.currentTime / audio.duration) * 100;
  progressFill.style.width = `%`;
  currentTimeEl.textContent = formatTime(audio.currentTime);
});

let rafId = null;
 
audio.addEventListener('timeupdate', () => {
  if (rafId) return; // 上一帧还没渲染完，跳过
  rafId = requestAnimationFrame(() => {
    updateProgressBar();
    rafId = null;
  });
});

audio.addEventListener('ratechange', () => {
  rateDisplay.textContent = `x`;
});

audio.addEventListener('volumechange', () => {
  if (audio.muted || audio.volume === 0) {
    volumeIcon.textContent = '🔇';
  } else if (audio.volume < 0.5) {
    volumeIcon.textContent = '🔉';
  } else {
    volumeIcon.textContent = '🔊';
  }
  volumeSlider.value = audio.muted ? 0 : audio.volume;
});

audio.addEventListener('loadstart', () => {
  showSkeleton(); // 显示骨架屏或 loading
  console.log('开始加载，networkState:', audio.networkState);
});

audio.addEventListener('durationchange', () => {
  if (isFinite(audio.duration)) {
    durationEl.textContent = formatTime(audio.duration);
  } else if (audio.duration === Infinity) {
    durationEl.textContent = '直播'; // 直播流
  }
});

audio.addEventListener('loadedmetadata', () => {
  // 此时 duration 已经可靠
  initProgressBar(audio.duration);
  // 如果需要从特定位置开始播放
  if (startTime) audio.currentTime = startTime;
});

audio.addEventListener('loadeddata', () => {
  console.log('当前帧数据就绪，readyState:', audio.readyState); // 2
});

audio.addEventListener('progress', () => {
  updateBufferBar(audio.buffered, audio.duration);
});

audio.addEventListener('canplay', () => {
  playBtn.disabled = false; // 解锁播放按钮
  hideLoading();
});

audio.addEventListener('canplaythrough', () => {
  console.log('数据充足，可流畅播放到结尾');
  // 如果设置了 autoplay 且用户已交互，可在此触发播放
});

audio.addEventListener('play', () => {
  playBtn.textContent = '⏸';
  playBtn.setAttribute('aria-label', '暂停');
});

audio.addEventListener('playing', () => {
  hideBufferingSpinner(); // 隐藏缓冲中的 loading
  console.log('音频正在输出');
});

audio.addEventListener('pause', () => {
  playBtn.textContent = '▶';
  playBtn.setAttribute('aria-label', '播放');
});

audio.addEventListener('ended', () => {
  if (playlist.hasNext()) {
    playNext();
  } else {
    resetPlayer();
  }
});

audio.addEventListener('timeupdate', () => {
  const progress = audio.currentTime / audio.duration;
  progressFill.style.width = `%`;
  currentTimeEl.textContent = formatTime(audio.currentTime);
});

audio.addEventListener('ratechange', () => {
  rateDisplay.textContent = `x`;
});

audio.addEventListener('volumechange', () => {
  if (audio.muted || audio.volume === 0) {
    volumeIcon.textContent = '🔇';
  } else if (audio.volume < 0.5) {
    volumeIcon.textContent = '🔉';
  } else {
    volumeIcon.textContent = '🔊';
  }
});

audio.addEventListener('waiting', () => {
  showBufferingSpinner();
  console.log('数据不足，等待缓冲...');
});

audio.addEventListener('stalled', () => {
  console.warn('数据获取停滞，可能是网络问题');
  showNetworkWarning();
});

audio.addEventListener('suspend', () => {
  console.log('浏览器暂停加载，已缓冲足够数据');
});

audio.addEventListener('abort', () => {
  console.log('加载被中止');
});

audio.addEventListener('emptied', () => {
  resetUI(); // 重置播放器 UI
  console.log('媒体元素已清空，networkState:', audio.networkState); // 0
});

audio.addEventListener('seeking', () => {
  showSeekingIndicator();
});

audio.addEventListener('seeked', () => {
  hideSeekingIndicator();
  console.log('已跳转到:', audio.currentTime);
});

audio.addEventListener('error', (event) => {
  const err = audio.error;
  const messages = {
    1: '用户中止了加载',
    2: '网络错误，请检查网络连接',
    3: '音频解码失败，文件可能已损坏',
    4: '不支持的音频格式或无效的 src',
  };
  const msg = messages[err?.code] || '未知错误';
  showErrorMessage(msg);
  console.error('MediaError:', err?.code, err?.message);
});

class PlayerStateMachine {
  constructor(audioEl) {
    this.audio = audioEl;
    // 定义所有可能的状态
    this.states = {
      IDLE: 'idle',           // 空闲，未加载
      LOADING: 'loading',     // 加载中
      READY: 'ready',         // 就绪，可播放
      PLAYING: 'playing',     // 播放中
      PAUSED: 'paused',       // 已暂停
      BUFFERING: 'buffering', // 缓冲中
      ENDED: 'ended',         // 播放结束
      ERROR: 'error',         // 错误
    };
    this.current = this.states.IDLE;
    this._bindEvents();
  }
 
  _transition(newState) {
    const prev = this.current;
    this.current = newState;
    console.log(`状态变更: [${prev}] → [${newState}]`);
    this._onStateChange(newState, prev);
  }
 
  _bindEvents() {
    const a = this.audio;
 
    a.addEventListener('loadstart',      () => this._transition(this.states.LOADING));
    a.addEventListener('canplay',        () => this._transition(this.states.READY));
    a.addEventListener('play',           () => this._transition(this.states.LOADING)); // 可能还在缓冲
    a.addEventListener('playing',        () => this._transition(this.states.PLAYING));
    a.addEventListener('pause',          () => {
      // 区分主动暂停和缓冲暂停
      if (!this.audio.ended) {
        this._transition(this.states.PAUSED);
      }
    });
    a.addEventListener('waiting',        () => this._transition(this.states.BUFFERING));
    a.addEventListener('ended',          () => this._transition(this.states.ENDED));
    a.addEventListener('error',          () => this._transition(this.states.ERROR));
    a.addEventListener('emptied',        () => this._transition(this.states.IDLE));
  }
 
  _onStateChange(state, prev) {
    const ui = {
      [this.states.IDLE]:      () => resetUI(),
      [this.states.LOADING]:   () => showLoading(),
      [this.states.READY]:     () => { hideLoading(); enablePlayBtn(); },
      [this.states.PLAYING]:   () => { hideLoading(); setPlayIcon('pause'); },
      [this.states.PAUSED]:    () => setPlayIcon('play'),
      [this.states.BUFFERING]: () => showBufferingSpinner(),
      [this.states.ENDED]:     () => { setPlayIcon('replay'); onEnded(); },
      [this.states.ERROR]:     () => showError(this.audio.error),
    };
    ui[state]?.();
  }
 
  get isPlaying() { return this.current === this.states.PLAYING; }
  get isBuffering() { return this.current === this.states.BUFFERING; }
  get hasError() { return this.current === this.states.ERROR; }
}
 
// 使用
const audio = document.getElementById('myAudio');
const player = new PlayerStateMachine(audio);

let lastUpdate = 0;
audio.addEventListener('timeupdate', () => {
  const now = Date.now();
  if (now - lastUpdate < 100) return; // 最多每 100ms 更新一次
  lastUpdate = now;
  updateProgressBar();
});

function renderLoop() {
  if (!audio.paused) {
    drawWaveform(); // 每帧绘制波形
    requestAnimationFrame(renderLoop);
  }
}
 
audio.addEventListener('playing', () => requestAnimationFrame(renderLoop));

audio.addEventListener('loadedmetadata', () => {
  initUI(audio.duration);
}, { once: true }); // 触发一次后自动移除

class AudioPlayer {
  constructor(el) {
    this.audio = el;
    this._handlers = {};
    this._on('timeupdate', this._onTimeUpdate.bind(this));
    this._on('ended', this._onEnded.bind(this));
  }
 
  _on(event, handler) {
    this._handlers[event] = handler;
    this.audio.addEventListener(event, handler);
  }
 
  destroy() {
    Object.entries(this._handlers).forEach(([event, handler]) => {
      this.audio.removeEventListener(event, handler);
    });
    this._handlers = {};
  }
}