Media Source Extensions（MSE）：彻底掌握 Web 流媒体的底层引擎

const mediaSource = new MediaSource();
 
// 1. 添加 SourceBuffer（只能在 readyState === 'open' 时调用）
const videoBuffer = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.64002A"');
const audioBuffer = mediaSource.addSourceBuffer('audio/mp4; codecs="mp4a.40.2"');
 
// 2. 移除 SourceBuffer（移除前必须先 abort()）
videoBuffer.abort();
mediaSource.removeSourceBuffer(videoBuffer);
 
// 3. 通知流结束（点播视频全部追加完毕后调用）
mediaSource.endOfStream();
 
// 4. 通知流结束并报错（触发 video 的 error 事件）
mediaSource.endOfStream('network');  // 或 'decode'
 
// 5. 设置直播的可跳转范围（直播场景）
mediaSource.setLiveSeekableRange(0, 300); // 允许在 0~300s 范围内跳转
mediaSource.clearLiveSeekableRange();
 
// 6. 静态方法：检测格式支持
MediaSource.isTypeSupported('video/mp4; codecs="avc1.64002A"'); // true/false

// sourceopen：readyState 变为 open 时触发（最重要的事件）
// 必须在这里创建 SourceBuffer，不能在外面
mediaSource.addEventListener('sourceopen', () => {
  console.log('MediaSource 已激活，readyState:', mediaSource.readyState); // 'open'
  // 在这里 addSourceBuffer
}, { once: true }); // 注意：如果不用 once，需要处理重复触发
 
// sourceended：readyState 变为 ended 时触发
mediaSource.addEventListener('sourceended', () => {
  console.log('流已结束');
});
 
// sourceclose：readyState 变为 closed 时触发
mediaSource.addEventListener('sourceclose', () => {
  console.log('MediaSource 已关闭，通常是 video 被销毁');
});

// 错误写法：不检查 updating 就追加
sourceBuffer.appendBuffer(chunk1);
sourceBuffer.appendBuffer(chunk2); // 💥 InvalidStateError！上一个还没完成
 
// 正确写法：等待 updateend 再追加
sourceBuffer.appendBuffer(chunk1);
sourceBuffer.addEventListener('updateend', () => {
  sourceBuffer.appendBuffer(chunk2);
}, { once: true });

// 直播场景：使用 sequence 模式
const sourceBuffer = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.64002A"');
sourceBuffer.mode = 'sequence'; // 必须在第一次 appendBuffer 之前设置

sourceBuffer.addEventListener('updatestart', () => {
  // appendBuffer() 或 remove() 开始执行
  // updating 从 false → true
});
 
sourceBuffer.addEventListener('update', () => {
  // 操作成功完成
  // updating 从 true → false
});
 
sourceBuffer.addEventListener('updateend', () => {
  // 操作结束（无论成功还是被 abort）
  // 在 update 事件之后触发
  // ✅ 这是判断"可以追加下一个分片"的正确时机
});
 
sourceBuffer.addEventListener('error', () => {
  // appendBuffer() 执行时发生错误
  // 通常是数据格式不正确
  console.error('SourceBuffer 错误，可能是数据格式问题');
});
 
sourceBuffer.addEventListener('abort', () => {
  // appendBuffer() 或 remove() 被 abort() 中断
});

class SourceBufferQueue {
  constructor(sourceBuffer) {
    this.sb = sourceBuffer;
    this.queue = [];
    this.isProcessing = false;
 
    // 每次操作完成后自动处理队列
    this.sb.addEventListener('updateend', () => {
      this.isProcessing = false;
      this._processNext();
    });
 
    this.sb.addEventListener('error', (e) => {
      console.error('SourceBuffer error:', e);
      this.isProcessing = false;
      // 可以选择清空队列或重试
    });
  }
 
  // 公共接口：追加数据（自动排队）
  append(arrayBuffer) {
    return new Promise((resolve, reject) => {
      this.queue.push({ type: 'append', data: arrayBuffer, resolve, reject });
      this._processNext();
    });
  }
 
