实现音视频互动

本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。

首先，你需要了解以下有关音视频实时互动的基础概念：

• 声网实时互动 SDK：由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
• 频道：用于传输数据的通道，在同一个频道内的用户可以进行实时互动。
• 主播：可以在频道内发布音视频，同时也可以订阅其他主播发布的音视频。
• 观众：可以在频道内订阅音视频，不具备发布音视频权限。

更多概念详见关键概念。

下图以直播场景为例，展示在 App 中实现音视频互动的基本工作流程：

1. 所有用户调用 joinChannel 方法加入频道，并根据需要设置用户角色：
   • 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。
   • 视频通话：将所有的用户角色都为主播。
2. 加入频道后，不同角色的用户具备不同的行为：
   • 所有用户默认都可以接收频道中的音视频流。
   • 主播可以在频道内发布音视频流。
   • 观众如果需要发流，可在频道内调用 setClientRole 方法修改用户角色，使其具备发流权限。

前提条件

目标平台为 Android

• React Native 0.60 或以上
• macOS 、Windows 或 Linux 操作系统
• Node 10 或以上
• Java Development Kit (JDK) 11 或以上
• 最新版本的 Android Studio
• Android 5.0 或以上设备
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 有效的声网账户和声网项目。请参考开通服务，从声网控制台获取以下信息：
  • App ID：声网随机生成的字符串，用于识别你的 App。
  • 临时 Token：你的 App 客户端加入频道时会使用 Token 对用户进行鉴权。临时 Token 的有效期为 24 小时。

目标平台为 iOS

• React Native 0.60 或以上
• macOS 操作系统
• Node 10 或以上
• Xcode 10 或以上
• CocoaPods
• iOS 9.0 或以上设备。如果你使用 React Native 0.63 或以上版本，请确保 iOS 的版本高于 10.0。
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。
• 有效的声网账户和声网项目。请参考开通服务，从声网控制台获取以下信息：
  • App ID：声网随机生成的字符串，用于识别你的 App。
  • 临时 Token：你的 App 客户端加入频道时会使用 Token 对用户进行鉴权。临时 Token 的有效期为 24 小时。

关于搭建开发环境的更多注意事项，详见搭建开发环境。

注意

声网 React Native SDK 默认使用同步模式（sync mode）。因此，建议你避免在 Chrome Debug 模式下使用 SDK，否则会收到报错信息，例如 Invariant Violation: Calling synchronous methods on native modules is not supported in Chrome。

创建项目

参考以下步骤，创建一个 React Native 项目。

1. 确保你已根据你使用的操作系统、针对的目标平台，完成了开发环境的搭建。

2. 运行以下命令，在 ProjectName 处填入你的项目名称，创建并初始化一个新项目。

   Shell

   npx react-native init ProjectName --template react-native-template-typescript

   运行完成后，会在执行该命令的路径下自动生成一个简单的示例项目。

3. 启动你的 Andoird 或 iOS 模拟器，执行以下命令运行你的项目：

   a. 在项目根目录下执行 npx react-native start 启动 Metro。

   b. 在项目目录下再打开一个终端，执行 npx react-native run-android 运行 Android 应用或执行 npx react-native run-ios 运行 iOS 应用。

如果配置没有问题，你可以看到应用自动安装到模拟器上并开始运行。你也可以在 Android 或 iOS 真机上运行应用，详见在设备上运行。

现在你已经成功运行了项目，可以开始尝试集成声网 SDK 并修改项目。

集成 SDK

本节介绍如何在 React Native 0.60 或以上版本集成声网 React Native SDK。

1. 在项目根目录下，使用以下任意一种方法下载最新版的声网 React Native SDK：

   • 方法一：使用 npm 下载

     Shell

     npm i --save react-native-agora

   • 方法二：使用 yarn 下载

     Shell

     // 安装 yarn
     npm install -g yarn
     // 使用 yarn 下载声网 React Native SDK
     yarn add react-native-agora

     信息

     React Native 0.60.0 或以上版本支持自动链接原生模块，请勿手动链接。详见 Autolinking。

2. 如果你的目标平台是 iOS， 还需要执行 npx pod-install 安装 SDK。

创建用户界面

