# 实现音视频互动 (/zh-CN/realtime-media/rtc/get-started/quick-start/windows) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何集成声网实时互动 SDK，通过少量代码从 0 开始实现一个简单的实时互动 App，适用于互动直播和视频通话场景。 首先，你需要了解以下有关音视频实时互动的基础概念： - 声网实时互动 SDK：由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。 - 频道：用于传输数据的通道，在同一个频道内的用户可以进行实时互动。 - 主播：可以在频道内**发布**音视频，同时也可以**订阅**其他主播发布的音视频。 - 观众：可以在频道内**订阅**音视频，不具备**发布**音视频权限。 更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。 下图展示在 App 中实现音视频互动的基本工作流程： 1. 所有用户调用 `joinChannel` 方法加入频道，并根据需要设置用户角色： - 互动直播：如果用户需要在频道中发流，则设为主播；如果用户只需要收流，则设为观众。 - 视频通话：将所有用户的角色都设为主播。 2. 加入频道后，不同角色的用户具备不同的行为： - 所有用户默认都可以接收频道中的音视频流。 - 主播可以在频道内发布音视频流。 - 观众如果需要发流，可在频道内调用 `setClientRole` 方法修改用户角色，使其具备发流权限。 ## 前提条件 [#前提条件-4] 在实现功能以前，请按照以下要求准备开发环境： - Windows 7 或以上版本的设备。 - Microsoft Visual Studio 2017 或以上版本。 - C++ 11 或以上版本。 - 如果使用 C# 开发，还需要 [.NET 桌面开发组件](https://learn.microsoft.com/en-us/dotnet/framework/install/guide-for-developers)。 - 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得 App ID 和临时 Token。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: C++ C# ## 创建项目 [#创建项目-3] 以 Windows 11 为例，参考以下操作或[官方文档](https://learn.microsoft.com/en-us/visualstudio/ide/create-new-project?view=vs-2022)在 Visual Studio 2022 中创建一个项目来实现实时音视频互动功能，如果你已有自己的项目，可跳过这一步骤。 1. 在 Visual Studio 中，选择**文件** > **新建** > **项目** 来创建一个新项目。在弹出的窗口中，选择 **MFC 应用**作为项目模板，点击**下一步**将项目名称设为 **AgoraQuickStart** 并设置项目储存位置，然后点击**创建**。 2. 在弹出的 MFC 应用程序窗口中，将**应用程序类型**设为**基于对话框**，将**使用 MFC** 设为**在共享 DLL 中使用 MFC**。进入**生成的类**，将**生成的类**设为 **Dlg**，将**基类**设为 **CDialog**，最后点击**完成**。 ## 集成 SDK [#集成-sdk-3] 1. 从[下载](/zh-CN/realtime-media/rtc/reference/downloads)获取最新的 Windows SDK，解压并打开。 2. 打开已下载的 SDK 文件，并将其中的 `sdk` 文件夹复制到你的项目路径下。保证 `sdk` 文件夹和你的 `sln` 文件处于同一目录。 :::warning[注意] 自 4.5.0 起，RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 `libaosl.dll` 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK，为避免冲突，请手动删除版本较低的 `libaosl.dll` 库。4.6.0 RTC SDK `libaosl.dll` 库版本为 1.3.0。你可以通过查看 `libaosl.dll` 文件的属性来得知库的版本信息。 ::: ## 配置项目属性 [#配置项目属性] 在**解决方案资源管理器**窗口中，右击项目名称并点击**属性**进行以下配置： 1. 进入 **C/C++ > 常规 > 附加包含目录**菜单，输入 `$(SolutionDir)sdk\high_level_api\include`。 2. 进入**链接器 > 常规 > 附加库目录**菜单，输入 `$(SolutionDir)sdk\x86_64`。 :::info[信息] 如果你是 x86 的 Windows 操作系统，请输入 `$(SolutionDir)sdk\x86`。 ::: 3. 进入**链接器 > 输入 > 附加依赖项**菜单，输入 `$(SolutionDir)sdk\x86_64\agora_rtc_sdk.dll.lib`。 :::info[信息] 如果你是 x86 的 Windows 操作系统，请输入 `$(SolutionDir)sdk\x86\agora_rtc_sdk.dll.lib`。 ::: 4. 进入**高级**菜单，在**高级属性**中，把**将内容复制到 OutDir** 和**将 C++ 运行时复制到输出目录**设为**是**。 5. 进入**生成事件 > 生成后事件 >命令行** 菜单，输入 `copy $(SolutionDir)sdk\x86_64\*.dll $(SolutionDir)$(Platform)\$(Configuration)`。 6. 完成上述配置后点击**应用**。 ## 创建用户界面 [#创建用户界面-3] 根据实时音视频互动的场景需要，你需要在你的应用中添加如下 UI： - 展示本地视频的视图框 - 展示远端视频的视图框 - 输入频道名称的输入框 - 加入和离开频道按钮 你可以参考下列步骤来创建用户界面。 1. 在右侧菜单栏将项目切换为资源视图，然后打开 `.Dialog` 文件，此时你的界面如下图所示： 2. 添加展示远端视频的视图框。在**视图 > 工具箱**中，选择添加 **Picture Control** 控件，在**属性 > 杂项**中，将该控件的 ID 设为 **IDC_STATIC_REMOTE**，如下图所示： 3. 添加展示本地视频的视图框。在**视图 > 工具箱**中，选择添加 **Picture Control** 控件，在**属性 > 杂项**中，将该控件的 ID 设为 **IDC_STATIC_LOCAL**。 4. 添加输入频道名称的输入框。在**视图 > 工具箱**中，选择添加 **Static Text** 控件，在**属性**中将**描述文字**改为**频道名**。然后再添加一个 **Edit Control** 控件作为输入框，在**属性 > 杂项**中，将该控件的 ID 设为 **IDC_EDIT_CHANNEL**。 5. 添加加入和离开频道按钮。在**视图 > 工具箱**中，选择添加两个 **Button** 控件，在**属性 > 杂项**中，将控件的 ID 分设为 **ID_BTN_JOIN** 和 **ID_BTN_LEAVE**，将**描述文字**分别设为**加入**、**离开**。 此时的用户界面如下图所示： ## 实现步骤 [#实现步骤-4] 本小节介绍如何实现一个实时音视频互动应用。你可以先复制完整的示例代码到你的项目中，快速体验实时音视频互动的基础功能，再按照实现步骤了解核心 API 调用。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。 以下展示实现实时互动基本流程的完整示例代码： :::warning[注意] 复制完整示例代码到你的项目之后，你需要将代码中的 `APP_ID` 和 `token` 替换成你在声网控制台获取的 App ID 和临时 Token。 ::: ```cpp #pragma once #include // 引入相关头文件 #include using namespace agora; using namespace agora::rtc; using namespace agora::media; using namespace agora::media::base; // 定义消息 ID #define WM_MSGID(code) (WM_USER+0x200+code) #define EID_JOIN_CHANNEL_SUCCESS 0x00000002 #define EID_USER_JOINED 0x00000004 #define EID_USER_OFFLINE 0x00000004 // 定义 CAgoraQuickStartRtcEngineEventHandler 类，用于处理用户加入、离开频道等回调事件 class CAgoraQuickStartRtcEngineEventHandler : public IRtcEngineEventHandler { public: // 设置消息接收窗口的句柄 void SetMsgReceiver(HWND hWnd) { m_hMsgHanlder = hWnd; } // 注册 onJoinChannelSuccess 回调，本地用户成功加入频道时，会触发该回调 virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_JOIN_CHANNEL_SUCCESS), uid, 0); } } // 注册 onUserJoined 回调，远端主播成功加入频道时，会触发该回调 virtual void onUserJoined(uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_JOINED), uid, 0); } } // 注册 onUserOffline 回调，远端主播离开频道或掉线时，会触发该回调 virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_OFFLINE), uid, 0); } } private: HWND m_hMsgHanlder; }; // CAgoraQuickStartDlg 对话框 class CAgoraQuickStartDlg : public CDialog { public: CAgoraQuickStartDlg(CWnd* pParent = nullptr); virtual ~CAgoraQuickStartDlg(); #ifdef AFX_DESIGN_TIME enum { IDD = IDD_AGORAQUICKSTART_DIALOG }; #endif // 处理加入/离开按钮点击事件 afx_msg void OnBnClickedBtnJoin(); afx_msg void OnBnClickedBtnLeave(); // 处理用户加入频道、用户离开等回调事件 afx_msg LRESULT OnEIDJoinChannelSuccess(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDUserJoined(WPARAM wParam, LPARAM lParam); afx_msg LRESULT OnEIDUserOffline(WPARAM wParam, LPARAM lParam); protected: HICON m_hIcon; CStatic m_staRemote; CStatic m_staLocal; CEdit m_edtChannelName; // DDX/DDV 支持 virtual void DoDataExchange(CDataExchange* pDX); virtual BOOL OnInitDialog(); afx_msg void OnSysCommand(UINT nID, LPARAM lParam); afx_msg void OnPaint(); afx_msg HCURSOR OnQueryDragIcon(); DECLARE_MESSAGE_MAP() std::string cs2utf8(CString str); private: IRtcEngine* m_rtcEngine = nullptr; CAgoraQuickStartRtcEngineEventHandler m_eventHandler; bool m_initialize = false; bool m_remoteRender = false; }; ``` ```cpp // AgoraQuickStartDlg.cpp: 实现文件 // #include "pch.h" #include "framework.h" #include "AgoraQuickStart.h" #include "AgoraQuickStartDlg.h" #include "afxdialogex.h" #ifdef _DEBUG #define new DEBUG_NEW #endif // 用于应用程序“关于”菜单项的 CAboutDlg 对话框 class CAboutDlg : public CDialogEx { public: CAboutDlg(); // 对话框数据 #ifdef AFX_DESIGN_TIME enum { IDD = IDD_ABOUTBOX } ; #endif protected: virtual void DoDataExchange(CDataExchange* pDX); // DDX/DDV 支持 // 实现 protected: DECLARE_MESSAGE_MAP() } ; CAboutDlg::CAboutDlg() : CDialogEx(IDD_ABOUTBOX) { } void CAboutDlg::DoDataExchange(CDataExchange* pDX) { CDialogEx::DoDataExchange(pDX); } BEGIN_MESSAGE_MAP(CAboutDlg, CDialogEx) END_MESSAGE_MAP() // CAgoraQuickStartDlg 对话框，用于处理主要的用户交互和回调事件 CAgoraQuickStartDlg::CAgoraQuickStartDlg(CWnd* pParent /*=nullptr*/ ) : CDialog(IDD_AGORAQUICKSTART_DIALOG, pParent) { m_hIcon = AfxGetApp()->LoadIcon(IDR_MAINFRAME); } CAgoraQuickStartDlg::~CAgoraQuickStartDlg() { CDialog::~CDialog(); // 在删除 CAgoraQuickStartDlg 对象时，释放引擎和相关资源 if(m_rtcEngine) { m_rtcEngine->release(true); m_rtcEngine = NULL; } } void CAgoraQuickStartDlg::DoDataExchange(CDataExchange* pDX) { CDialog::DoDataExchange(pDX); // 将控件和变量关联起来，以便于读写控件的数据 DDX_Control(pDX, IDC_EDIT_CHANNEL, m_edtChannelName); DDX_Control(pDX, IDC_STATIC_REMOTE, m_staRemote); DDX_Control(pDX, IDC_STATIC_LOCAL, m_staLocal); } BEGIN_MESSAGE_MAP(CAgoraQuickStartDlg, CDialog) // 声明消息映射，用于处理 Windows 消息和用户加入、离开频道等事件 ON_WM_SYSCOMMAND() ON_WM_PAINT() ON_WM_QUERYDRAGICON() ON_BN_CLICKED(ID_BTN_JOIN, &CAgoraQuickStartDlg::OnBnClickedBtnJoin) ON_BN_CLICKED(ID_BTN_LEAVE, &CAgoraQuickStartDlg::OnBnClickedBtnLeave) ON_MESSAGE(WM_MSGID(EID_JOIN_CHANNEL_SUCCESS), CAgoraQuickStartDlg::OnEIDJoinChannelSuccess) ON_MESSAGE(WM_MSGID(EID_USER_JOINED), &CAgoraQuickStartDlg::OnEIDUserJoined) ON_MESSAGE(WM_MSGID(EID_USER_OFFLINE), &CAgoraQuickStartDlg::OnEIDUserOffline) END_MESSAGE_MAP() // CAgoraQuickStartDlg 消息处理程序 // 填入你项目的 App ID，在声网控制台获取 #define "" // 填入你在声网控制台获取的临时 Token #define "" BOOL CAgoraQuickStartDlg::OnInitDialog() { CDialog::OnInitDialog(); // 将“关于...”菜单项添加到系统菜单中 // IDM_ABOUTBOX 必须在系统命令范围内 ASSERT((IDM_ABOUTBOX & 0xFFF0) == IDM_ABOUTBOX); ASSERT(IDM_ABOUTBOX < 0xF000); CMenu* pSysMenu = GetSystemMenu(FALSE); if (pSysMenu != nullptr) { BOOL bNameValid; CString strAboutMenu; bNameValid = strAboutMenu.LoadString(IDS_ABOUTBOX); ASSERT(bNameValid); if (!strAboutMenu.IsEmpty()) { pSysMenu->AppendMenu(MF_SEPARATOR); pSysMenu->AppendMenu(MF_STRING, IDM_ABOUTBOX, strAboutMenu); } } // 设置此对话框的图标。当应用程序主窗口不是对话框时，框架将自动执行此操作 SetIcon(m_hIcon, TRUE); // 设置大图标 SetIcon(m_hIcon, FALSE); // 设置小图 m_eventHandler.SetMsgReceiver(m_hWnd); // 创建 rtcEngine 对象 m_rtcEngine = createAgoraRtcEngine(); RtcEngineContext context; context.appId = APP_ID; context.eventHandler = &m_eventHandler; //初始化 int ret = m_rtcEngine->initialize(context); if (ret == 0) { m_initialize = true; } else { m_initialize = false; } // 启用视频模块 m_rtcEngine->enableVideo(); return TRUE; // 除非将焦点设置到控件，否则返回 TRUE } void CAgoraQuickStartDlg::OnSysCommand(UINT nID, LPARAM lParam) { if ((nID & 0xFFF0) == IDM_ABOUTBOX) { CAboutDlg dlgAbout; dlgAbout.DoModal(); } else { CDialog::OnSysCommand(nID, lParam); } } // 如果向对话框添加最小化按钮，则需要下面的代码 // 来绘制该图标。对于使用文档/视图模型的 MFC 应用程序，这将由框架自动完成 void CAgoraQuickStartDlg::OnPaint() { if (IsIconic()) { CPaintDC dc(this); // 用于绘制的设备上下文 SendMessage(WM_ICONERASEBKGND, reinterpret_cast(dc.GetSafeHdc()),0); // 使图标在工作区矩形中居中 int cxIcon = GetSystemMetrics(SM_CXICON); int cyIcon = GetSystemMetrics(SM_CYICON); CRect rect; GetClientRect(&rect); int x = (rect.Width() - cxIcon + 1) / 2; int y = (rect.Height() - cyIcon + 1) / 2; // 绘制图标 dc.DrawIcon(x, y, m_hIcon); } else { CDialog::OnPaint(); } } //当用户拖动最小化窗口时系统调用此函数取得光标 HCURSOR CAgoraQuickStartDlg::OnQueryDragIcon() { return static_cast(m_hIcon); } std::string CAgoraQuickStartDlg::cs2utf8(CString str) { char szBuf[2 * MAX_PATH] = { 0 } ; WideCharToMultiByte(CP_UTF8, 0, str.GetBuffer(0), str.GetLength(), szBuf, 2 *MAX_PATH, NULL, NULL); return szBuf; } void CAgoraQuickStartDlg::OnBnClickedBtnJoin() { // 加入频道 // 获取频道名 CString strChannelName; m_edtChannelName.GetWindowText(strChannelName); if (strChannelName.IsEmpty()) { AfxMessageBox(_T("Fill channel name first")); return; } ChannelMediaOptions option; // 设置频道场景为直播 options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; // 设置用户角色为主播 options.clientRoleType = CLIENT_ROLE_BROADCASTER; // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅频道内的音频流 options.autoSubscribeAudio = true; // 自动订阅频道内的视频流 options.autoSubscribeVideo = true; // 填入你在控制台获取的临时 Token 加入频道 int ret = m_rtcEngine->joinChannel(token, cs2utf8(strChannelName).c_str(), 0,option); // 渲染本地视图 VideoCanvas canvas; canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN; canvas.uid = 0; canvas.view = m_staLocal.GetSafeHwnd(); m_rtcEngine->setupLocalVideo(canvas); // 开启本地视频预览 m_rtcEngine->startPreview(); } void CAgoraQuickStartDlg::OnBnClickedBtnLeave() { // 停止本地视频预览 m_rtcEngine->stopPreview(); // 离开频道 m_rtcEngine->leaveChannel(); // 清除本地视图 VideoCanvas canvas; canvas.uid = 0; m_rtcEngine->setupLocalVideo(canvas); m_remoteRender = false; } LRESULT CAgoraQuickStartDlg::OnEIDJoinChannelSuccess(WPARAM wParam, LPARAM lParam) { // 加入频道成功回调 uid_t localUid = wParam; return 0; } LRESULT CAgoraQuickStartDlg::OnEIDUserJoined(WPARAM wParam, LPARAM lParam) { // 远端用户加入回调 uid_t remoteUid = wParam; if (m_remoteRender) { return 0; } // 渲染远端视图 VideoCanvas canvas; canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN; canvas.uid = remoteUid; canvas.view = m_staRemote.GetSafeHwnd(); m_rtcEngine->setupRemoteVideo(canvas); m_remoteRender = true; return 0; } LRESULT CAgoraQuickStartDlg::OnEIDUserOffline(WPARAM wParam, LPARAM lParam) { // 远端用户离开回调 uid_t remoteUid = wParam; if (!m_remoteRender) { return 0; } // 清除远端视图 VideoCanvas canvas; canvas.uid = remoteUid; m_rtcEngine->setupRemoteVideo(canvas); m_remoteRender = false; return 0; } ``` 参考下列步骤来在你的应用中实现实时互动： ### 初始化引擎 [#初始化引擎-3] 在调用其他声网 API 前，你需要调用 `createAgoraRtcEngine` 创建一个`IRtcEngine` 对象，然后调用 `initialize` 并传入 App ID，初始化 `IRtcEngine`。 :::warning[注意] 在初始化 SDK 前，需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```cpp // 创建 IRtcEngine 对象 m_rtcEngine = createAgoraRtcEngine(); // 创建 IRtcEngine 上下文对象 RtcEngineContext context; // 输入你的 App ID。你可以在声网控制台获取你的项目的 App ID context.appId = APP_ID; // 添加注册回调和事件 context.eventHandler = &m_eventHandler; // 初始化 int ret = m_rtcEngine->initialize(context); if (ret == 0) { m_initialize = true; } else { m_initialize = false; } ``` ### 启用视频模块 [#启用视频模块-3] 1. 调用 `enableVideo` 方法，启用视频模块。 2. 调用 `setupLocalVideo` 初始化本地视图，同时设置本地的视频显示属性。 3. 调用 `startPreview` 方法，开启本地视频预览。 ```cpp // 启用视频模块 m_rtcEngine->enableVideo(); ... // 设置本地视频显示属性 VideoCanvas canvas; // 设置视频尺寸等比缩放 canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN; // 用户 ID canvas.uid = 0; // 视频显示窗口 canvas.view = m_staLocal.GetSafeHwnd(); m_rtcEngine->setupLocalVideo(canvas); // 开启本地视频预览 m_rtcEngine->startPreview(); ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-3] 调用 `joinChannel`[2/2] 方法、填入你在控制台获取的临时 Token，以及获取 Token 时填入的频道名加入频道，并设置用户角色。 ```cpp void CAgoraQuickStartDlg::OnBnClickedBtnJoin() { CString strChannelName; // 获取频道名 m_edtChannelName.GetWindowText(strChannelName); if (strChannelName.IsEmpty()) { AfxMessageBox(_T("Fill channel name first")); return; } ChannelMediaOptions option; // 设置频道场景为直播场景 options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; // 设置用户角色为主播；如果要将用户角色设置为观众，保持默认值即可 options.clientRoleType = CLIENT_ROLE_BROADCASTER; // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; // 填入你在控制台获取的临时 Token 加入频道 m_rtcEngine->joinChannel(token, cs2utf8(strChannelName).c_str(), 0, option); } ``` ### 实现常用回调 [#实现常用回调-3] 你可以根据需求，在初始化时实现其他功能，如注册用户加入、离开频道等回调。 ```cpp class CAgoraQuickStartRtcEngineEventHandler : public IRtcEngineEventHandler { public: // 注册 onJoinChannelSuccess 回调 // 本地用户成功加入频道时，会触发该回调 virtual void onJoinChannelSuccess(const char* channel, uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_JOIN_CHANNEL_SUCCESS), uid, 0); } } // 注册 onUserJoined 回调 // 远端主播成功加入频道时，会触发该回调 virtual void onUserJoined(uid_t uid, int elapsed) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_JOINED), uid, 0); } } // 注册 onUserOffline 回调 // 远端主播离开频道或掉线时，会触发该回调 virtual void onUserOffline(uid_t uid, USER_OFFLINE_REASON_TYPE reason) { if (m_hMsgHanlder) { ::PostMessage(m_hMsgHanlder, WM_MSGID(EID_USER_OFFLINE), uid, 0); } } private: HWND m_hMsgHanlder; }; ``` ### 设置远端视图 [#设置远端视图-1] 当远端用户加入频道时，从远端用户加入频道的回调中获取到的远端用户的 uid，然后调用 `setupRemoteVideo` 设置并渲染远端视图。 ```cpp LRESULT CAgoraQuickStartDlg::OnEIDUserJoined(WPARAM wParam, LPARAM lParam) { // 远端用户加入回调 uid_t remoteUid = wParam; if (m_remoteRender) { return; } // 设置远端视频显示属性 VideoCanvas canvas; // 设置视频尺寸等比缩放 canvas.renderMode = RENDER_MODE_TYPE::RENDER_MODE_HIDDEN; // 远端用户 ID canvas.uid = remoteUid; canvas.view = m_staRemote.GetSafeHwnd(); m_rtcEngine->setupRemoteVideo(canvas); m_remoteRender = true; } ``` ### 离开频道 [#离开频道] 根据场景需要，如关闭应用或应用切换至后台时，调用 `leaveChannel` 离开当前频道。 ```cpp void CAgoraQuickStartDlg::OnBnClickedBtnLeave() { // 停止本地视频预览 m_rtcEngine->stopPreview(); // 离开频道 m_rtcEngine->leaveChannel(); // 清除本地视图 VideoCanvas canvas; canvas.uid = 0; m_rtcEngine->setupLocalVideo(canvas); m_remoteRender = false; } ``` 如果你不再需要互动，调用 `release` 方法释放引擎资源。 :::warning[注意] - 调用 `release` 后，你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能，你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-3)。 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作，因此建议在子线程中调用该方法，避免主线程阻塞。 ::: ```cpp CDialog::~CDialog() { // 在对象被销毁时释放资源 if(m_rtcEngine){ m_rtcEngine->release(true); m_rtcEngine = NULL; } } ``` ## 调试应用 [#调试应用] 按照以下步骤来测试你的应用： 1. 在 Visual Studio 中，选择**本地 Windows 调试器**开始编译应用。 2. 在输入框中输入你要加入的频道名，并点击**加入**按钮加入频道，你将在本地视图中看到自己。 3. 邀请一位朋友通过另一台设备来使用相同的 App ID、频道名、Token 加入频道。你的朋友加入频道后，你们可以听见、看见对方。 ## 创建项目 [#创建项目-4] 参考以下操作，在 Visual Studio 中创建一个 Windows 项目： 1. 在 Visual Studio 上创建一个 Windows Forms 应用项目，详见 [Create a Windows Forms app in Visual Studio with C#](https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2017/ide/create-csharp-winform-visual-studio?view=vs-2017)。 3. 打开 **Configuration Manager** 窗口，在 **Active solution platform** 下拉菜单中选择 **New**，在弹出的窗口中选择 **x64** 或 **x86** 作为目标平台。 ## 集成 SDK [#集成-sdk-4] 使用 Visual Studio 中的 NuGet 包管理器，将 SDK 集成到项目中。详见[快速入门：在 Visual Studio 中安装和使用包](https://learn.microsoft.com/zh-cn/nuget/quickstart/install-and-use-a-package-in-visual-studio)。 :::info[信息] 你可以在 [agora_rtc_sdk](https://www.nuget.org/packages/agora_rtc_sdk/#versions-body-tab) 中获取最新发布的 SDK 的版本信息。 ::: ## 创建用户界面 [#创建用户界面-4] 为直观地体验视频通话，你需要根据应用场景创建用户界面（UI）。若你的项目中已有用户界面，可略过此步骤。 如果你想实现音视频互动，推荐在 UI 上添加以下控件： - 本地视图窗口 - 远端视图窗口 - 加入频道按钮 - 离开频道按钮 参考以下步骤创建 UI。 1. 创建 **Join** 和 **Leave** 按钮 1. 在你的项目中，打开 **Solution Explore** 窗口，双击 **Form1.cs**，打开 **Toolbox** 窗口，选择 **Button** 控件，依次添加两个按钮，并将两个按钮拖放至合适位置。 1. 将鼠标移至其中一个按钮上，点击鼠标右键，选中 **Properties**，在打开的 **Properties** 窗口中修改 **Text** 属性为 **Join**，修改 **Name** 属性为 **btnJoin**。 1. 重复上一个步骤来修改另一个按钮的属性：修改 **Text** 为 **Leave**；修改 **Name** 为 **btnLeave**。 2. 创建本地及远端视图窗口 1. 打开 **Toolbox** 窗口，选中 **PictureBox** 控件，依次为本地视图和远端视图在合适的位置添加控件。 1. 将鼠标移至本地视图窗口控件上，点击鼠标右键，选中 **Properties**，在打开的 **Properties** 窗口中修改 **Name** 属性为 **videoboxLocal**；修改 **BorderStyle** 为 **FixedSingle**。 1. 重复上一个步骤修改远端视图窗口控件的属性：修改 **Name** 为 **videoboxRemote**；修改 **BorderStyle** 为 **FixedSingle**。 3. 创建频道名输入框 1. 打开 **Toolbox** 窗口，选中 **TextBox** 控件，然后将其拖拽至合适位置。 1. 将鼠标移至添加好的输入框控件上，点击鼠标右键，选中 **Properties** ，修改其属性 **Name** 为 **txChannelName**。 4. 保存上述步骤的更改。 5. 分别双击 **Join** 和 **Leave** 按钮，IDE 会自动关联点击事件处理函数。 此时你的 UI 界面如下图所示： ![Windows Forms 用户界面示意图](https://web-cdn.agora.io/docs-files/1684404223720) ## 实现步骤 [#实现步骤-5] 本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中，快速体验实时音视频互动的基础功能，再按照实现步骤了解核心 API 调用。 下图展示了使用声网 RTC SDK 实现音视频互动的基本流程。 下面列出了一段实现实时互动基本流程的完整代码以供参考。 :::info[信息] 在 `APP_ID` 和 `Token` 字段中传入你在控制台获取到的 App ID 和临时 Token。 ::: ```csharp using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Linq; using System.Text; using System.Threading.Tasks; using System.Windows.Forms; using Agora.Rtc; namespace WindowsFormsApp2 { public partial class Form1 : Form { private readonly string APP_ID = ""; private readonly String APP_TOKEN = ""; private IRtcEngine engine_ = null; private RtcEventHandler handler_ = null; public Form1() { InitializeComponent(); // 创建引擎 engine_ = RtcEngine.CreateAgoraRtcEngine(); // 配置引擎实例 RtcEngineContext ctx = new RtcEngineContext() { appId = APP_ID, areaCode = AREA_CODE.AREA_CODE_GLOB, logConfig = { filePath = "rtc.log" } }; // 初始化引擎 var ret = engine_.Initialize(ctx); if (ret != 0) { Console.WriteLine("=====>Initialize failed {0}", ret); return; } // 注册事件句柄 handler_ = new RtcEventHandler(); handler_.EventOnUserJoined += OnUserJoined; engine_.InitEventHandler(handler_); // 启用视频模块 ret = engine_.EnableVideo(); if (ret != 0) { Console.WriteLine("=====>EnableVideo failed {0}", ret); } // 开启本地视频采集 ret = engine_.EnableLocalVideo(true); if (ret != 0) { Console.WriteLine("=====>EnableLocalVideo failed {0}", ret); } // 开始本地视频预览 ret = engine_.StartPreview(VIDEO_SOURCE_TYPE.VIDEO_SOURCE_CAMERA_PRIMARY); if (ret != 0) { Console.WriteLine("=====>StartPreview failed {0}", ret); } // 设置本地视图 VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxLocal.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; ret = engine_.SetupLocalVideo(canvas); if (ret != 0) { Console.WriteLine("=====>SetupLocalVideo failed {0}", ret); } } private void btnJoin_Click(object sender, EventArgs e) { if (null != engine_) { ChannelMediaOptions options = new ChannelMediaOptions(); // 设置频道场景为直播 options.channelProfile.SetValue(CHANNEL_PROFILE_TYPE.CHANNEL_PROFILE_LIVE_BROADCASTING); // 设置用户角色为主播 options.clientRoleType.SetValue(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER); // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; var ret = engine_.JoinChannel(APP_TOKEN, txChannelName.Text, 0, options); Console.WriteLine("=====>JoinChannel result {0}", ret); } } private void btnLeave_Click(object sender, EventArgs e) { if (null != engine_) { var ret = engine_.StopPreview(); var ret = engine_.LeaveChannel(); Console.WriteLine("=====>LeaveChannel result {0}", ret); } } private void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxRemote.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; canvas.uid = remoteUid; int ret = engine_.SetupRemoteVideo(canvas); Console.WriteLine("----->SetupRemoteVideo, ret={0}", ret); } } internal class RtcEventHandler : IRtcEngineEventHandler { public delegate void OnUserJoinedHandler( RtcConnection connection, uint remoteUid, int elapsed ); // 声明 OnUserJoined 回调 public event OnUserJoinedHandler EventOnUserJoined; public RtcEventHandler() { } public override void OnError(int error, string msg) { Console.WriteLine("=====>OnError {0} {1}", error, msg); } public override void OnJoinChannelSuccess(RtcConnection connection, int elapsed) { Console.WriteLine("----->OnJoinChannelSuccess channel={0} uid={1}", connection.channelId,connection.localUid); } public override void OnLeaveChannel(RtcConnection connection, RtcStats stats) { Console.WriteLine("----->OnLeaveChannel duration={0}", stats.duration); } public override void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { Console.WriteLine("----->OnUserJoined uid={0}", remoteUid); if (EventOnUserJoined != null) EventOnUserJoined.Invoke(connection, remoteUid, elapsed); } public override void OnUserOffline( RtcConnection connection, uint remoteUid, USER_OFFLINE_REASON_TYPE reason ) { Console.WriteLine("----->OnUserOffline, channel={0}, remoteUid={1}, reason={2}", connection.channelId, remoteUid, reason); } public override void OnRemoteVideoStateChanged( RtcConnection connection, uint remoteUid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed ) { Console.WriteLine("----->OnRemoteVideoStateChanged, channel={0}, remoteUid={1}, state={2}, reason={3}", connection.channelId, remoteUid, state, reason); } } } ``` ### 导入声网相关的类 [#导入声网相关的类-1] 导入声网 RTC SDK 相关的类。 ```csharp using Agora.Rtc; ``` ### 初始化引擎 [#初始化引擎-4] 调用 `CreateAgoraRtcEngine` 方法创建一个 `RtcEngine` 对象，然后调用 `initialize` 初始化 `RtcEngine`。 ```csharp // 创建引擎 engine_ = RtcEngine.CreateAgoraRtcEngine(); // 配置引擎实例 RtcEngineContext ctx = new RtcEngineContext() { appId = APP_ID, areaCode = AREA_CODE.AREA_CODE_GLOB, logConfig = { filePath = "rtc.log" } }; // 初始化引擎 var ret = engine_.Initialize(ctx); if (ret != 0) { Console.WriteLine("=====>Initialize failed {0}", ret); return; } ``` ### 启用视频模块 [#启用视频模块-4] 1. 调用 `EnableVideo` 方法，启用视频模块。 1. 调用 `SetupLocalVideo` 初始化本地视图，同时设置本地的视频显示属性。 1. 调用 `StartPreview` 方法，开启本地视频预览。 ```csharp // 启用视频模块 ret = engine_.EnableVideo(); if (ret != 0) { Console.WriteLine("=====>EnableVideo failed {0}", ret); } // 设置本地视图 VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxLocal.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; ret = engine_.SetupLocalVideo(canvas); if (ret != 0) { Console.WriteLine("=====>SetupLocalVideo failed {0}", ret); } // 开启本地视频预览 ret = engine_.StartPreview(VIDEO_SOURCE_TYPE.VIDEO_SOURCE_CAMERA_PRIMARY); if (ret != 0) { Console.WriteLine("=====>StartPreview failed {0}", ret); } ``` ### 加入频道并发布音视频流 [#加入频道并发布音视频流-4] 调用 `JoinChannel`[2/2] 加入频道,填入你在控制台获取的临时 Token，以及获取 Token 时填入的频道名加入频道，并设置用户角色。 ```csharp ChannelMediaOptions options = new ChannelMediaOptions(); // 设置频道场景为直播 options.channelProfile.SetValue(CHANNEL_PROFILE_TYPE.CHANNEL_PROFILE_LIVE_BROADCASTING); // 设置用户角色为主播 options.clientRoleType.SetValue(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER); // 发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 发布摄像头采集的视频流 options.publishCameraTrack = true; // 自动订阅所有音频流 options.autoSubscribeAudio = true; // 自动订阅所有视频流 options.autoSubscribeVideo = true; var ret = engine_.JoinChannel(APP_TOKEN, txChannelName.Text, 0, options); ``` ### 设置远端用户视图 [#设置远端用户视图-2] 调用 `SetupRemoteVideo` 方法初始化远端用户视图，同时设置远端用户的视图在本地显示属性。你可以通过 `OnUserJoined` 回调获取远端用户的 `uid`。 ```csharp private void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { VideoCanvas canvas = new VideoCanvas(); canvas.view = (long)videoboxRemote.Handle; canvas.renderMode = RENDER_MODE_TYPE.RENDER_MODE_FIT; canvas.uid = remoteUid int ret = engine_.SetupRemoteVideo(canvas); Console.WriteLine("----->SetupRemoteVideo, ret={0}", ret); } ``` ### 实现常用回调 [#实现常用回调-4] 根据使用场景，定义必要的回调。以下示例代码展示如何实现 `OnJoinChannelSuccess`、 `OnUserJoined` 和 `OnUserOffline` 回调。 ```csharp public override void OnJoinChannelSuccess(RtcConnection connection, int elapsed) { Console.WriteLine("----->OnJoinChannelSuccess channel={0} uid={1}", connection.channelId,connection.localUid); } public override void OnUserJoined(RtcConnection connection, uint remoteUid, int elapsed) { Console.WriteLine("----->OnUserJoined uid={0}", remoteUid); if (EventOnUserJoined != null) EventOnUserJoined.Invoke(connection, remoteUid, elapsed); } public override void OnUserOffline( RtcConnection connection, uint remoteUid, USER_OFFLINE_REASON_TYPE reason ) ``` ### 开始音视频互动 [#开始音视频互动-3] 在 `btnJoin_Click` 函数中调用 `JoinChannel`[2/2] 方法，当用户点击 **Join** 按钮时开始音视频互动。 ```csharp private void btnJoin_Click(object sender, EventArgs e) { if (null != engine_) { ... var ret = engine_.JoinChannel(APP_TOKEN, txChannelName.Text, 0, options); Console.WriteLine("=====>JoinChannel result {0}", ret); } } ``` ### 结束音视频互动 [#结束音视频互动-3] 1. 在 **btnLeave_Click** 函数中调用 `LeaveChannel` 方法，当用户点击 **Leave** 按钮时结束音视频互动。 ```csharp private void btnLeave_Click(object sender, EventArgs e) { if (null != engine_) { var ret = engine_.StopPreview(); var ret = engine_.LeaveChannel(); Console.WriteLine("=====>LeaveChannel result {0}", ret); } } ``` 2. 调用 `Dispose` 销毁引擎，并释放声网 SDK 中使用的所有资源。 ```csharp engine_.Dispose() ``` :::error[警告] - 调用 `Dispose` 后，你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能，你必须重新创建一个新的引擎。详见[初始化引擎](#cs-initialize)。 - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作，因此建议在子线程中调用该方法，避免主线程阻塞。 ::: ## 测试你的项目 [#测试你的项目] 按照以下步骤来测试你的视频通话项目： 1. 将你从声网控制台获取的 App ID 和临时 Token 分别填入到 `Form1.cs` 文件的 `APP_ID` 和 `APP_TOKEN` 中。 1. 在 Visual Studio 中点击 **Start** 按钮运行你的项目，你将在本地视图中看到自己。 2. 在输入框中输入你在声网控制台生成临时 Token 时填写的频道名，并点击 **Join** 按钮加入频道。 4. 邀请一位朋友通过另一台设备来使用相同的 App ID、频道名、Token 加入频道。你的朋友加入频道后，你们可以听见、看见对方。 ## 后续步骤 [#后续步骤-3] - 在测试或生产环境中，为确保通信安全，声网推荐使用 Token 服务器来生成 Token，详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 - 如果你想要实现极速直播场景，可以在互动直播的基础上，通过修改观众端的延时级别为低延时 (`AUDIENCE_LATENCY_LEVEL_LOW_LATENCY`)实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。 ## 参考信息 [#参考信息-4] ### 示例项目 [#示例项目-4] 声网提供了开源的音视频互动示例项目供你参考，你可以前往下载或查看其中的源代码。 C++ C# LiveBroadcasting} href="https://gitee.com/agoraio-community/API-Examples/tree/main/windows/APIExample/APIExample/Basic/LiveBroadcasting" /> LiveBroadcasting} href="https://github.com/Shengwang-Community/API-Examples/tree/main/windows/APIExample/APIExample/Basic/LiveBroadcasting" /> JoinChannelVideo} href="https://github.com/AgoraIO-Extensions/Agora-C_Sharp-SDK/tree/master/APIExample/src/Basic/JoinChannelVideo" /> JoinChannelVideo} href="https://gitee.com/agoraio-community/Agora-C_Sharp-SDK/tree/main/Agora-C_Sharp-RTC-SDK-API_Example/src/Basic/JoinChannelVideo" /> ### 常见问题 [#常见问题-4] - [直播场景下，如何监听远端观众角色用户加入/离开频道的事件？](/zh-CN/reference/faq/integration/audience_event) - [如何处理视频黑屏问题？](/zh-CN/reference/faq/quality/video_blank) - [为什么我无法打开摄像头？](/zh-CN/reference/faq/quality/video_camera) - [如何处理频道相关常见问题？](/zh-CN/reference/faq/integration/channel) - [如何设置日志文件](/zh-CN/reference/faq/integration/set_log_file) - [为什么 SDK 中使用的是动态库而不是静态库？](/zh-CN/reference/faq/integration/dynamic_or_static_library) ### 相关文档 [#相关文档-3] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection)