WetRTC 类

WebRTC 连接门面，框架无关的核心 API。提供连接生命周期管理、事件系统、媒体/数据/监控三大子系统。

导入

import { WetRTC } from '@wetspace/wetrtc'

构造函数

new WetRTC(config: WetRTCConfig)

WetRTCConfig

参数	类型	必填	默认值	说明
signal	SignalChannel	✅	—	信令通道
direction	'sendonly' | 'recvonly' | 'sendrecv'	❌	'sendrecv'	连接方向
iceServers	RTCIceServer[]	❌	[{ urls: 'stun:stun.l.google.com:19302' }]	ICE 服务器列表
iceTransportPolicy	RTCIceTransportPolicy	❌	—	ICE 传输策略
polite	boolean	❌	direction === 'sendonly' 时为 false	Perfect Negotiation 礼貌方
initiator	boolean	❌	direction !== 'recvonly' 时为 true	是否主动创建 offer；被动方（如屏幕分享发送端等待 viewer 连入）可设为 false
dataChannels	DataChannelConfig[]	❌	[]	预配置 DataChannel
signalConfig	SignalConfig	❌	{}	信令配置
statsInterval	number	❌	2000	统计采集间隔 (ms)，0 关闭
logLevel	'debug' | 'info' | 'warn' | 'error' | 'none'	❌	'warn'	日志级别
reconnect	false | ReconnectConfig	❌	{ maxAttempts: 5, baseDelay: 1000, maxDelay: 30000, backoffMultiplier: 2 }	重连策略；传 false 可关闭自动重连
videoEncoding	VideoEncodingOptions	❌	—	发送端视频编码参数（帧率、码率、contentHint 等）；见 视频编码调优
preferredVideoCodec	'auto' | 'h264'	❌	'auto'	视频编解码器偏好；'h264' 在 SDP 协商前优先 H.264（Electron/Chrome 下通常走硬件编码），见 编解码器偏好
audioEncoding	AudioEncodingOptions	❌	—	发送端音频编码参数（码率、优先级等）；见 音频编码调优
preferredAudioCodec	'auto' | 'opus'	❌	'auto'	音频编解码器偏好；'opus' 在 SDP 协商前优先 Opus，见 编解码器偏好

initiator / polite 配对

屏幕分享等「发送端等待 viewer 连入」场景：sendonly + initiator:false + polite:true（主机）与 recvonly + initiator:true + polite:false（viewer）成对使用。完整示例见 virt-screen 集成。

属性

属性	类型	说明
state	ConnectionState	当前连接状态（只读）
peerConnection	RTCPeerConnection | null	底层 RTCPeerConnection（只读）
fsm	ConnectionStateMachine	状态机实例
media	MediaManager	媒体管理子系统
data	DataManager	数据通道子系统
stats	StatsMonitor	统计监控子系统

方法

connect()

connect(): Promise<void>

发起连接。仅允许在 idle 或 failed 状态下调用。

disconnect()

disconnect(): Promise<void>

断开连接，保留实例可重连。关闭当前 RTCPeerConnection 并重建新实例，状态置为 idle。

dispose()

dispose(): void

彻底销毁，释放所有资源。包括 Stats 采集、信令管理器、RTCPeerConnection、所有事件监听器。调用后不可再使用。

on()

on<E extends WetRTCEvent>(event: E, handler: WetRTCEventMap[E]): () => void

注册事件监听器，返回取消监听的函数。

once()

once<E extends WetRTCEvent>(event: E, handler: WetRTCEventMap[E]): void

注册一次性事件监听器。

off()

off<E extends WetRTCEvent>(event: E, handler: WetRTCEventMap[E]): void

取消指定事件监听器。

addTrack()

addTrack(track: MediaStreamTrack, stream: MediaStream): void

添加本地 track 到连接。

当配置了 videoEncoding 时，对视频 track 会自动设置 contentHint，并通过 RTCRtpSender.setParameters 应用帧率、码率与 degradationPreference；连接建立后会再次应用以确保协商完成。

当配置了 audioEncoding 时，对音频 track 会通过 RTCRtpSender.setParameters 应用码率与优先级；连接建立后同样会再次应用。

当 preferredVideoCodec 为 'h264' 时，会在 SDP 协商前对该 transceiver 调用 setCodecPreferences，优先选择 H.264。

当 preferredAudioCodec 为 'opus' 时，会在 SDP 协商前对该 transceiver 调用 setCodecPreferences，优先选择 Opus。

removeTrack()

removeTrack(track: MediaStreamTrack): void

从连接中移除本地 track。

replaceTrack()

replaceTrack(oldTrack: MediaStreamTrack, newTrack: MediaStreamTrack): Promise<void>

替换本地 track，并同步更新底层 RTCRtpSender。

replaceVideoTrack()

replaceVideoTrack(track: MediaStreamTrack): Promise<void>

替换当前视频轨道；若尚无视频轨道，则自动添加。

shareScreen()

shareScreen(options?: DisplayMediaOptions): Promise<MediaStream>

采集屏幕流并自动添加到连接。用户停止浏览器屏幕分享时会自动移除屏幕轨道。

stopScreenShare()

stopScreenShare(): void

停止当前屏幕分享并移除相关 track。

switchCamera()

switchCamera(deviceId?: string): Promise<MediaStream>

切换摄像头。传入 deviceId 时使用指定摄像头，否则使用浏览器默认摄像头。

事件

事件	回调参数	说明
statechange	(state: string, prev: string) => void	连接状态变更
track	(ev: RTCTrackEvent) => void	收到远端媒体流
datachannel	(channel: RTCDataChannel) => void	收到远端 DataChannel
message	(data: unknown, channel: RTCDataChannel) => void	DataChannel 收到消息
error	(err: WetRTCError) => void	错误事件
reconnecting	(attempt: number, max: number) => void	重连进度
stats	(snapshot: StatsSnapshot) => void	统计快照

错误码

type WetRTCErrorCode =
  | 'SIGNAL_FAILED'   // 信令失败
  | 'NEGOTIATION_FAILED' // SDP 协商失败
  | 'ICE_FAILED'      // ICE 连接失败
  | 'MEDIA_FAILED'    // 媒体操作失败
  | 'DATA_FAILED'     // DataChannel 失败
  | 'RECONNECT_FAILED' // 自动重连失败
  | 'INTERNAL'        // 内部错误
  | 'TIMEOUT'         // 超时

interface WetRTCError {
  code: WetRTCErrorCode
  message: string
  recoverable: boolean
}