WebRTC传输video元素captureStream()媒体流时远端黑屏问题

核心问题根因（按出现概率从高到低排序） #

• 轨道捕获时机过早
  调用captureStream()时如果video元素还未输出有效视频帧，返回的MediaStream里的视频轨道会处于muted（静音）状态——这类轨道的SDP协商可以正常通过（因为音频轨道已经就绪，所以对端能正常收到声音），但传输过程中只会发送空的黑屏帧，不会携带有效视频内容。你本地测试能正常播放，是因为本地video元素的实时渲染跳过了轨道muted状态的帧校验，一旦走WebRTC传输就会暴露问题。
  正确的捕获时机要求：必须等到video元素触发canplay/playing事件，且捕获到的视频轨道触发unmute事件、确认readyState为live状态后，再将流加入Peer连接。
• 流添加后未触发重新协商
  Simple Peer建立连接时，如果初始加入的流仅包含音频轨道，SDP协商阶段就会只开音频传输通道。后续再通过addStream()加入带视频轨道的MediaStream时，如果不主动触发重新协商，远端的SDP配置里根本不会预留视频通道，自然收不到视频内容，但初始协商好的音频通道不受影响。
  已连接状态下添加流的正确操作：

  const capturedStream = vidEl.captureStream()
  const videoTrack = capturedStream.getVideoTracks()[0]
  // 等视频轨道拿到第一帧后再操作
  videoTrack.onunmute = () => {
    if (peer.connected) {
      peer.addStream(capturedStream)
      peer.renegotiate() // 必须手动触发重协商，不然新轨道不会同步给对端
    }
  }
  

• SDP语义配置不兼容
  旧版本的Simple Peer默认采用plan-b的SDP语义，这种非标准的实现对独立捕获的视频轨道支持存在bug，经常出现单独的视频轨道被协商逻辑过滤的问题。
  初始化Peer时需要手动指定标准SDP语义：

  const peer = new SimplePeer({
    initiator: isInitiator,
    sdpSemantics: 'unified-plan' // 采用W3C标准的统一计划语义，修复轨道过滤问题
  })
  

• 远端渲染逻辑漏加载视频轨道
  收到远端流后如果直接将流赋值给video元素的srcObject，没有检查流中的视频轨道存在性，或者被浏览器自动播放策略拦截，都会导致远端黑屏——常见的场景是只收到了流的音频部分，视频部分因为协商丢包根本没传过来，但代码没有做校验直接渲染。
  正确的远端渲染逻辑：

  peer.on('stream', (remoteStream) => {
    const remoteVideo = document.querySelector('#remote-video')
    // 校验流是否包含有效视频轨道
    if (remoteStream.getVideoTracks().length === 0) {
      console.log('当前收到的流无视频轨道，协商过程丢失了视频通道')
      return
    }
    remoteVideo.srcObject = remoteStream
    // 解除浏览器自动播放拦截
    remoteVideo.play().catch(err => console.log('视频播放被拦截', err))
  })
  

快速定位调试步骤 #

• 发送端打印捕获流的所有轨道属性，确认视频轨道存在、状态为live且非muted
• 打开浏览器内置的WebRTC调试面板，查看视频通道的传输比特率：如果比特率为0，说明发送端编码器没拿到有效帧，是捕获时机的问题；如果比特率正常但远端黑屏，说明是远端渲染的问题
• 检查协商日志，确认添加视频流后确实触发了重新协商流程，且没有协商报错导致的通道建立失败

内容的提问来源于stack exchange，提问作者QuangNV