  // 公共接口：移除数据（自动排队）
  remove(start, end) {
    return new Promise((resolve, reject) => {
      this.queue.push({ type: 'remove', start, end, resolve, reject });
      this._processNext();
    });
  }
 
  _processNext() {
    // 如果正在处理或队列为空，直接返回
    if (this.isProcessing || this.queue.length === 0) return;
    // 如果 SourceBuffer 正在更新（外部操作），等待
    if (this.sb.updating) return;
 
    const task = this.queue.shift();
    this.isProcessing = true;
 
    try {
      if (task.type === 'append') {
        this.sb.appendBuffer(task.data);
      } else if (task.type === 'remove') {
        this.sb.remove(task.start, task.end);
      }
 
      // 在 updateend 时 resolve
      this.sb.addEventListener('updateend', () => task.resolve(), { once: true });
      this.sb.addEventListener('error', () => task.reject(new Error('SourceBuffer error')), { once: true });
    } catch (e) {
      this.isProcessing = false;
      task.reject(e);
 
      if (e.name === 'QuotaExceededError') {
        // 缓冲区满，需要先清理再重试
        this.queue.unshift(task);
        this._evictAndRetry();
      }
    }
  }
 
  _evictAndRetry() {
    // 异步清理后重试
    setTimeout(() => this._processNext(), 50);
  }
}

function evictBuffer(sourceBuffer, video, keepBehind = 30, keepAhead = 60) {
  const currentTime = video.currentTime;
  const buffered = sourceBuffer.buffered;
 
  if (buffered.length === 0) return Promise.resolve();
 
  const bufferStart = buffered.start(0);
  const bufferEnd = buffered.end(buffered.length - 1);
 
  // 计算需要清理的范围
  const evictStart = bufferStart;
  const evictEnd = Math.max(bufferStart, currentTime - keepBehind);
 
  if (evictEnd <= evictStart) return Promise.resolve();
 
  console.log(`清理缓冲区: ${evictStart.toFixed(1)}s ~ ${evictEnd.toFixed(1)}s`);
 
  return new Promise((resolve) => {
    sourceBuffer.remove(evictStart, evictEnd);
    sourceBuffer.addEventListener('updateend', resolve, { once: true });
  });
}
 
// 在 appendBuffer 抛出 QuotaExceededError 时调用
async function safeAppend(queue, sourceBuffer, video, data) {
  try {
    await queue.append(data);
  } catch (e) {
    if (e.name === 'QuotaExceededError') {
      await evictBuffer(sourceBuffer, video);
      await queue.append(data); // 清理后重试
    } else {
      throw e;
    }
  }
}

// 点播：尽量多缓冲，只清理当前位置 60s 之前的数据
const keepBehind = 60;  // 保留已播放 60s 的数据（支持快速回退）
const keepAhead = 120;  // 预加载未来 120s 的数据

// 直播：只保留少量历史，重点保证未来数据
const keepBehind = 10;  // 只保留 10s 历史（直播不需要回退太多）
const keepAhead = 30;   // 预加载 30s 未来数据

// AI 视频：生成多少追加多少，适当清理历史
const keepBehind = 20;
const keepAhead = Infinity; // 全部追加，不限制预加载

// 解决：用 timestampOffset 将时间戳归零
// 假设第一个分片的时间戳是 1712000000
const firstSegmentTimestamp = 1712000000;
sourceBuffer.timestampOffset = -firstSegmentTimestamp;
// 之后追加的数据时间戳会被自动减去这个偏移量

// 解决：切换码率时，将 timestampOffset 设置为当前播放位置
// 确保新分片的时间戳从当前播放点开始
sourceBuffer.timestampOffset = video.currentTime;

