RTCRtpTransceiver 唯一对应一个媒体轨道,包含了一个连接对: RTCRtpSender和RTCRtpReceiver,还包含了管理连接的属性和方法。
WebRTC 在以下几种情况创建 RTCRtpTransceiver,作为属性成员也同时创建了RTCRtpSender 和RTCRtpReceiver。
| RTCRtpTransceiver 类 | |
| 属性 | 描述 |
| currentDirection | (只读)。该属性表示当前的传输方向,类型为 RTCRtpTransceiverDirection。 |
| direction |
该属性用于指定传输方向,可读写,类型为 RTCRtpTransceiverDirection。 为该属性赋值时,如果成功,则会触发 negotiationneeded 事件,表示当前连接需要重新进行协商;如果失败,则抛出异常 InvalidStateError,表示当前连接处于关闭状态。 调用方法 RTCPeerConnection.createOffer() 或 RTCPeerConnection.createAnswer() 创建SDP 信息时,会在 SDP 中包含该值,如果该值是 sendrecv,则 SDP 中会出现如下一行代码。 a=sendrecv |
| mid | (只读)。该属性是连接对的唯一标识,该值从 SDP 信息中获取,如果值为 null,表示 ICE 协商还没有完成。 |
| receiver | (只读)。该属性表示 RTCRtpReceiver 对象,用于接收和解码媒体流数据。 |
| sender | (只读)。该属性表示 RTCRtpSender 对象,用于发送和编码媒体流数据。 |
| 方法 | 描述 |
| setCodecPreferences() |
该方法用于设置编码格式。 参数:codecs,RTCRtpCodecCapability 对象的数组。 返回值:无。 异常:InvalidAccessError: codecs 数组里包含了当前浏览器不支持的编码格式。 |
| stop() |
该方法用于停止传输通道,同时停止与通道相连的 RTCRtpSender 和 RTCRtpReceiver。 输入值:无。 返回值:无。 异常:InvalidStateError,当 RTCPeerConnection 处于关闭状态时,抛出此异常。 |
RTCRtpSender 提供了媒体数据编码及发送能力,当调用 addTrack() 方法添加媒体轨道时,会相应创建一个 RTCRtpSender,用于该媒体发送 RTP 数据。
| RTCRtpSender 属性 | |
| 属性 | 说明 |
| track | 只读。该属性表示与 RTCRtpSender 相连的媒体流轨道,类型为 MediaStreamTrack。 |
| dtmf | 只读。该属性表示与 RTCRtpSender 相连的 RTCDTMFSender 对象。 |
| transport | 只读。该属性表示与 RTCRtpSender 相连的 RTCDtlsTransport 对象,用于安全传输媒体流数据。 |
1.getCapabilities() 静态方法
该方法用于获取平台的发送能力。
const rtpSendCapabilities = RTCRtpSender.getCapabilities(kind)
参数: kind,取值 video 或 audio,分别表示视频和音频。
返回值: RTCRtpCapabilities 对象,如果平台不具备 kind 类型的发送能力,则返回 null。
// RTCRtpCapabilities 的定义
dictionary RTCRtpCapabilities {
required sequence<RTCRtpCodecCapability> codecs;
required sequence<RTCRtpHeaderExtensionCapability> headerExtensions;
};
RTCRtpCapabilities 的属性 codecs 是一个数组,包含了多个类型为 RTCRtpCodecCapability 的编码格式(codec)。
// RTCRtpHeaderExtensionCapability 的定义
dictionary RTCRtpHeaderExtensionCapability {
DOMString uri;
};
RTCRtpHeaderExtensionCapability 包含了一个属性 uri,用于表明 RTP头扩展的地址。
2.getParameters() 方法
该方法用于获取 RTP 媒体编码及传输信息。
const rtpSendParameters = rtpSender.getParameters()
参数:无。
返回值: RTCRtpSendParameters 对象。
// RTCRtpSendParameters 的定义
dictionary RTCRtpSendParameters : RTCRtpParameters {
required DOMString transactionId;
required sequence<RTCRtpEncodingParameters> encodings;
}
// RTCRtpParameters 的定义
dictionary RTCRtpParameters {
required sequence<RTCRtpHeaderExtensionParameters> headerExtensions;
required RTCRtcpParameters rtcp;
required sequence<RTCRtpCodecParameters> codecs;
}
| RTCRtpSendParameters 属性说明 | |
| 属性 | 说明 |
| transactionId | 参数集的 ID 值 |
| encodings | RTCRtpEncodingParameters 对象数组,包含了媒体编码参数 |
| headerExtensions | RTP 头扩展 |
| rtcp | RTCP参数 |
| codecs | 包含媒体编码格式的数组,RTP 发送器将从中选择使用 |
// RTCRtcpParameters 的定义
dictionary RTCRtcpParameters {
DOMString cname;
boolean reducedsize;
}
其中,cname 是指 RTCP 的规范名称,reducedSize 是一个布尔值,当使用了缩减 RTCP 时,值为 true;当使用了复合 RTCP 时,值为 false。
// RTCRtpHeaderExtensionParameters 的定义
dictionary RTCRtpHeaderExtensionParameters {
required DOMString uri;
required unsigned short id;
boolean encrypted = false;
}
其中,uri指 RTP 头扩展的地址,id 指头扩展的标识,encrypted 指头扩展是否使用了压缩。
下面的代码清单演示了调用getParameters0方法获取RTP发送器的参数,将第一个编码设置为不活跃状态,然后调用 setParameters 设置修改后的参数。
async function updateParameters() {
try {
const params = sender.getParameters();
// 将第一个编码设置为不活跃
params.encodings[0].active = false;
await sender.setParameters(params);
} catch (err) {
console.error(err);
}
}
3.setParameters() 方法
该方法更新 RTP 编码及传输信息。
const promise = rtpSender.setParameters(parameters)
参数: parameters,类型为 RTCRtpSendParameters。
返回值: Promise 值。
异常: 如果失败,返回异常值如下表所示。
| setParameters 异常说明 | |
| 异常 | 说明 |
| InvalidModificationError | 修改 encodings 失败 |
| InvalidStateError | RTP发送器所在的 RTCRtpTransceiver 处于非活跃状态 |
| RangeError | parameters 中指定的 scaleResolutionDownBy 小于1 |
| OperationError | 其他原因导致的失败 |
4.replaceTrack() 方法
该方法用于替换媒体流轨道。传入ReplaceTrack()的轨道必须添加进发送流,否则替换会导致传输中断。可以先将新track添加进发送流,再调用ReplaceTrack()方法,也可以先调用ReplaceTrack()方法再添加进发送流。
替换媒体流轨道通常不需要进行 ICE 重新协商,以下场景除外。
aPromise = rtpSender.replaceTrack(newTrack);
参数: newTrack,可选参数,新的媒体流轨道,类型为 MediaStreamTrack,kind值要与原有媒体流轨道保持一致。如果参数为空,则该调用将中止 RTP 发送器。
返回值: Promise 值,成功时无决议值; 如果失败,则返回异常值如下表所示。
| replaceTrack 异常说明 | |
| 异常 | 说明 |
| InvalidModificationError | 替换后媒体流信息发生了改变,需要重新进行ICE 协商 |
| InvalidStateError | 媒体流轨道处于停止状态 |
| TypeError | kind 值不一致 |
下面的代码清单演示了摄像头的切换。
navigator.mediaDevices.getUserMedia({
video: {
deviceId: {
exact: selectedCamera
}
}
}).then((stream) => {
let videoTrack = stream.getVideoTracks()[0];
PCs.forEach((pc) => {
const sender = pc.getSenders().find((s) => {
return s.track.kind == videoTrack.kind;
});
console.log('found sender:', sender);
sender.replaceTrack(videoTrack);
});
}).catch((err) => {
console.error('Error happens:',err);
});
5.getStats() 方法
该方法返回 RTP 发送器的统计数据。
const promise = rtpsender.getstats();
参数:无。
返回值:Promise值,调用成功可得到包含统计数据的 RTCStatsReport 对象。
RTCRtpReceiver 接口负责管理媒体流的接收和解码。
1.track 只读
该属性表示 RTCRtpReceiver 相连的媒体流轨道(MediaStreamTrack)。
1.transport 只读
该属性表示 DTLS 传输对象,类型为 RTCDtlsTransport。
1.getCapabilities() 静态方法
该方法用于获取平台的 RTP 接收能力。
const rtpRecvCapabilities = RTCRtpReceiver.getCapabilities(kind)
参数: kind,取值为 video 或 audio,分别表示视频和音频。
返回值: RTCRtpCapabilities 对象,如果平台不具备 kind 类型的接收能力,则返回 null。
let codecList = RTCRtpReceiver.getCapabilities("audio").codecs;
2.getParameters() 方法
该方法返回 RTP 解码参数。
const rtpRecvParameters = rtcRtpReceiver.getParameters()
参数: 无。
返回值: 当前使用的解码参数,类型为 RTCRtpReceiveParameters。RTCRtpReceiveParameters 继承自 RTCRtpParameters。
3.getContributingSources() 方法
该方法返回最近 10s 内的贡献源(CSRC)。
const rtcRtpContributingSources = rtcRtpReceiver.getContributingSources()
参数: 无。
返回值: 最近 10s 内提供数据的贡献源数组,数组成员类型为 RTCRtpContributingSource。
| RTCRtpContributingSource 属性说明 | |
| 属性 | 说明 |
| timestamp | 最近一个关键帧从源发出的时间 |
| source | 贡献源的 CSRC 标识 |
| audioLevel | 音频音量,取值介于 0 和 1 之间 |
| rtpTimestamp | RTP 数据包的时间戳 |
4.getSynchronizationSources() 方法
该方法返回最近 10s 内的同步源(SSRC)。
const rtcRtpSynchronizationSources = rtcRtpReceiver.getSynchronizationSources()
参数:无。
返回值:最近 10s 内提供数据的同步源数组,数组成员类型为 RTCRtpSynchronizationSource。
RTCRtpSynchronizationSource 继承自 RTCRtContributingSource,增加了属性 voiceActivityFlag,表示 RTP 数据包里声音是否处于活动状态,true 表示声音处于活动状态 (能听到).false 表示声音处于暂停状态 (不能听到)。
5.getStats() 方法
该方法返回 RTP 接收器的统计数据。
const promise = RTCRtpReceiver.getStats();
参数:无。
返回值: Promise 值,调用成功可得到包含统计数据的 RTCStatsReport 对象。