• 实时音视频
    • 实时音视频>客户端 API>HarmonyOS

    HarmonyOS

    编辑文档 更新于
    API 概览BRTCBrtcListenerBrtcDeviceManager枚举和类常见问题

    BRTC

    基础接口

    函数列表 描述
    createEngine 创建引擎，设置配置信息
    destroyEngine 销毁引擎
    getSdkVersion 获取 SDK 版本
    callExperimentalApi 设置试验性参数
    setDefaultStreamRecvMode 设置自动拉流模式
    setNetworkQosParam 设置网络自适应策略
    on 或 off 监听或取消 SDK 回调事件

    房间相关接口

    函数列表 描述
    enterRoom 进入房间
    exitRoom 离开房间

    音视频相关接口

    函数列表 描述
    startLocalPreview 开启本地摄像头的预览画面
    stopLocalPreview 停止摄像头预览
    startLocalAudio 开启本地音频的采集和发布
    stopLocalAudio 停止本地音频的采集和发布
    muteLocalAudio 暂停/恢复发布本地的音频流
    muteLocalVideo 暂停/恢复发布本地的视频流
    startRemoteView 订阅远端用户的视频流，并绑定视频渲染控件
    stopRemoteView 停止订阅远端用户的视频流，并释放渲染控件
    muteRemoteAudio 暂停/恢复播放远端的音频流
    muteRemoteVideo 暂停/恢复订阅远端用户的视频流
    muteAllRemoteAudio 暂停/恢复播放所有远端用户的音频流
    setVideoEncoderParam 设置视频编码器的编码参数
    setVideoEncoderMirror 设置是否开启视频编码水平镜像
    setVideoEncoderRotation 设置视频编码旋转角度
    enableSmallVideoStream 设置是否开启推流小画面
    setRemoteVideoStreamType 设置远端用户流类型（大小流切换）
    setRenderParams 设置本地或远端用户视频画面渲染模式

    屏幕分享相关接口

    函数列表 描述
    startScreenCapture 开始全系统的屏幕分享（仅支持安卓系统）
    stopScreenCapture 停止屏幕分享

    日志相关

    函数列表 描述
    setConsoleEnabled 是否将 SDK 日志输出到 IDE 控制台
    setLogLevel 设置 SDK 输出日志级别
    setLogPath 设置 SDK 保存路径

    详细信息

    createEngine

    创建引擎，设置配置信息

    createEngine(config: BrtcEngineAdvancedConfig | null): Promise<BrtcEngineImpl | null>

    参数

    名称 描述
    config 创建引擎传入的配置信息。建议至少传入 ApplicationContext，否则部分功能可能表现不正常

    返回

    • BRTC 引擎实例对象

    详情

    • 此方法是所有功能的起点，必须获取到合法的 BRTC 引擎实例对象才能进行后续操作。
    • 引擎配置信息是一个字符串数组，不同的版本支持的配置信息不同。具体参见类与枚举中的说明。

    destroyEngine

    销毁 BRTC 引擎

    destroyEngine(): void

    详情

    • 该方法释放 BRTC SDK 使用的所有资源
    • 调用 destroyEngine 方法后，你将无法再使用 SDK 的其它方法和回调
    • 如需再次使用实时音视频通信功能，你必须重新调用 createEngine 方法创建一个新的 BRTC 引擎实例
    • 由于 destroyEngine 执行释放需要一些时间，因此如果在销毁后需要再次创建 BRTC 引擎实例，建议最好控制调用频率，减少可能存在的表现异常隐患。

    getSdkVersion

    获取 SDK 版本信息

    getSdkVersion(): string

    callExperimentalApi

    调用实验性 API 接口

    callExperimentalApi(jsonStr: string): void

    参数

    名称 描述
    jsonStr 接口及参数描述的 JSON 字符串

    详情

    SDK 内部存在一些只针对特殊用户、特殊场景下的参数、方法。这些内容通常情况下，不适用于大多数普通用户，因此不会作为标准接口提供出来。如果在标准接口中未能找到您需要的功能，您可以与我们联系来确认是否在试验性接口中可以开启或者设置。

    setDefaultStreamRecvMode

    设置默认的订阅模式

    setDefaultStreamRecvMode(autoRecvAudio: boolean, autoRecvVideo: boolean): void

    详情

    默认情况下，SDK 在感知到有远端用户推流时，会自动拉取其音视频流，并进行解码。目的是当需要播放远端用户声音和画面时，可以立刻播放，达到“秒开”的效果。但这会需要额外的带宽和计算资源。

    您可以根据使用场景，设置不自动拉流解码，在需要播放的时候再订阅远端音视频流，缺点是播放耗时要长一些。

    注意：需要在进入房间（enterRoom）前调用该接口，设置才能生效。

    参数

    名称 描述
    autoRecvAudio true 表示自动订阅该远端用户的音频流, false 与之相反
    autoRecvVideo true 表示自动订阅该远端用户的视频流, false 与之相反

    setNetworkQosParam

    设置网络流控相关参数

    setNetworkQosParam(qosParam: brtc.BrtcNetworkQosParam): void

    参数

    名称 描述
    qosParam 网络流控参数，详见 BrtcNetworkQosParam

    详情

    • 该设置决定 SDK 在各种网络环境下的调控策略（运行条件受限下，优先选择“保清晰”或“保流畅”）

    on/off

    设置回调接口

    on<EventType extends keyof BrtcListener>(event: EventType, callback: BrtcListener[EventType])

    参数

    名称 描述
    event 事件名称，必须是 BrtcListener 中提供的
    callback 用来处理该事件的方法

    详情

    • 您可以先通过 createEngine() 获得引擎实例，然后调用 engineInstance.on('event', (...) => {}) 获得来自 SDK 的各种状态、事件通知，根据这些回调决定业务的后续动作。

    enterRoom

    加入房间

    enterRoom(roomParams: brtc.BrtcRoomParams): void

    参数

    名称 描述
    roomParams 进房参数，详见 BrtcRoomParams

    详情

    必须加入房间才能发布或订阅音视频流。“发布”是指将自己的音、视频推送到服务器；“订阅”是指从服务器拉取房间里其他用户的音视频流。调用接口后，您会收到来自 BrtcListener 中的 onEnterRoom(result) 回调：

    • 如果加入成功，result 会是一个正数（result > 0），表示加入房间的时间消耗，单位是毫秒（ms）

    • 如果加入失败，result 会是一个负数（result < 0），表示进房失败的错误码

    不管进房是否成功，enterRoom 都必须与 exitRoom 配对使用，在调用 exitRoom 前再次调用 enterRoom 函数会导致不可预期的错误问题。

    exitRoom

    离开房间

    exitRoom(): void

    详情

    • 调用 exitRoom 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等
    • 待资源释放完毕，SDK 会通过 BrtcListener 中的 onExitRoom() 回调通知到您
    • 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来之后再执行相关操作，否则可能会遇到摄像头或麦克风被占用等各种异常问题

    startLocalPreview

    开启本地视频的预览画面

    startLocalPreview(useFront: boolean): void

    参数

    名称 描述
    useFront true：开启前置摄像头；false：开启后置摄像头

    详情

    • 请在 enterRoom 之后调用此函数
    • 此方法调用后，会打开摄像头，请确保您的应用程序申请了摄像头访问权限

    注意

    • 与其他端的 SDK 不同，HarmonyOS SDK 不需要您设置渲染视图对象。您只需要遵守命名规则在您的页面上创建 XComponent 控件即可。
    • 目前尚不支持在进入房间前调用此方法，建议您在收到 onEnterRoom 回调中来调用
    • 如果当前正在屏幕共享，且设置的流类型是 BrtcVideoStreamTypeBig，调用此接口后，将会停止屏幕共享，恢复显示摄像头画面

    stopLocalPreview

    停止本地视频采集及预览

    stopLocalPreview(): void

    startLocalAudio

    开启本地音频的采集和上行

    startLocalAudio(quality: brtc.BrtcAudioQuality): void

    参数

    名称 描述
    quality 声音音质，详见 BrtcAudioQuality

    详情

    • SDK 默认不会采集您的麦克风声音数据，您需要主动调用该函数来开启麦克风采集，并将音频数据传输给房间里的其他用户
    • 请确保您的应用程序已经申请了麦克风权限。可以参考华为开发者中心的 申请应用权限 的介绍来完成权限申请。

    stopLocalAudio

    关闭本地音频的采集和上行

    stopLocalAudio(): void

    详情

    • 调用此方法，会停止传递本地麦克风音频数据给房间里其他用户，并释放对麦克风设备的占用

    muteLocalAudio

    静音/取消静音本地的音频

    muteLocalAudio(mute: boolean): void

    参数

    名称 描述
    mute true：静音；false：取消静音

    详情

    • 当静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, false) 回调通知
    • 当取消静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, true) 回调通知
    • 与 stopLocalAudio 不同之处在于，muteLocalAudio(true) 并不会释放对麦克风设备的占用，只是同步一个状态，服务器将不再下发音频数据给房间里的其它成员

    muteLocalVideo

    暂停/恢复推送本地的视频数据

    muteLocalVideo(streamType: brtc.BrtcVideoStreamType, mute: boolean): void

    参数

    名称 描述
    streamType 流类型，参见 BrtcVideoStreamType
    mute true：暂停；false：恢复

    详情

    该接口可以暂停（或恢复）发布本地的视频画面，暂停之后，同一房间中的其他用户将无法继续看到自己的画面。调用此接口，并不会操作物理摄像头设备，比较适合频繁开关视频的场景。

    注意：如果您还调用了 startScreenCapture 接口启动了屏幕共享，并设置了 streamType 是 BrtcVideoStreamTypeSub，此时摄像头和屏幕共享将会是两个独立的视频流在发布。在这种情况下，调用此接口，只作用于摄像头流。

    • 当暂停推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userid, false) 回调通知
    • 当恢复推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userid, true) 回调通知

    startRemoteView

    开始拉取并显示指定用户的远端画面

    startRemoteView(userId: string, streamType: brtc.BrtcVideoStreamType)

    参数

    名称 描述
    userId 远端用户ID
    streamType 流类型，参见 BrtcVideoStreamType

    详情

    • 与其他端的 SDK 不同，HarmonyOS SDK 不需要您设置渲染视图对象。您只需要遵守命名规则在您的页面上创建 XComponent 控件即可。
    • 您必须在等待来自 SDK 的 onUserVideoAvailable(userId, true) 回调通知后再调用此方法来显示远端用户的视频
    • SDK 支持同时观看某 userid 的大画面和辅路，或者小画面和辅路，但不支持同时观看大画面和小画面
    • 只有当指定的 userid 通过 enableSmallVideoStream() 开启双路编码后，才能观看该用户的小画面
    • 如果该用户的小画面不存在，则默认显示大画面

    stopRemoteView

    停止显示远端视频画面，同时不再拉取该远端用户的视频数据流

    stopRemoteView(userId: string, streamType: brtc.BrtcVideoStreamType)

    参数

    名称 描述
    userId 远端用户ID
    streamType 流类型，参见 BrtcVideoStreamType

    详情

    调用此接口后，SDK 会清理关联到该远端用户的相关视频显示资源

    调用此接口后，无论在手动订阅模式还是自动订阅模式下，都会停止接收该远端用户的视频流。区别是：

    • 在手动订阅模式下，会释放掉该用户视频流相关的全部资源。如果需要再次恢复显示，需要重新发起订阅。
    • 在自动订阅模式下，不需要重新订阅，再次恢复显示，画面显示速度更快。

    muteRemoteAudio

    静音/取消静音指定的远端用户的声音

    muteRemoteAudio(userId: string, mute: boolean): void

    参数

    名称 描述
    userId 远端用户ID
    mute true：静音；false：取消静音

    详情

    • 当您静音某用户的远端音频时，SDK 会停止播放指定用户的声音。
    • 自动订阅模式下，还会继续拉取该远端用户的音频数据。需要恢复播放时速度较快。
    • 手动订阅模式下，会停止拉取该用户的音频数据数据。恢复播放的速度比自动订阅模式下稍慢一些。
    • 在调用了 muteAllRemoteAudio 后，仍然可以调用此方法单独针对某一个当前已订阅的远端用户进行设置

    muteRemoteVideo

    暂停/恢复接收指定的远端视频流

    muteRemoteVideo(userId: string, streamType: brtc.BrtcVideoStreamType, mute: boolean): void

    参数

    名称 描述
    userId 远端用户ID
    streamType 流类型，参见 BrtcVideoStreamType
    mute true：暂停；false：恢复

    详情

    • 该接口仅暂停/恢复接收指定的远端用户的视频流，但并不释放显示资源
    • 手动订阅模式下，如果是首次针对此远端用户调用此方法并设置 mute 为 false，会自动订阅该远端用户的流
    • 当设置 mute 为 true 时：
      • 自动订阅模式下，调用此方法不会停止拉取视频流数据，也不会停止解码
      • 手动订阅模式下，调用此方法，服务器会停止下发视频流数据

    muteAllRemoteAudio

    静音/取消静音所有用户的声音

    muteAllRemoteAudio(mute: boolean): void

    参数

    名称 描述
    mute true：静音；false：取消静音

    详情

    • mute 设置为 true 时，会停止播放所有远端用户的音频流
    • mute 设置为 false 时，会恢复播放所有远端用户的音频流

    注意：当设置 mute 为 false 时，会自动拉取所有远端用户的音频流。因此，在手动订阅模式下，建议谨慎使用此接口。

    setVideoEncoderParam

    设置视频编码器相关参数

    setVideoEncoderParam(encParam: brtc.BrtcVideoEncParam): void

    参数

    名称 描述
    encParam 视频编码参数，详情 BrtcVideoEncParam

    详情

    • 该设置决定了远端用户看到的画面质量（同时也是云端录制出的视频文件的画面质量）

    setVideoEncoderMirror

    设置编码器输出的画面镜像模式

    setVideoEncoderMirror(mirror: boolean): void

    参数

    名称 描述
    mirror true：开启远端画面水平镜像；false：关闭远端画面水平镜像，默认值：false

    详情

    • 该接口不改变本地摄像头的预览画面，但会改变另一端用户看到的（以及服务器录制的）画面效果
    • 即便是在推流过程中，您也可以随时调用此接口来改变编码的镜像效果
    • 该接口只针对于主画面有效。如果当前同时在推流摄像头和屏幕共享流，则只有摄像头会有镜像效果

    setVideoEncoderRotation

    设置视频编码器输出的画面方向

    setVideoEncoderRotation(rotation: brtc.BrtcVideoRotation): void

    参数

    名称 描述
    roation 旋转角度。参见 BrtcVideoRotation

    详情

    该设置不影响本地画面的预览方向，但会影响房间中其他用户所观看到（以及云端录制文件）的画面方向。

    enableSmallVideoStream

    开启大小画面双路编码模式

    enableSmallVideoStream(enable: boolean, encParam: brtc.BrtcVideoEncParam): void

    参数

    名称 描述
    enable true：开启；false：不开启，默认值：false
    encParam 详见 详情 BrtcVideoEncParam

    详情

    • 开启该模式后，当前用户会同时编码输出【高清大画面】和【低清小画面】两个规格的视频画面（但只有一路音频流）
    • 对于开启该模式的当前用户，会占用更多的网络带宽，并且会消耗更多的 CPU 计算资源
    • 对于同一房间的远程观众而言：
      • 如果下行网络很好，或者显示区域较大，可以选择观看【高清大画面】
      • 如果下行网络较差，或者显示区域较小，可以选择观看【低清小画面】

    考虑到同时编码两个规格的视频画面，需要更多的计算资源，在硬件设备较差的系统上请谨慎开启此功能

    setRemoteVideoStreamType

    切换指定远端用户的大小画面

    setRemoteVideoStreamType(userId: string, streamType: brtc.BrtcVideoStreamType)

    参数

    名称 描述
    userId 用于指定要观看的 userId
    streamType 流类型，参见 BrtcVideoStreamType

    详情

    • 只有在远端用户调用 enableSmallVideoStream 提前开启双路编码模式，切换动作才有效果
    • 在不通过此接口进行设置的情况下，默认订阅的视频画面为大画面

    setRenderParams

    设置视频画面的渲染参数

    setRenderParams(userId: string, streamType: brtc.BrtcVideoStreamType, params: brtc.BrtcRenderParams)

    参数

    名称 描述
    userId 本地或远端用户的 userId
    streamType 流类型，参见 BrtcVideoStreamType
    params 渲染参数，详见 BrtcRenderParams

    详情

    可设置的参数包括有：画面的填充模式、旋转角度（待开放）以及镜像模式（待开放）等。

    startScreenCapture

    开始屏幕分享

    startScreenCapture(xComponentSurfaceId:string, streamType: brtc.BrtcVideoStreamType,
    encParam: brtc.BrtcVideoEncParam): void

    参数

    名称 描述
    xComponentSurfaceId （1.0.0 尚不支持）用于回显屏幕共享的 XComponent 控件的 surfaceId。
    streamType 流类型，参见 BrtcVideoStreamType
    encParam 屏幕共享编码参数。参考：BrtcVideoEncParam

    详情

    • 如果设置 streamType 是 BrtcVideoStreamType.BIG，屏幕共享将会替换当前主摄像头流（如有），否则将独立于主摄像头流单独推送一路辅流。

    stopScreenCapture

    停止屏幕采集

    stopScreenCapture(): void

    setConsoleEnabled

    启用或禁用控制台日志打印（在 DevEco Studio 中，控制台可以理解为是 Log 面板）

    setConsoleEnabled(enabled: boolean): void

    参数

    名称 描述
    enabled 指定是否启用，默认为禁止。如果不调用，SDK 默认行为是启用

    setLogLevel

    设置日志输出级别

    setLogLevel(level: brtc.BrtcLogLevel): void

    参数

    名称 描述
    level log级别，详见 BrtcLogLevel

    setLogPath

    设置日志保存路径

    setLogPath(path: string): void

    参数

    名称 描述
    path 日志文件保存路径

    详情

    • 请务必在所有其他接口之前调用此方法来设置，并且保证您指定的目录是存在的，并且您的应用程序拥有对该目录的读写权限，否则可能无法成功记录日志
    • SDK 不会自动清理保存下来的日志，需要您自行完成过期日志的清理工作
    • 单个日志文件的最大尺寸是 10MB，超过的会产生多个日志文件
    {{allComment[version]}} ×
    • 暂无评论
    • {{comment.author}}
      {{ comment.createdAt | date: 'yyyy-MM-dd HH:mm:ss '}}
      {{comment.content}}
    您需要 后才能评论