mediaSource.addEventListener('sourceopen', async () => {
  // 分别创建音频和视频 SourceBuffer
  const videoSB = mediaSource.addSourceBuffer('video/mp4; codecs="avc1.64002A"');
  const audioSB = mediaSource.addSourceBuffer('audio/mp4; codecs="mp4a.40.2"');
 
  const videoQueue = new SourceBufferQueue(videoSB);
  const audioQueue = new SourceBufferQueue(audioSB);
 
  // 分别追加初始化片段
  const [videoInit, audioInit] = await Promise.all([
    fetch('video_init.mp4').then(r => r.arrayBuffer()),
    fetch('audio_init.mp4').then(r => r.arrayBuffer()),
  ]);
 
  await Promise.all([
    videoQueue.append(videoInit),
    audioQueue.append(audioInit),
  ]);
 
  // 并行追加媒体分片（浏览器负责音视频同步）
  for (let i = 1; i <= totalSegments; i++) {
    const [videoSeg, audioSeg] = await Promise.all([
      fetch(`video_seg.m4s`).then(r => r.arrayBuffer()),
      fetch(`audio_seg.m4s`).then(r => r.arrayBuffer()),
    ]);
 
    await Promise.all([
      videoQueue.append(videoSeg),
      audioQueue.append(audioSeg),
    ]);
  }
 
  mediaSource.endOfStream();
});

async function handleSeek(video, videoQueue, videoSB, targetTime) {
  // 1. 暂停播放
  video.pause();
 
  // 2. 等待 SourceBuffer 空闲
  if (videoSB.updating) {
    await new Promise(resolve =>
      videoSB.addEventListener('updateend', resolve, { once: true })
    );
  }
 
  // 3. 中止当前操作
  videoSB.abort();
 
  // 4. 清空整个缓冲区（或只清空目标位置前后的数据）
  if (videoSB.buffered.length > 0) {
    const start = videoSB.buffered.start(0);
    const end = videoSB.buffered.end(videoSB.buffered.length - 1);
    await videoQueue.remove(start, end);
  }
 
  // 5. 找到目标时间最近的关键帧（IDR 帧）位置
  // 必须从关键帧开始解码，否则画面会花屏
  const keyframeTime = findNearestKeyframe(targetTime);
 
  // 6. 重新下载并追加目标位置的分片
  const segmentIndex = Math.floor(keyframeTime / SEGMENT_DURATION);
  const segData = await fetch(`seg.m4s`).then(r => r.arrayBuffer());
  await videoQueue.append(segData);
 
  // 7. 设置播放位置并恢复播放
  video.currentTime = targetTime;
  video.play();
}
 
// 监听 seeking 事件触发跳转处理
video.addEventListener('seeking', () => {
  // 检查目标时间是否已在缓冲区内
  const isBuffered = isTimeBuffered(videoSB, video.currentTime);
  if (!isBuffered) {
    handleSeek(video, videoQueue, videoSB, video.currentTime);
  }
});
 
function isTimeBuffered(sourceBuffer, time) {
  const buffered = sourceBuffer.buffered;
  for (let i = 0; i < buffered.length; i++) {
    if (buffered.start(i) <= time && time <= buffered.end(i)) {
      return true;
    }
  }
  return false;
}

// 代码层面的调试辅助
function debugMSE(mediaSource, sourceBuffer, video) {
  const log = (msg) => console.log(`[MSE Debug] ${new Date().toISOString()} ${msg}`);
 
  mediaSource.addEventListener('sourceopen',  () => log('sourceopen'));
  mediaSource.addEventListener('sourceended', () => log('sourceended'));
  mediaSource.addEventListener('sourceclose', () => log('sourceclose'));
 
  sourceBuffer.addEventListener('updatestart', () => log(`updatestart, buffered: ${getBufferedStr(sourceBuffer)}`));
  sourceBuffer.addEventListener('updateend',   () => log(`updateend,   buffered: ${getBufferedStr(sourceBuffer)}`));
  sourceBuffer.addEventListener('error',       () => log('SourceBuffer ERROR'));
 
  video.addEventListener('waiting',  () => log(`video waiting, currentTime: ${video.currentTime.toFixed(2)}`));
  video.addEventListener('stalled',  () => log('video stalled'));
  video.addEventListener('error',    () => log(`video error: ${video.error?.message}`));
}
 