根据实时音视频互动的场景需要，为你的项目创建两个视图框，分别用于展示本地视频和远端视频，并配置加入频道和离开频道按钮。复制以下代码即可快速创建场景所需的用户界面。

创建用户界面示例代码

TypeScript

// 导入 React Hooks
import React, {useRef, useState, useEffect} from 'react';
// 导入用户界面元素
import {
    SafeAreaView,
    ScrollView,
    StyleSheet,
    Text,
    View,
    Switch,
} from 'react-native';

const App = () => {
    const agoraEngineRef = useRef<IRtcEngine>(); // IRtcEngine 实例
    const [isJoined, setIsJoined] = useState(false); // 本地用户是否已加入频道
    const [isHost, setIsHost] = useState(true); // 用户角色
    const [remoteUid, setRemoteUid] = useState(0); // 远端用户的 Uid
    const [message, setMessage] = useState(''); // 用户提示信息


    // 渲染用户界面
    return (
    <SafeAreaView style={styles.main}>
        <Text style={styles.head}>声网实时音视频互动快速开始</Text>
        <View style={styles.btnContainer}>
            <Text onPress={join} style={styles.button}>
                加入频道
            </Text>
            <Text onPress={leave} style={styles.button}>
                离开频道
            </Text>
        </View>
        <View style={styles.btnContainer}>
            <Text>Audience</Text>
            <Switch
                onValueChange={switchValue => {
                    setIsHost(switchValue);
                    if (isJoined) {
                    leave();
                    }
                }}
                value={isHost}
            />
            <Text>Host</Text>
        </View>        
		<ScrollView
            style={styles.scroll}
            contentContainerStyle={styles.scrollContainer}>
            {isJoined ? (
                <React.Fragment key={0}>
                <RtcSurfaceView canvas={{uid: 0}} style={styles.videoView} />
                <Text>本地用户 uid: {uid}</Text>
                </React.Fragment>
            ) : (
                <Text>加入一个频道</Text>
            )}
            {isJoined && !isHost && remoteUid !== 0 ? (
                <React.Fragment key={remoteUid}>
                <RtcSurfaceView
                    canvas={{uid: remoteUid}}
                    style={styles.videoView}
                />
                <Text>远端用户 uid: {remoteUid}</Text>
                </React.Fragment>
            ) : (
                <Text>{isJoined && !isHost ? '等待远端用户加入' : ''}</Text>
            )}
            <Text style={styles.info}>{message}</Text>
        </ScrollView>
    </SafeAreaView>
);

	// 展示信息
    function showMessage(msg: string) {
        setMessage(msg);
    }
};

// 定义用户界面样式
const styles = StyleSheet.create({
    button: {
        paddingHorizontal: 25,
        paddingVertical: 4,
        fontWeight: 'bold',
        color: '#ffffff',
        backgroundColor: '#0055cc',
        margin: 5,
    },
    main: {flex: 1, alignItems: 'center'},
    scroll: {flex: 1, backgroundColor: '#ddeeff', width: '100%'},
    scrollContainer: {alignItems: 'center'},
    videoView: {width: '90%', height: 200},
    btnContainer: {flexDirection: 'row', justifyContent: 'center'},
    head: {fontSize: 20},
    info: {backgroundColor: '#ffffe0', paddingHorizontal: 8, color: '#0000ff'}
});

实现流程

本节介绍如何实现一个实时音视频互动 App。

下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。

下面列出了一段实现实时音视频互动基本流程的完整代码以供参考，你可以先复制完整的示例代码到你的项目中，参考测试项目中的步骤快速体验实时音视频互动的基础功能，再按照实现流程了解其中的核心 API 调用。

复制以下代码替换 App.tsx 文件的全部内容，即可快速体验实时音视频互动基础功能。

实现音视频互动功能示例代码

TypeScript

// 导入 React Hooks
import React, {useRef, useState, useEffect} from 'react';
// 导入用户界面元素
import {
    SafeAreaView,
    ScrollView,
    StyleSheet,
    Text,
    View,
    Switch,
} from 'react-native';
// 导入获取 Android 设备权限相关组件
import {PermissionsAndroid, Platform} from 'react-native';
// 导入声网 SDK
import {
    ClientRoleType,
    createAgoraRtcEngine,
    IRtcEngine,
    RtcSurfaceView,
    ChannelProfileType,
    AudienceLatencyLevelType,
} from 'react-native-agora';


