屏幕共享

功能简介

在视频通话或互动直播中进行屏幕共享，可以将说话人或主播的屏幕内容，以视频的方式分享给其他说话人或观众观看，以提高沟通效率。

屏幕共享在如下场景中应用广泛：

• 视频会议场景中，屏幕共享可以将讲话者本地的文件、数据、网页、PPT 等画面分享给其他与会人；
• 在线课堂场景中，屏幕共享可以将老师的课件、笔记、讲课内容等画面展示给学生观看。

示例项目

Agora 在 GitHub 提供了一个开源的 API-Examples maOS 示例项目，其中的 ScreenShare.swift 文件中实现了屏幕共享功能。你可以直接下载体验或查看其中的源代码。

实现方法

Agora 在 v2.4.0 对屏幕共享相关接口进行梳理，目前在 macOS 平台上支持：

• 通过 displayId 共享指定屏幕，或指定屏幕的部分区域。
• 通过 windowId 共享指定窗口，或指定窗口的部分区域。

共享指定屏幕

macOS 系统为每个屏幕分配一个唯一的 Display ID，名为 CGDirectDisplayID。我们可以按如下步骤实现通过 Display ID 共享指定屏幕：

1. 获取想要共享屏幕的 Display ID：

   • 如果你使用早于 3.5.2 版的 SDK，请使用系统方法获取 Display ID：

       let screenId = screen.deviceDescription[NSDeviceDescriptionKey(rawValue: "NSScreenNumber")]

     更多关于 Display ID 的详情，请参考 Apple deviceDescription 说明。

   • 如果你使用 3.5.2 或之后版的 SDK，除了通过系统方法获取 Display ID 外，你还可以直接通过 SDK 提供的 getScreenCaptureSourcesWithThumbSize 方法返回的 sourceId 获取 Display ID：

       func initSelectScreenPicker() {
           let size = NSSize(width: 100, height: 100)
           let screens = agoraKit.getScreenCaptureSources(withThumbSize: size, iconSize: size, includeScreen: true)
           screens.map { sources in
               selectScreenPicker.picker.addItems(withTitles: sources.filter{ $0.type == .screen }.map {"\($0.sourceName)(\($0.sourceId))"})
           }
           selectScreenPicker.label.stringValue = "Screen Share".localized
       }

2. 通过 Display ID 共享屏幕

    // 开始共享屏幕
    // 如果你的 Mac 设备未外接显示器，display = 0 表示共享当前 Mac 设备屏幕。
    // 如果你的 Mac 设备已外接显示器，display = 0 表示共享主屏幕。系统默认主屏幕为 Mac 设备屏幕，你也可以自行设置外接屏幕为主屏幕。
    let displayId = 0
    let rectangle = CGRect.zero
    let parameters = AgoraScreenCaptureParameters()
    parameters.dimensions = CGSize.zero
    parameters.frameRate = 15
    parameters.bitrate = 1000
    agoraKit.startScreenCapture(bydisplayId: displayId, rectangle: rectangle, parameters: parameters)
   
    // 更新屏幕共享编码参数
    let parameters = AgoraScreenCaptureParameters()
    parameters.dimensions = CGSize.zero
    parameters.frameRate = 15
    parameters.bitrate = 1000
    agoraKit.update(parameters)
   
    // 更新屏幕共享区域
    let region = CGRect.zero
    agoraKit.updateScreenCaptureRegion(region)
   
    // 设置屏幕共享内容类型
    agoraKit.setScreenCapture(.none)
   
    // 停止屏幕共享
    agoraKit.stopScreenCapture()

共享指定窗口

macOS 为每个窗口分配一个唯一的 Window ID，名为 CGWindowID。我们可以按如下步骤在 macOS 平台上实现窗口共享：

1. 获取想要共享窗口的 Window ID

    // Swift
    let windowDicCFArray = CGWindowListCopyWindowInfo([.optionAll, .excludeDesktopElements], 0)

   更多关于 Window ID 的详情，请参考 Apple CGWindowListCopyWindowInfo 说明。

2. 通过 Window ID 共享窗口

    // 开始共享窗口
    let windowId = <#Your Window ID#>
    let rectangle = CGRect.zero
    let parameters = AgoraScreenCaptureParameters()
    parameters.dimensions = CGSize.zero
    parameters.frameRate = 15
    parameters.bitrate = 1000
    agoraKit.startScreenCapture(byWindowId: windowId, rectangle: rectangle, parameters: parameters)
   
    // 更新屏幕共享编码参数
    let parameters = AgoraScreenCaptureParameters()
    parameters.dimensions = CGSize.zero
    parameters.frameRate = 15
    parameters.bitrate = 1000
    agoraKit.update(parameters)
   
    // 更新屏幕共享区域
    let region = CGRect.zero
    agoraKit.updateScreenCaptureRegion(region)
   
    // 设置屏幕共享内容类型
    agoraKit.setScreenCapture(.none)
   
    // 停止屏幕共享
    agoraKit.stopScreenCapture()

API 参考

• getScreenCaptureSourcesWithThumbSize
• startScreenCaptureByDisplayId
• startScreenCaptureByWindowId
• updateScreenCaptureParameters
• setScreenCaptureContentHint
• updateScreenCaptureRegion:
• stopScreenCapture

开发注意事项

• SDK 在 v2.4.0 版本中废弃了原有的屏幕共享接口 startScreenCapture，你仍然可以使用，但 Agora 不再推荐。
• 视频共享编码属性 AgoraScreenCaptureParameters 类中各参数的设置可能会影响计费。从 v2.4.1 版本起，如果你将 dimensions 参数设为默认值，会按照 1920 × 1080 进行计费。
• 如果你使用 3.1.0 及之后版本 SDK 且为屏幕共享另起一个进程，请确保该进程支持 event loop，否则屏幕共享会出现一些可用性问题。