function getBufferedStr(sb) {
  if (!sb.buffered.length) return '[]';
  const ranges = [];
  for (let i = 0; i < sb.buffered.length; i++) {
    ranges.push(`${sb.buffered.start(i).toFixed(2)}~${sb.buffered.end(i).toFixed(2)}`);
  }
  return `[${ranges.join(', ')}]`;
}

class MSEPlayer {
  constructor(videoEl) {
    this.video = videoEl;
    this.mediaSource = new MediaSource();
    this.videoSB = null;
    this.audioSB = null;
    this.videoQueue = [];
    this.audioQueue = [];
    this.isVideoUpdating = false;
    this.isAudioUpdating = false;
    this.totalDuration = 0;
 
    // 绑定 MediaSource 到 video
    this.video.src = URL.createObjectURL(this.mediaSource);
 
    this.mediaSource.addEventListener('sourceopen', () => {
      // sourceopen 后立即释放 blob URL，避免内存泄漏
      URL.revokeObjectURL(this.video.src);
      this._onSourceOpen();
    }, { once: true });
 
    // 监听 video 跳转事件
    this.video.addEventListener('seeking', () => this._onSeeking());
  }
 
  _onSourceOpen() {
    // 创建独立的音视频 SourceBuffer
    this.videoSB = this.mediaSource.addSourceBuffer(
      'video/mp4; codecs="avc1.64002A"'
    );
    this.audioSB = this.mediaSource.addSourceBuffer(
      'audio/mp4; codecs="mp4a.40.2"'
    );
 
    // 绑定 updateend 事件驱动队列
    this.videoSB.addEventListener('updateend', () => {
      this.isVideoUpdating = false;
      this._processVideoQueue();
    });
    this.audioSB.addEventListener('updateend', () => {
      this.isAudioUpdating = false;
      this._processAudioQueue();
    });
 
    // 错误处理
    this.videoSB.addEventListener('error', (e) => {
      console.error('[MSEPlayer] videoSB error:', e);
    });
    this.audioSB.addEventListener('error', (e) => {
      console.error('[MSEPlayer] audioSB error:', e);
    });
  }
 
  // ── 公共接口 ──────────────────────────────────────
 
  appendVideoChunk(arrayBuffer) {
    this.videoQueue.push(arrayBuffer);
    this._processVideoQueue();
  }
 
  appendAudioChunk(arrayBuffer) {
    this.audioQueue.push(arrayBuffer);
    this._processAudioQueue();
  }
 
  setDuration(seconds) {
    if (this.mediaSource.readyState === 'open') {
      this.mediaSource.duration = seconds;
    }
    this.totalDuration = seconds;
  }
 
  finalize() {
    const tryEnd = () => {
      const videoIdle = !this.isVideoUpdating && this.videoQueue.length === 0;
      const audioIdle = !this.isAudioUpdating && this.audioQueue.length === 0;
      const sbIdle = !this.videoSB?.updating && !this.audioSB?.updating;
 
      if (videoIdle && audioIdle && sbIdle) {
        if (this.mediaSource.readyState === 'open') {
          this.mediaSource.endOfStream();
          console.log('[MSEPlayer] 流已结束');
        }
      } else {
        setTimeout(tryEnd, 100);
      }
    };
    tryEnd();
  }
 
  destroy() {
    try {
      if (this.videoSB?.updating) this.videoSB.abort();
      if (this.audioSB?.updating) this.audioSB.abort();
      if (this.mediaSource.readyState === 'open') {
        this.mediaSource.endOfStream();
      }
    } catch (e) {
      // 忽略销毁时的错误
    }
    this.video.src = '';
    this.videoQueue = [];
    this.audioQueue = [];
  }
 