// 定义基本信息
const appId = '<-- Insert App ID -->';
const token = '<-- Insert Token -->';
const channelName = '<-- Insert Channel Name -->';
const uid = 0; // 本地用户 Uid，无需修改

const App = () => {
    const agoraEngineRef = useRef<IRtcEngine>(); // IRtcEngine 实例
    const [isJoined, setIsJoined] = useState(false); // 本地用户是否已加入频道
    const [isHost, setIsHost] = useState(true); // 用户角色
    const [remoteUid, setRemoteUid] = useState(0); // 远端用户的 Uid
    const [message, setMessage] = useState(''); // 用户提示信息

    // 启动 App 时初始化引擎
	useEffect(() => {
       setupVideoSDKEngine();
    });
    const setupVideoSDKEngine = async () => {
       try {
       // 获取设备权限后创建 RtcEngine
       if (Platform.OS === 'android') {
                      await getPermission()};
       agoraEngineRef.current = createAgoraRtcEngine();
       const agoraEngine = agoraEngineRef.current;
       
       // 注册回调事件
       agoraEngine.registerEventHandler({
           onJoinChannelSuccess: () => {
               showMessage('成功加入频道：' + channelName);
               setIsJoined(true);
           },
           onUserJoined: (_connection, Uid) => {
               showMessage('远端用户 ' + Uid + ' 已加入');
               setRemoteUid(Uid);
           },
           onUserOffline: (_connection, Uid) => {
               showMessage('远端用户 ' + Uid + '已离开频道');
               setRemoteUid(0);
           },
       });
       // 初始化引擎
       agoraEngine.initialize({
           appId: appId,
       });
       // 开启本地视频
       agoraEngine.enableVideo();
       } catch (e) {
           console.log(e);
       }
    };
	// 定义点击加入频道按钮后调用的 join 方法 
    const join = async () => {
        if (isJoined) {
            return;
        }
        try {
            // 加入频道后设置频道场景类型为直播
            agoraEngineRef.current?.setChannelProfile(
                ChannelProfileType.ChannelProfileLiveBroadcasting,
            );
            if (isHost) {
            // 开启预览
            agoraEngineRef.current?.startPreview();
            // 以主播角色加入频道
            agoraEngineRef.current?.joinChannel(token, channelName, uid, {
                clientRoleType: ClientRoleType.ClientRoleBroadcaster});
            } else {
            // 以观众角色加入频道
            agoraEngineRef.current?.joinChannel(token, channelName, uid, {
                clientRoleType: ClientRoleType.ClientRoleAudience,
                audienceLatencyLevelType: AudienceLatencyLevelType.AudienceLatencyLevelUltraLowLatency
                });
            }
        } catch (e) {
            console.log(e);
        }
    };
    // 定义点击离开频道按钮后调用的 leave 方法 
    const leave = () => {
        try {
            // 调用 leaveChannel 方法离开频道
            agoraEngineRef.current?.leaveChannel();
            setRemoteUid(0);
            setIsJoined(false);
            showMessage('已离开频道');
        } catch (e) {
            console.log(e);
        }
    };

    // 渲染用户界面
    return (
    <SafeAreaView style={styles.main}>
        <Text style={styles.head}>声网互动直播快速开始</Text>
        <View style={styles.btnContainer}>
            <Text onPress={join} style={styles.button}>
                加入频道
            </Text>
            <Text onPress={leave} style={styles.button}>
                离开频道
            </Text>
        </View>
        <View style={styles.btnContainer}>
            <Text>Audience</Text>
            <Switch
                onValueChange={switchValue => {
                    setIsHost(switchValue);
                    if (isJoined) {
                    leave();
                    }
                }}
                value={isHost}
            />
            <Text>Host</Text>
        </View>        
		<ScrollView
            style={styles.scroll}
            contentContainerStyle={styles.scrollContainer}>
            {isJoined ? (
                <React.Fragment key={0}>
                <RtcSurfaceView canvas={{uid: 0}} style={styles.videoView} />
                <Text>本地用户 uid: {uid}</Text>
                </React.Fragment>
            ) : (
                <Text>加入一个频道</Text>
            )}
            {isJoined && !isHost && remoteUid !== 0 ? (
                <React.Fragment key={remoteUid}>
                <RtcSurfaceView
                    canvas={{uid: remoteUid}}
                    style={styles.videoView}
                />
                <Text>远端用户 uid: {remoteUid}</Text>
                </React.Fragment>
            ) : (
                <Text>{isJoined && !isHost ? '等待远端用户加入' : ''}</Text>
            )}
            <Text style={styles.info}>{message}</Text>
        </ScrollView>
    </SafeAreaView>
);

	// 展示信息
    function showMessage(msg: string) {
        setMessage(msg);
    }
};

