跨房间转发媒体流--实时音视频-火山引擎

文档中心

立即注册

导航

跨房间转发媒体流

最近更新时间：2024.04.22 17:52:22首次发布时间：2022.03.08 20:51:05

跨房间转发媒体流，指可见用户的媒体流可以同时转发到多个 RTC 房间。转发目标房间的数量在 RTC 侧没有限制。
使用转发媒体流功能并不会产生额外的费用，与其他音视频通话遵循相同的计费原则，详见计费规则。

适用场景

本功能适用于以下场景，观众在原来的房间中就能够接收到来自其他房间主播的媒体流。

主播连麦 PK：接受连麦邀请后，主播 A 的音视频流可以转发到主播 B 所在的房间，同时，B 的音视频流也可以转发到 A 房间。观众和主播均无需离开原有房间，即可观赏到两位主播连麦 PK 的音视频内容。
子母直播间：母直播间的音视频为集团总部统一制作，可以同时转发到多个子直播间。子直播间的主播们直接转播母直播间内容，边与用户进行互动，也可以合入自己的个性化内容后进行直播。

前提条件

你已经集成 RTC SDK，实现了基本的音视频通话。
支持跨房间转发功能的 SDK 详见API 及回调。

名词解释

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

功能实现

以下时序图以 Android SDK 中的 API 名称为例。不同端的 SDK 中 API 或回调名称可能略有不同，以 API 及回调为准。

Api sequence

1. 加入房间

创建引擎实例并加入房间，本地用户默认对他人可见。

typescript

java

swift

cpp

import VERTC, { ForwardStreamState } from '@volcengine/rtc';
// 创建引擎实例
const engine = VERTC.createEngine('appid');
// 加入房间
await engine.joinRoom('roomId_token', 'roomId', { userId: 'userid' });

// 创建引擎
rtcVideo = RTCVideo.createRTCVideo(this, Constants.APP_ID, videoEventHandler, null, null);

// 加入房间
private void joinRoom(String roomId) {
    rtcRoom = rtcVideo.createRTCRoom(roomId);
    rtcRoom.setRTCRoomEventHandler(roomEventHandler);
    String token = requestRoomToken(roomId);
    // 用户信息
    UserInfo userInfo = new UserInfo(localUid, "");
    // 设置房间配置
    boolean isAutoPublish = true;
    boolean isAutoSubscribeAudio = true;
    boolean isAutoSubscribeVideo = true;
    RTCRoomConfig roomConfig = new RTCRoomConfig(ChannelProfile.CHANNEL_PROFILE_CHAT_ROOM, isAutoPublish, isAutoSubscribeAudio, isAutoSubscribeVideo);
    // 加入房间
    rtcRoom.joinRoom(token, userInfo, roomConfig);
}

//创建引擎
self?.rtcVideo = ByteRTCVideo.createRTCVideo(kAppID, delegate: self, parameters: [:])
self?.rtcVideo?.startVideoCapture()
self?.rtcVideo?.startAudioCapture()

//创建房间
self.rtcRoom = self.rtcVideo?.createRTCRoom(roomId)
self.rtcRoom?.delegate = self

//加入房间
let userInfo = ByteRTCUserInfo.init()
userInfo.userId = userId

let roomCfg = ByteRTCRoomConfig.init()
self.rtcRoom?.joinRoom(token, userInfo: userInfo, roomConfig: roomCfg)

//创建引擎
bytertc::IRTCVideo *video = bytertc::createRTCVideo(app_id, handler, nullptr);
video->startAudioCapture();
video->startVideoCapture();

//创建房间
bytertc::IRTCRoom *room = video->createRTCRoom(roomid);
room->setRTCRoomEventHandler(room_handler);

bytertc::UserInfo info;
bytertc::RTCRoomConfig config;
info.uid = str_uid.c_str();
config.is_auto_publish = true;
config.is_auto_subscribe_audio = true;
config.is_auto_subscribe_video = true;
int ret = room->joinRoom(token, userinfo, config);

参考构建 RTC 应用获取详细步骤。

2. 开启跨房间转发

startForwardStreamToRooms 中所传入的 token 是与目标房间相对应的 token，而非当前用户所在房间的 token。
在调用 stopForwardStreamToRooms 前，仅可调用一次 startForwardStreamToRooms。
向开启音频选路的房间转发媒体流，该媒体流可能无法被播放。