  // ── 内部队列处理 ──────────────────────────────────
 
  _processVideoQueue() {
    if (this.isVideoUpdating) return;
    if (!this.videoSB || this.videoSB.updating) return;
    if (this.videoQueue.length === 0) return;
 
    const chunk = this.videoQueue.shift();
    this.isVideoUpdating = true;
 
    try {
      this.videoSB.appendBuffer(chunk);
    } catch (e) {
      this.isVideoUpdating = false;
      if (e.name === 'QuotaExceededError') {
        this.videoQueue.unshift(chunk); // 放回队列
        this._evict(this.videoSB).then(() => this._processVideoQueue());
      } else {
        console.error('[MSEPlayer] appendBuffer video error:', e.name, e.message);
      }
    }
  }
 
  _processAudioQueue() {
    if (this.isAudioUpdating) return;
    if (!this.audioSB || this.audioSB.updating) return;
    if (this.audioQueue.length === 0) return;
 
    const chunk = this.audioQueue.shift();
    this.isAudioUpdating = true;
 
    try {
      this.audioSB.appendBuffer(chunk);
    } catch (e) {
      this.isAudioUpdating = false;
      if (e.name === 'QuotaExceededError') {
        this.audioQueue.unshift(chunk);
        this._evict(this.audioSB).then(() => this._processAudioQueue());
      } else {
        console.error('[MSEPlayer] appendBuffer audio error:', e.name, e.message);
      }
    }
  }
 
  // ── 缓冲区清理 ────────────────────────────────────
 
  _evict(sourceBuffer, keepBehind = 30) {
    return new Promise((resolve) => {
      const currentTime = this.video.currentTime;
      const buffered = sourceBuffer.buffered;
      if (buffered.length === 0) return resolve();
 
      const evictEnd = Math.max(
        buffered.start(0),
        currentTime - keepBehind
      );
      if (evictEnd <= buffered.start(0)) return resolve();
 
      sourceBuffer.remove(buffered.start(0), evictEnd);
      sourceBuffer.addEventListener('updateend', resolve, { once: true });
    });
  }
 
  // ── Seek 处理 ─────────────────────────────────────
 
  _onSeeking() {
    const target = this.video.currentTime;
    if (this._isBuffered(this.videoSB, target)) return; // 已缓冲，无需处理
 
    // 触发外部的重新加载逻辑
    this.onSeekToUnbuffered?.(target);
  }
 
  _isBuffered(sb, time) {
    if (!sb) return false;
    const buffered = sb.buffered;
    for (let i = 0; i < buffered.length; i++) {
      if (buffered.start(i) <= time && time <= buffered.end(i) + 0.1) {
        return true;
      }
    }
    return false;
  }
}
 
// ── 使用示例 ──────────────────────────────────────────
 
const player = new MSEPlayer(document.querySelector('video'));
 
// 设置跳转到未缓冲区域时的回调
player.onSeekToUnbuffered = async (targetTime) => {
  console.log('用户跳转到未缓冲位置:', targetTime);
  // 在这里重新下载目标位置的分片
};
 
// 流式追加数据（AI 视频生成场景）
async function streamAIVideo(player) {
  // 先追加初始化片段
  const videoInit = await fetch('/init_video.mp4').then(r => r.arrayBuffer());
  const audioInit = await fetch('/init_audio.mp4').then(r => r.arrayBuffer());
  player.appendVideoChunk(videoInit);
  player.appendAudioChunk(audioInit);
 
  // 持续追加生成的媒体分片
  const response = await fetch('/ai-generate-stream');
  const reader = response.body.getReader();
 
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
 
    // 解析分片类型（实际项目中通过协议头或单独通道区分）
    if (isVideoSegment(value)) {
      player.appendVideoChunk(value.buffer);
    } else {
      player.appendAudioChunk(value.buffer);
    }
  }
 
  player.finalize();
}