// 定义用户界面样式
const styles = StyleSheet.create({
    button: {
        paddingHorizontal: 25,
        paddingVertical: 4,
        fontWeight: 'bold',
        color: '#ffffff',
        backgroundColor: '#0055cc',
        margin: 5,
    },
    main: {flex: 1, alignItems: 'center'},
    scroll: {flex: 1, backgroundColor: '#ddeeff', width: '100%'},
    scrollContainer: {alignItems: 'center'},
    videoView: {width: '90%', height: 200},
    btnContainer: {flexDirection: 'row', justifyContent: 'center'},
    head: {fontSize: 20},
    info: {backgroundColor: '#ffffe0', paddingHorizontal: 8, color: '#0000ff'}
});

const getPermission = async () => {
    if (Platform.OS === 'android') {
        await PermissionsAndroid.requestMultiple([
            PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
            PermissionsAndroid.PERMISSIONS.CAMERA,
        ]);
    }
};

export default App;

信息

将 <-- Insert App Id -->、<-- Insert Token --> 和 <-- Insert Channel Name --> 分别替换为你在控制台获取到的 App ID、临时 Token，以及生成临时 token 时填入的频道名。

导入依赖项

导入构建 App 所需的依赖项。

TypeScript

// 导入获取 Android 设备权限相关组件
import {PermissionsAndroid, Platform} from 'react-native';
// 导入声网 SDK 
import {
    ClientRoleType,
    createAgoraRtcEngine,
    IRtcEngine,
    RtcSurfaceView,
    ChannelProfileType,
    AudienceLatencyLevelType,
} from 'react-native-agora';

定义基本信息

传入从声网控制台获取的 App ID、临时 Token，以及生成临时 Token 时填入的频道名，用于后续初始化引擎和加入频道。

TypeScript

const appId = '<-- Insert App ID -->';
const token = '<-- Insert Token -->';
const channelName = '<-- Insert Channel Name -->';
const uid = 0; // 本地用户 Uid，无需修改

获取设备权限

根据你的目标平台选择获得麦克风和摄像头的使用权限的方式：

Android

在 Android 设备上，要获得麦克风和摄像头的使用权限，需要弹出提示框供用户选择。

TypeScript

const getPermission = async () => {
    if (Platform.OS === 'android') {
        await PermissionsAndroid.requestMultiple([
            PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
            PermissionsAndroid.PERMISSIONS.CAMERA,
        ]);
    }
};

iOS

在 Xcode 中，打开 info.plist 文件。在右侧列表中添加如下内容，获取相应的设备权限：

Key	Type	Value
Privacy - Microphone Usage Description	String	使用麦克风的目的，例如：for a call or live interactive streaming。
Privacy - Camera Usage Description	String	使用摄像头的目的，例如：for a call or live interactive streaming。

初始化引擎

调用 createAgoraRtcEngine 方法创建一个 RtcEngine 实例，然后调用 initialize 初始化引擎。

TypeScript

agoraEngineRef.current = createAgoraRtcEngine();
const agoraEngine = agoraEngineRef.current;
agoraEngine.initialize({
    appId: appId,
});

启用视频模块

按照以下步骤启用视频模块。

1. 调用 enableVideo 方法，启用视频模块。
2. 调用 startPreview 方法，开启本地视频预览。

TypeScript