typescript

java

swift

cpp

// 管理目标房间列表
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);
  }
});

//开启转推
private void startForwardStreamToRooms(String roomId) {
    // 可以向多个房间转推，以下代码仅展示向一个房间转推
    ForwardStreamInfo forwardStreamInfo = new ForwardStreamInfo(roomId, requestRoomToken(roomId));
    if (rtcRoom != null) {
        rtcRoom.startForwardStreamToRooms(Collections.singletonList(forwardStreamInfo));
    }
}

let config = ForwardStreamConfiguration.init()
config.roomId = roomId

// 获取token,建议从服务端获取
let token = generatorToken(roomId: roomId, userId: userId)
config.token = token

// 支持向多个房间转推,数组内传入多个config即可
self.rtcRoom?.startForwardStreamToRooms([config])

// list 存储每个 roomid 及对应 token
for (int i=0; i<list.size(); i++) {
        bytertc::ForwardStreamInfo one;
        one.room_id = roomids[i].c_str();
        one.token = tokens[i].c_str();
        forward_stream_dests.push_back(one);
}
// 开启跨房间转发媒体流
bytertc::ForwardStreamConfiguration configuration;
configuration.dest_count = forward_stream_dests.size();
configuration.forward_stream_dests = forward_stream_dests.data();
int ret = m_room1->startForwardStreamToRooms(configuration);

3. 更新转发配置

更新跨房间媒体流转发请求。
如果调用 updateForwardStreamToRooms 时不传入任何参数或者传空值，会停止所有正在转发的目标房间流。此时仍需要调用 stopForwardStreamToRooms 后才可以再次调用 startForwardStreamToRooms 。

typescript

java

swift

cpp

// 更新跨房间转发媒体流的目标房间列表
const updateResult = await engine.updateForwardStreamToRooms([
  // 列表中不包含 targetRoomIdA，会停止该房间的转发媒体流
  // targetRoomIdB 在之前的目标房间列表中，会更新对应的 token。
  // 在暂停状态下调用更新无法对 token 进行校验。在调用恢复 resumeForwardStreamToAllRooms  后才会进行 token 校验。
  { roomId: 'targetRoomIdB', token: 'targetRoomIdB_new_token' },
  // targetRoomIdC 不在之前的目标房间列表中，会开启向该房间转发媒体流
  { roomId: 'targetRoomIdC', token: 'targetRoomIdC_token' }
]);

// 处理调用结果
// 停止转发的目标房间也会在 updateForwardStreamToRooms 的返回结果中。
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);
  }
});

ForwardStreamInfo forwardStreamInfo = new ForwardStreamInfo(roomId, requestRoomToken(roomId));
    if (rtcRoom != null) {
        rtcRoom.updateForwardStreamToRooms(Collections.singletonList(forwardStreamInfo));
    }

let config = ForwardStreamConfiguration.init()
config.roomId = roomId

// 获取 token,建议从服务端获取
let token = generatorToken(roomId: roomId, userId: userId)
config.token = token

// 支持向多个房间转推,数组内传入多个 config
self.rtcRoom?.updateForwardStreamToRooms([config])

// 创建 list，存放每个房间 roomid 及对应 token
for (int i=0; i<list.size(); i++) {
        bytertc::ForwardStreamInfo one;
        one.room_id = roomids[i].c_str();
        one.token = tokens[i].c_str();
        forward_stream_dests.push_back(one);
}
bytertc::ForwardStreamConfiguration configuration;
configuration.dest_count = forward_stream_dests.size();
configuration.forward_stream_dests = forward_stream_dests.data();
int ret = m_room1->updateForwardStreamToRooms(configuration);

4. 暂停和恢复转发

暂停与恢复向所有目标房间转发媒体流。
在调用 resumeForwardStreamToAllRooms 恢复媒体流转发前，仅可调用一次 pauseForwardStreamToAllRooms 。

typescript

java

swift

cpp

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

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

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

5. 停止转发

停止向所有目标房间转发媒体流。

typescript

java

swift

cpp

await engine.stopForwardStreamToRooms();

6. 回调

监听 onForwardStreamStateChanged，感知跨房间转发媒体流状态。

