跨房间转发媒体流，指可见用户的媒体流可以同时转发到多个 RTC 房间。转发目标房间的数量在 RTC 侧没有限制。 本功能适用于以下场景，观众在原来的房间中就能够接收到来自其他房间主播的媒体流。

适用场景
功能变更日志

  1. 自 Native SDK v3.34 起，本功能在 Native 端可用。

  2. 自 Web SDK v4.54 起，本功能在 Web 端可用。

注意

微信小程序端 SDK 不支持本功能。

名词解释

转推流：跨房间转发的媒体流
源房间：发送转推流的房间
目标房间：转推流到达的房间

功能实现
示例代码

说明

以下示例代码以 Web RTC SDK 为例，参考对应平台的 API 文档获取更多信息。

  1. 创建引擎实例并加入房间，本地用户默认对他人可见。
import VERTC, { ForwardStreamState } from '@volcengine/rtc';

// 创建引擎实例
const engine = VERTC.createEngine('appid');

// 加入房间
await engine.joinRoom('roomId_token', 'roomId', { userId: 'userid' });

typescript
  1. 开启跨房间转发媒体流。

注意

  • startForwardStreamToRooms 中所传入的 token 是与目标房间相对应的 token，而非本房间 token。
  • 在调用 stopForwardStreamToRooms 前，仅可调用一次 startForwardStreamToRooms。
// 管理目标房间列表
const targetRoomList: string[] = [];

// 开启跨房间转发媒体流
const startResult = await engine.startForwardStreamToRooms([
  { roomId: 'targetRoomIdA', token: 'targetRoomIdA_token' },
  // 可以同时指定多个目标房间
  { roomId: 'targetRoomIdB', token: 'targetRoomIdB_token' }
]);

// 处理调用结果
startResult.forEach(item => {
  if (item.state === ForwardStreamState.FORWARD_STREAM_STATE_SUCCESS) {
    // 保存成功的目标房间
    targetRoomList.push(item.roomId);
  } else {
    // 根据错误码进行对应处理
    console.error(item.error);
  }
});

typescript
  1. 更新跨房间媒体流转发信息。

注意

  • 如果调用 updateForwardStreamToRooms 时不传入任何参数，则将停止所有已转发的目标房间流。此时仍需要调用 stopForwardStreamToRooms 后才可以再次调用 startForwardStreamToRooms。
  • 停止转发的目标房间也会在 updateForwardStreamToRooms 的返回结果中。
  • 在暂停状态下调用更新无法对 token 进行校验。在调用恢复后才会进行 token 校验。
// 更新跨房间转发媒体流的目标房间列表
const updateResult = await engine.updateForwardStreamToRooms([
  // 列表中不包含 targetRoomIdA，会停止该房间的转发媒体流
  // targetRoomIdB 在之前的目标房间列表中，会更新对应的 token
  { roomId: 'targetRoomIdB', token: 'targetRoomIdB_new_token' },
  // targetRoomIdC 不在之前的目标房间列表中，会开启向该房间转发媒体流
  { roomId: 'targetRoomIdC', token: 'targetRoomIdC_token' }
]);

// 处理调用结果
updateResult.forEach(item => {
  if (item.state === ForwardStreamState.FORWARD_STREAM_STATE_SUCCESS) {
    if (!['targetRoomIdB', 'targetRoomIdC'].includes(item.roomId)) {
      // 不在请求列表中，但在返回结果中的应当删除
      targetRoomList.splice(targetRoomList.indexOf(item.roomId), 1);
    } else if (!targetRoomList.includes(item.roomId)) {
      // 不在已有房间中，需要新增
      targetRoomList.push(item.roomId);
    }
  } else {
    // 根据错误码进行对应处理
    console.error(item.error);
  }
});

typescript
  1. 暂停与恢复向所有目标房间转发媒体流。

注意

在调用 resumeForwardStreamToAllRooms 恢复媒体流转发前，仅可调用一次 pauseForwardStreamToAllRooms。

// 暂停跨房间转发媒体流的目标房间列表
await engine.pauseForwardStreamToAllRooms();

// 恢复跨房间转发媒体流的目标房间列表
const result = await engine.resumeForwardStreamToAllRooms();

// 处理调用结果
result.forEach(item => {
  if (item.state !== ForwardStreamState.FORWARD_STREAM_STATE_SUCCESS) {
    // 根据错误码进行对应处理
    console.error(item.error);
  }
});

typescript
  1. 停止向所有目标房间转发媒体流。
// 停止跨房间转发媒体流的目标房间列表
await engine.stopForwardStreamToRooms();

typescript
  1. 监听跨房间转发媒体流状态。
function onForwardError(info) {
  console.error(info);
}

engine.on(EngineEventsTypes.onForwardStreamError, onForwardError);

typescript
API 参考

参考以下顺序，调用 API 实现此功能：

步骤调用目标AndroidiOSWindowsWeb
1开启跨房间转发媒体流startForwardStreamToRoomsstartForwardStreamToRooms:startForwardStreamToRoomsstartForwardStreamToRooms
可选更新跨房间转发媒体流updateForwardStreamToRoomsupdateForwardStreamToRooms:updateForwardStreamToRoomsupdateForwardStreamToRooms
可选暂停跨房间转发媒体流pauseForwardStreamToAllRoomspauseForwardStreamToAllRoomspauseForwardStreamToAllRoomspauseForwardStreamToAllRooms
恢复跨房间转发媒体流resumeForwardStreamToAllRoomsresumeForwardStreamToAllRoomsresumeForwardStreamToAllRoomsresumeForwardStreamToAllRooms
2停止跨房间转发媒体流stopForwardStreamToRoomsstopForwardStreamToRoomsstopForwardStreamToRoomsstopForwardStreamToRooms
注意事项