agoraEngine.enableVideo();
agoraEngineRef.current?.startPreview();

注册回调

注册以下必要的回调事件可以在触发相应的事件时调用 showMessage 方法提示操作结果，并更新组件状态。

• onJoinChannelSuccess：成功加入频道回调。
• onUserJoined：远端用户加入当前频道回调。
• onUserOffline：远端用户离开当前频道回调。

TypeScript

// 注册回调事件
agoraEngine.registerEventHandler({
    onJoinChannelSuccess: () => {
        showMessage('成功加入频道：' + channelName);
        setIsJoined(true);
    },
    onUserJoined: (_connection, Uid) => {
        showMessage('远端用户 ' + Uid + ' 已加入');
        setRemoteUid(Uid);
    },
    onUserOffline: (_connection, Uid) => {
        showMessage('远端用户 ' + Uid + '已离开频道');
        setRemoteUid(0);
    },
});

加入频道

点击加入频道按钮将调用 setChannelProfile 将频道场景设置为 ChannelProfileLiveBroadcasting，即直播场景。之后调用 joinChannel 加入频道，并设置用户角色设置为 ClientRoleBroadcaster（主播）或者 ClientRoleAudience（观众）。

TypeScript

agoraEngineRef.current?.setChannelProfile(
    ChannelProfileType.ChannelProfileLiveBroadcasting,
);
if (isHost) {
// 开启预览
agoraEngineRef.current?.startPreview();
// 以主播角色加入频道
agoraEngineRef.current?.joinChannel(token, channelName, uid, {
    clientRoleType: ClientRoleType.ClientRoleBroadcaster});
} else {
// 以观众角色加入频道
agoraEngineRef.current?.joinChannel(token, channelName, uid, {
    clientRoleType: ClientRoleType.ClientRoleAudience,
    audienceLatencyLevelType: AudienceLatencyLevelType.AudienceLatencyLevelUltraLowLatency
    });
}

离开频道

调用 leaveChannel 方法离开频道、释放资源并显示文字提示。

TypeScript

// 调用 leaveChannel 方法离开频道
agoraEngineRef.current?.leaveChannel();
setRemoteUid(0);
setIsJoined(false);
showMessage('已离开频道');

测试项目

1. 确保已经在代码中传入了有效的 appId，channelName 和 token。

2. 运行 App。部分模拟机可能无法支持本项目的全部功能，建议你在真机中运行该项目。

   • 在 Android 设备上运行：

     a. 开启 Android 设备的开发者选项，通过 USB 连接线将 Android 设备接入电脑。

     b. 在项目根目录下执行 npx react-native run-android。

   • 在 iOS 设备上运行：

     a. 使用 Xcode 打开 ProjectName/ios/ProjectName.xcworkspace 文件夹。

     b. 通过 USB 线将 iOS 设备接入你的电脑。

     c. 在 Xcode 中，点击 Build and run 按钮。

   信息

   在 Android 或 iOS 真机上运行 App 的详细步骤，请参考 Running On Device。

3. 启动 App，点击按钮加入频道。

4. 邀请一位朋友使用第二台设备，重复以上步骤，在该设备上安装 App，并打开 App 加入频道。你的朋友加入频道后，你们可以看到彼此，并听到彼此的声音。

后续步骤

• 本文的示例使用了临时 Token 加入频道。在测试或生产环境中，为确保通信安全，声网推荐使用 Token 服务器来生成 Token，详见使用 Token 鉴权。
• 如果你想要实现极速直播场景，可以在互动直播的基础上，通过修改观众端的延时级别为低延时 (audienceLatencyLevelLowLatency)实现。详见实现极速直播。

相关信息

本节提供了额外的信息供参考。

示例项目

声网在 GitHub 上提供了一个开源的实时音视频互动示例项目 JoinChannelVideo.tsx 供你参考。

常见问题

• 直播场景下，如何监听远端观众角色用户加入/离开频道的事件？
• 如何处理视频黑屏问题？
• 为什么我无法打开摄像头？
• 如何处理频道相关常见问题？
• 如何设置日志文件？
• 为什么 Android 9 应用锁屏或切后台后采集音视频无效？

相关文档

• 错误码
• 频道连接状态管理