转发媒体流至目标房间和进入目标房间，将分别触发一次以下回调： onUserJoin 、 onUserLeave 、 onUserPublishStream / onUserPublishScreen 、 onUserUnpublishStream / onUserUnpublishScreen。
如果媒体流转发过程中，用户切换为不可见，媒体流转发将停止。

typescript

java

swift

cpp

function onForwardError(info) {
  console.error(info);
}

engine.on(EngineEventsTypes.onForwardStreamError, onForwardError);

@Override
public void onForwardStreamEvent(ForwardStreamEventInfo[] eventInfos) {
   //跨房间媒体流转发状态和错误回调
}

@Override
public void onForwardStreamStateChanged(ForwardStreamStateInfo[] stateInfos) {
   //跨房间媒体流转发事件回调
}

func rtcRoom(_ rtcRoom: ByteRTCRoom, onForwardStreamStateChanged infos: [ForwardStreamStateInfo]) {
//跨房间媒体流转发状态和错误回调
}

func rtcRoom(_ rtcRoom: ByteRTCRoom, onForwardStreamEvent infos: [ForwardStreamEventInfo]) {
//跨房间媒体流转发事件回调
}

void ByteRTCRoomHandler::onForwardStreamStateChanged(bytertc::ForwardStreamStateInfo* infos, int info_count) {
//跨房间媒体流转发状态和错误回调
}

void ByteRTCRoomHandler::onForwardStreamEvent(bytertc::ForwardStreamEventInfo* infos, int info_count)
{
//跨房间媒体流转发事件回调
}

示例项目

API 及回调

以下客户端 SDK 均支持跨房间转发媒体流功能。你可以根据上文中的描述和实例，使用不同的 SDK，在不同的端上实现这个功能。

说明：表格中的 macOS API 接口为 Objective-C，而示例项目中的 macOS 项目使用的是 Windows SDK 中的 API 接口。

平台	Android	iOS	macOS	Windows	Linux	Web	Electron	Flutter
开启跨房间转发媒体流	`startForwardStreamToRooms`	`startForwardStreamToRooms:`	`startForwardStreamToRooms:`	`startForwardStreamToRooms`	`startForwardStreamToRooms`	`startForwardStreamToRooms`	`startForwardStreamToRooms`	`startForwardStreamToRooms`
更新跨房间转发媒体流	`updateForwardStreamToRooms`	`updateForwardStreamToRooms:`	`updateForwardStreamToRooms:`	`updateForwardStreamToRooms`	`updateForwardStreamToRooms`	`updateForwardStreamToRooms`	`updateForwardStreamToRooms`	`updateForwardStreamToRooms`
恢复跨房间转发媒体流	`resumeForwardStreamToAllRooms`	`resumeForwardStreamToAllRooms`	`resumeForwardStreamToAllRooms`	`resumeForwardStreamToAllRooms`	`resumeForwardStreamToAllRooms`	`resumeForwardStreamToAllRooms`	`resumeForwardStreamToAllRooms`	`resumeForwardStreamToAllRooms`
暂停跨房间转发媒体流	`pauseForwardStreamToAllRooms`	`pauseForwardStreamToAllRooms`	`pauseForwardStreamToAllRooms`	`pauseForwardStreamToAllRooms`	`pauseForwardStreamToAllRooms`	`pauseForwardStreamToAllRooms`	`pauseForwardStreamToAllRooms`	`pauseForwardStreamToAllRooms`
停止跨房间转发媒体流	`stopForwardStreamToRooms`	`stopForwardStreamToRooms`	`stopForwardStreamToRooms`	`stopForwardStreamToRooms`	`stopForwardStreamToRooms`	`stopForwardStreamToRooms`	`stopForwardStreamToRooms`	`stopForwardStreamToRooms`
状态和错误回调	`onForwardStreamStateChanged`	`rtcRoom:onForwardStreamStateChanged:`	`rtcRoom:onForwardStreamStateChanged:`	`onForwardStreamStateChanged`	`onForwardStreamStateChanged`	`onForwardStreamError`	`onForwardStreamStateChanged`	`onForwardStreamStateChanged`
事件回调	`onForwardStreamEvent`	`rtcRoom:onForwardStreamEvent:`	`rtcRoom:onForwardStreamEvent:`	`onForwardStreamEvent`	`onForwardStreamEvent`	无	`onForwardStreamEvent`	`onForwardStreamEvent`

功能变更日志

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