文档中心
视频通话 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

React Native API Reference

概览 RtcEngine RtcEngineEvents RtcChannel RtcChannelEvents 警告码 错误码

RtcChannel 类。

Hierarchy

  • RtcChannel

Implements

  • RtcChannelInterface

Index

Methods

Methods

addListener

  • addListener<EventType>(event: EventType, listener: RtcChannelEvents[EventType]): Subscription

  • 设置频道事件句柄。

    设置后，你可以通过 RtcChannelEvents 回调监听对应频道内的事件、获取频道数据。

    Type parameters

    Parameters

    • event: EventType

      事件类型。

    • listener: RtcChannelEvents[EventType]

      RtcChannel 对象的事件回调。

    Returns Subscription

addPublishStreamUrl

  • addPublishStreamUrl(url: string, transcodingEnabled: boolean): Promise<void>

  • 增加旁路推流地址。

    deprecated

    该方法自 3.6.2 版废弃，替代方案请参考发版说明。

    调用该方法后，你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地 触发 RtmpStreamingStateChanged 回调，报告增加旁路推流地址的状态。

    Note

    • 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
    • 请确保在成功加入频道后才能调用该接口。
    • 该方法仅适用直播场景。
    • 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
    • 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

    Parameters

    • url: string

      CDN 推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。url 不支持中文等特殊字符。

    • transcodingEnabled: boolean

      是否转码。如果设为 true，则需要在该方法前 先调用 setLiveTranscoding 方法。

      • true：转码。转码是指在旁路推流时对音视频流进行转码处理后，再推送到其他 CDN 服务器。 多适用于频道内有多个主播，需要进行混流、合图的场景。
      • false：不转码。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 2(InvalidArgument)：参数无效，一般是 URL 为空或是长度为 0 的字符串
      • 7(NotInitialized)：推流时未初始化引擎。

adjustUserPlaybackSignalVolume

  • adjustUserPlaybackSignalVolume(uid: number, volume: number): Promise<void>

  • 调节本地播放的指定远端用户音量。

    你可以多次调用该方法调节不同远端用户在本地播放的音量，或对某个远端用户在本地播放的音量调节多次。

    Note

    • 该方法要在加入频道后调用。
    • 该方法调节的是本地播放的指定远端用户混音后的音量。
    • 该方法每次只能调整一位远端用户在本地播放的音量。若需调整多位远端用户在本地播放的音量，则需多次调用该方法。

    Parameters

    • uid: number

      远端用户的 ID。

    • volume: number

      播放音量，取值范围为 [0,100]。

      • 0：静音。
      • 100：（默认）原始音量。

    Returns Promise<void>

createDataStream

  • createDataStream(reliable: boolean, ordered: boolean): Promise<number>

  • 创建数据流。

    deprecated

    该方法从 v3.3.0 起废弃，请改用 createDataStreamWithConfig。

    该方法用于创建数据流。RtcChannel 生命周期内，每个用户最多只能创建 5 个数据流。

    Note

    请将 reliable 和 ordered 同时设置为 true 或 false，暂不支持交叉设置。

    Parameters

    • reliable: boolean

      设置是否保证接收方在 5 秒内收到数据消息：

      • true：接收方 5 秒内会收到发送方所发送的数据，否则会收到 StreamMessageError 回调并获得相应报错信息。
      • false：接收方不保证收到，就算数据丢失也不会报错。
    • ordered: boolean

      设置接收方是否按发送方发送的顺序接收数据消息：

      • true：接收方会按照发送方发送的顺序收到数据包。
      • false：接收方不保证按照发送方发送的顺序收到数据包。

    Returns Promise<number>

    • 方法调用成功时，返回创建的数据流的 ID。
    • 方法调用失败时，返回错误码。

createDataStreamWithConfig

  • 创建数据流。

    自从 v3.3.1

    该方法用于创建数据流。每个用户在每个频道内最多只能创建 5 个数据流。

    该方法不支持数据可靠，接收方会丢弃超出发送时间 5 秒后的数据包。

    Parameters

    Returns Promise<number>

    • 方法调用成功时，返回创建的数据流的 ID。
    • 方法调用失败时，返回错误码。

destroy

  • destroy(): Promise<void>

  • 销毁当前的 RtcChannel 对象。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 7(NotInitialized)：调用该方法前尚未初始化 RtcChannel 对象。

enableEncryption

  • 开启或关闭内置加密。

    自从 v3.1.2。

    在安全要求较高的场景下，声网建议你在加入频道前，调用 enableEncryption 方法开启内置加密。

    用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

    自 v3.4.5 起，声网推荐使用 AES128GCM2 或 AES256GCM2 加密模式。这两种模式支持设置盐，安全性更高。设置方法详见《媒体流加密》。

    Warning 同一频道内所有用户必须使用相同的加密模式、密钥和盐，否则用户之间无法互通。

    Note

    • 如果开启了内置加密，则不能使用 RTMP/RTMPS 推流功能。
    • 为加强安全性，声网建议每次启用媒体流加密时都更换新的密钥和盐。

    Parameters

    • enabled: boolean

      是否开启内置加密：

      • true: 开启内置加密。
      • false: 关闭内置加密。
    • config: EncryptionConfig

      配置内置加密方案。详见 EncryptionConfig。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 2(InvalidArgument): 参数无效。
      • 4(NotSupported): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
      • 7(NotInitialized): SDK 尚未初始化。需在调用 API 之前已创建 RtcEngine 对象并完成初始化。

enableRemoteSuperResolution

  • enableRemoteSuperResolution(uid: number, enable: boolean): Promise<void>

  • 开启/关闭远端视频超分辨率。(beta 功能）

    自从 v3.5.2

    该功能可以有效地提升本地用户看到的远端视频画面的分辨率。远端用户视频的原始分辨率为 a × b，开启该功能后，本地设备会以 2a × 2b 的分辨率显示该远端视频。

    调用该方法后，SDK 会触发 UserSuperResolutionEnabled 回调报告超分辨率是否成功开启。

    Warning 超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗，只可以对一个远端用户开启超分辨率，并且远端用户视频的原始分辨率不能超过一定范围。 如果本地用户在 Android 系统上应用超分辨率，远端视频原始分辨率不能超过 640 × 360；如果本地用户在 iOS 系统上应用超分辨率，远端视频原始分辨率不能超过 640 × 480。当超出限制时，SDK 会触发 Warning 回调，并返回相应的警告码：

    • SuperResolutionStreamOverLimitation(1610)：远端用户的原始视频分辨率超出了可以应用超分辨率的范围。
    • SuperResolutionUserCountOverLimitation(1611)：已对一个远端用户的视频使用超分辨率。
    • SuperResolutionDeviceNotSupported(1612)：设备不支持使用超分辨率。

    Note 该方法对用户设备具有一定要求，声网推荐你使用如下或更好的设备：

    • Android：
      • VIVO：V1821A，NEX S，1914A，1916A，1962A，1824BA，X60，X60 Pro
      • OPPO：PCCM00，Find X3
      • 一加：A6000
      • 小米：Mi 8，Mi 9，Mi 10，Mi 11，MIX3，Redmi K20 Pro
      • 三星：SM-G9600，SM-G9650，SM-N9600，SM-G9708，SM-G960U，SM-G9750，S20，S21
      • 华为：SEA-AL00，ELE-AL00，VOG-AL00，YAL-AL10，HMA-AL00，EVR-AN00，nova 4，nova 5 Pro，nova 6 5G，nova 7 5G，Mate 30，Mate 30 Pro，Mate 40，Mate 40 Pro，P40，P40 Pro，华为平板 M6，MatePad 10.8
    • iOS（系统版本 12 或之后）：
      • iPhone XR
      • iPhone XS
      • iPhone XS Max
      • iPhone 11
      • iPhone 11 Pro
      • iPhone 11 Pro Max
      • iPhone 12
      • iPhone 12 mini
      • iPhone 12 Pro
      • iPhone 12 Pro Max
      • iPhone 12 SE（第二代）
      • iPad Pro 11-inch（第三代）
      • iPad Pro 12.9-inch（第三代）
      • iPad Air（第三代）
      • iPad Air（第四代）

    Parameters

    • uid: number

      远端用户 ID。

    • enable: boolean

      是否对远端视频开启超分辨率：

      • true: 开启。
      • false: 关闭。

    Returns Promise<void>

getCallId

  • getCallId(): Promise<string>

  • 获取当前的通话 ID。

    Returns Promise<string>

    • 方法调用成功时，则返回当前的通话 ID。
    • 方法调用失败时，则返回空字符串 ""。

getConnectionState

joinChannel

  • joinChannel(token: string | undefined | null, optionalInfo: string | undefined | null, optionalUid: number, options: ChannelMediaOptions): Promise<void>

  • 使用 UID 加入频道。

    Note

    • 该方法不支持相同的用户重复加入同一个频道。
    • 如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。
    • 请确保用于生成 Token 的 App ID 和创建 RtcEngine 对象时用的 App ID 一致。

    相比于 RtcEngine 类下的 joinChannel 方法，该方法支持通过创建多个 RtcChannel 对象， 并调用相应对象的 joinChannel 方法，实现同时加入多个频道。

    用户成功加入频道后，户发布本地音视频流并自动订阅频道内所有其他用户的音视频流。 订阅音视频流会产生用量并影响计费。 如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

    Parameters

    • token: string | undefined | null

      在你的服务器上生成的 Token。详见使用 Token 鉴权。

    • optionalInfo: string | undefined | null

      开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。

    • optionalUid: number

      用户 ID，32 位无符号整数。建议设置范围：1 到 (232-1)，并保证唯一性。 如果不指定（即设为 0），SDK 会自动分配一个， 并在 JoinChannelSuccess 回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。

    • options: ChannelMediaOptions

      频道媒体设置选项。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 2(InvalidArgument): 参数无效。
      • 3(NotReady): SDK 初始化失败，请尝试重新初始化 SDK。
      • 5(Refused): 调用被拒绝。可能有如下两个原因：
        • 已经创建了一个同名的 RtcChannel 频道。
        • 已经通过 RtcChannel 加入了一个频道，并在该 RtcChannel 频道中发布了音视频流。
      • 7(NotInitialized): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 RtcEngine 对象并完成初始化。
      • 17(JoinChannelRejected)：加入频道被拒绝。由于 SDK 不支持用户重复加入同一个 RtcChannel 频道，当已经加入某个 RtcChannel 频道的用户再次调用该 RtcChannel 对象的加入频道方法时，会返回此错误码。

joinChannelWithUserAccount

  • joinChannelWithUserAccount(token: string | undefined | null, userAccount: string, options: ChannelMediaOptions): Promise<void>

  • 使用 User Account 加入频道。

    Note

    • 该方法不支持相同的用户重复加入同一个频道。
    • 如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 User Account 是不同的。
    • 请确保用于生成 Token 的 App ID 和创建 RtcEngine 对象时用的 App ID 一致。
    • 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID，了解使用限制及实现方法。

    用户成功加入（切换）频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

    Parameters

    • token: string | undefined | null

      在你的服务器上生成的 Token。详见使用 Token 鉴权。

    • userAccount: string

      用户 User Account。该参数为必需，最大不超过 255 字节，不可为 null。请确保加入频道的 User Account 的唯一性。 以下为支持的字符集范围（共 89 个字符）：

      • 26 个小写英文字母 a-z
      • 26 个大写英文字母 A-Z
      • 10 个数字 0-9
      • 空格
      • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
    • options: ChannelMediaOptions

      频道媒体设置选项。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 2(InvalidArgument): 参数无效。
      • 3(NotReady): SDK 初始化失败，请尝试重新初始化 SDK。
      • 5(Refused): 调用被拒绝。
      • 17(JoinChannelRejected)：加入频道被拒绝。由于 SDK 不支持用户重复加入同一个 RtcChannel 频道，当已经加入 某个 RtcChannel 频道的用户再次调用该 RtcChannel 对象的加入频道方法时，会返回此错误码。

leaveChannel

  • leaveChannel(): Promise<void>

  • 离开当前频道。

    成功调用该方法离开频道后，会触发如下回调：

    • 本地：LeaveChannel
    • 远端：通信场景下的用户和直播场景下的主播离开频道后， 触发 UserOffline。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 1(Failed): 一般性的错误（未明确归类）。
      • 2(InvalidArgument): 参数无效。
      • 7(NotInitialized): SDK 尚未初始化。

muteAllRemoteAudioStreams

  • muteAllRemoteAudioStreams(muted: boolean): Promise<void>

  • 停止/恢复接收所有音频流。

    成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流，包括在调用该方法后加入频道的用户的音频流。

    Note

    • 该方法需要在加入频道后调用。
    • 自 v3.3.1 起，该方法包含了 setDefaultMuteAllRemoteAudioStreams 的功能。 声网建议不要一起调用 muteAllRemoteAudioStreams 和 setDefaultMuteAllRemoteVideoStreams，否则设置可能会不生效。详见《设置订阅状态》。

    Parameters

    • muted: boolean

      设置是否停止接收所有远端音频流：

      • true：停止接收所有远端音频流。
      • false：继续接收所有远端音频流（默认）。

    Returns Promise<void>

muteAllRemoteVideoStreams

  • muteAllRemoteVideoStreams(muted: boolean): Promise<void>

  • 停止/恢复接收所有视频流。

    成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的视频流，包括在调用该方法后加入频道的用户的视频流。

    Note

    • 该方法需要在加入频道后调用。
    • 自 v3.3.1 起，该方法包含了 setDefaultMuteAllRemoteVideoStreams 的功能。 声网建议不要一起调用 muteAllRemoteVideoStreams 和 setDefaultMuteAllRemoteVideoStreams，否则设置可能会不生效。详见《设置订阅状态》。

    Parameters

    • muted: boolean

      设置是否停止/恢复接收所有视频流：

      • true：停止接收所有远端视频流。
      • false：（默认）继续接收所有远端视频流。

    Returns Promise<void>

muteLocalAudioStream

  • muteLocalAudioStream(muted: boolean): Promise<void>

  • 取消或恢复发布本地音频流。

    自从 v3.4.5

    该方法仅设置用户在 RtcChannel 频道中的音频发布状态。

    成功调用该方法后，远端会触发 RemoteAudioStateChanged 回调。

    同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中调用 muteLocalAudioStream(false) 否则方法会调用失败并返回 -5 (ERR_REFUSED)。

    Note

    • 该方法不会改变音频采集设备的使用状态。
    • 该方法的调用是否生效受 joinChannel 和 setClientRole 方法的影响，详见《设置发布状态》。

    Parameters

    • muted: boolean

      是否取消发布本地音频流：

      • true：取消发布。
      • false：发布。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • -5 (ERR_REFUSED)：调用被拒绝。

muteLocalVideoStream

  • muteLocalVideoStream(muted: boolean): Promise<void>

  • 取消或恢复发布本地视频流。

    自从 v3.4.5

    该方法仅设置用户在 RtcChannel 频道中的视频发布状态。

    成功调用该方法后，远端会触发 RemoteVideoStateChanged 回调。

    同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中 调用 muteLocalVideoStream(false)，否则方法会调用失败并返回 -5 (ERR_REFUSED)。

    Note

    • 该方法不会改变视频采集设备的使用状态。
    • 该方法的调用是否生效受 joinChannel 和 setClientRole 方法的影响，详见《设置发布状态》。

    Parameters

    • muted: boolean

      是否取消发布本地视频流：

      • true：取消发布。
      • false：发布。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • -5 (ERR_REFUSED)：调用被拒绝。

muteRemoteAudioStream

  • muteRemoteAudioStream(uid: number, muted: boolean): Promise<void>

  • 停止/恢复接收指定音频流。

    Parameters

    • uid: number

      指定的用户 ID。

    • muted: boolean

      设置是否停止/恢复接收指定音频流：

      • true：停止接收指定用户的音频流。
      • false：（默认）继续接收指定用户的音频流。

    Returns Promise<void>

muteRemoteVideoStream

  • muteRemoteVideoStream(uid: number, muted: boolean): Promise<void>

  • 停止/恢复接收指定视频流。

    Parameters

    • uid: number

      指定的用户 ID。

    • muted: boolean

      设置是否停止/恢复接收指定视频流：

      • true：停止接收指定用户的视频流。
      • false：（默认）继续接收指定用户的视频流。

    Returns Promise<void>

pauseAllChannelMediaRelay

  • pauseAllChannelMediaRelay(): Promise<void>

  • 暂停向所有目标频道转发媒体流。

    自从 v3.5.2

    开始跨频道转发媒体流后，如果你需要暂停向所有频道转发媒体流，可以调用该方法； 暂停后，如果要恢复跨频道媒体流转发，可以调用 resumeAllChannelMediaRelay 方法。

    成功调用该方法后，SDK 会触发 ChannelMediaRelayEvent 回调，并在回调中报告是否成功暂停媒体流转发。

    Note 该方法需要在 startChannelMediaRelay 后调用。

    Returns Promise<void>

publish

  • publish(): Promise<void>

  • 将本地音视频流发布到本频道。

    deprecated

    该方法自 v3.4.5 起废弃，请改用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。

    该方法的调用需满足以下要求，否则 SDK 会返回 Refused(-5)：

    • 该方法仅支持将音视频流发布到当前 RtcChannel 类所对应的频道。
    • 直播场景下，该方法仅适用于角色为主播的用户。你可以调用该 RtcChannel 类 下的 setClientRole 方法设置用户角色。
    • SDK 只支持用户同一时间在一个频道发布一路音视频流。详情请参考高阶指南《多频道管理》。

    Returns Promise<void>

registerMediaMetadataObserver

  • registerMediaMetadataObserver(): Promise<void>

  • 注册媒体 Metadata 观测器。

    该接口通过在直播的视频帧中同步添加 Metadata，实现发送商品链接、分发优惠券、发送答题等功能，构建更为丰富的直播互动方式。

    Note

    • 请在调用 joinChannel 加入频道前调用该方法。
    • 该方法仅适用于直播场景。

    Returns Promise<void>

removeAllListeners

  • removeAllListeners<EventType>(event?: EventType): void

  • 删除所有的频道事件句柄。

    Type parameters

    Parameters

    Returns void

removeListener

  • removeListener<EventType>(event: EventType, listener: RtcChannelEvents[EventType], subscription?: EmitterSubscription): void

  • 删除指定的频道事件句柄。

    该方法删除指定的回调句柄。对于某些注册的回调句柄， 如果你在收到相应回调事件后无需再次接收回调消息，可以调用该方法移除回调句柄。

    Type parameters

    Parameters

    • event: EventType

      事件类型。

    • listener: RtcChannelEvents[EventType]

      RtcChannel 对象的事件回调。

    • Optional subscription: EmitterSubscription

    Returns void

removePublishStreamUrl

  • removePublishStreamUrl(url: string): Promise<void>

  • 删除旁路推流地址。

    deprecated

    该方法自 3.6.2 版废弃，替代方案请参考发版说明。

    调用该方法后，SDK 会在本地 触发 RtmpStreamingStateChanged 回调， 报告删除旁路推流地址的状态。

    Note

    • 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
    • 该方法只适用于直播场景。
    • 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。

    Parameters

    • url: string

      待删除的推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。

    Returns Promise<void>

renewToken

  • renewToken(token: string): Promise<void>

  • 更新 Token。

    在如下情况下，SDK 判定当前的 Token 已过期：

    你应该在服务端重新获取 token，然后调用该方法更新 Token，否则 SDK 无法和服务器建立连接。

    Parameters

    • token: string

      新的 Token。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 1(Failed): 一般性的错误（未明确归类）。
      • 2(InvalidArgument): 参数无效。
      • 7(NotInitialized): SDK 尚未初始化。

resumeAllChannelMediaRelay

  • resumeAllChannelMediaRelay(): Promise<void>

  • 恢复向所有目标频道转发媒体流。

    自从 v3.5.2

    调用 pauseAllChannelMediaRelay 方法后，如果你需要恢复向所有目标频道转发媒体流，可以调用该方法。

    成功调用该方法后，SDK 会触发 ChannelMediaRelayEvent 回调，并在回调中报告是否成功恢复媒体流转发。

    Note 该方法需要在 pauseAllChannelMediaRelay 后调用。

    Returns Promise<void>

sendMetadata

  • sendMetadata(metadata: string): Promise<void>

  • 发送 metadata。

    Parameters

    • metadata: string

      需要发送的 metadata。

      Note 请确保在该方法中传入的 Metadata 大小不超过 setMaxMetadataSize 中设定的值。

    Returns Promise<void>

sendStreamMessage

  • sendStreamMessage(streamId: number, message: string): Promise<void>

  • 发送数据流。

    该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：

    • 频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。
    • 每个客户端每秒最多能发送 6 KB 数据。
    • 频道内每人最多能同时有 5 个数据通道。

    成功调用该方法后，远端会触发 StreamMessage 回调，远端用户可以在该回调中获取接收到的流消息； 若调用失败，远端会触发 StreamMessageError 回调。

    Parameters

    • streamId: number

      createDataStream 方法返回的数据流 ID。

    • message: string

      待发送的数据，格式为 byte[]。

    Returns Promise<void>

setAVSyncSource

  • setAVSyncSource(channelId: string, uid: number): Promise<void>

  • 设置发流端音画同步。

    since

    v3.6.2

    同一用户可能使用两个设备分别发送音频流和视频流，为保证接收端听到和看到的音频和视频的时间同步性， 你可以在视频发送端调用该方法，并传入音频发送端的频道名、用户 ID。SDK 会以发送的音频流的时间戳为基准进行自动调节 发送的视频流，以保证即使在两个发送端的上行网络情况不一致（如分别使用 Wi-Fi 和 4G 网络）的情况下， 也能让接收到的音视频具有时间同步性。

    Note 声网推荐你在加入频道前调用该方法。

    Parameters

    • channelId: string

      标识音频发送端所在频道的频道名。

    • uid: number

      音频发送端的用户 ID。

    Returns Promise<void>

setClientRole

  • 设置直播场景下的用户角色。

    直播场景下，SDK 会默认设置用户角色为观众，你可以调用 setClientRole 设置用户角色为主播。

    该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：

    Note

    • 该方法仅适用于直播场景（setChannelProfile 中 profile 设为 LiveBroadcasting）。
    • 自 3.2.0 版本起，该方法新增 options 参数，支持设置用户级别。
      • 用户角色 (role) 确定用户在 SDK 层的权限，包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。
      • 用户级别 (level) 需要与角色结合使用，确定用户在其权限范围内，可以操作和享受到的服务级别。例如对于观众，选择接收低延时还是超低延时的视频流。用户级别会影响计费。

    Parameters

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 1(Failed): 一般性的错误（未明确归类）。
      • 2(InvalidArgument): 参数无效。
      • 5(Refused): 调用被拒绝。在多频道场景中，如果你已在一个频道中进行如下设置，则用户在另一个频道内切换角色为主播时会返回该错误码：
        • 调用带 options 参数的 joinChannel，并使用默认设置 publishLocalAudio = true 或 publishLocalVideo = true。
        • 调用 setClientRole，并设置用户角色为主播。
        • 调用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。
      • 7(NotInitialized): SDK 尚未初始化。

setDefaultMuteAllRemoteAudioStreams

  • setDefaultMuteAllRemoteAudioStreams(muted: boolean): Promise<void>

  • 设置是否默认接收音频流。

    deprecated

    该方法自 v3.3.0 起废弃。

    默认取消或恢复订阅远端用户的音频流。

    该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

    Note 取消订阅音频流后，如果需要恢复订阅频道内的远端，可以进行如下操作：

    • 如果需要恢复订阅单个用户的音频流，调用 muteRemoteAudioStream(false)，并指定你想要订阅的远端用户 ID。
    • 如果想恢复订阅多个用户的音频流，则需要多次调用 muteRemoteAudioStream(false)。

    Parameters

    • muted: boolean

      是否默认取消订阅远端用户的音频流：

      • true：默认取消订阅。
      • false：（默认）默认订阅。

    Returns Promise<void>

setDefaultMuteAllRemoteVideoStreams

  • setDefaultMuteAllRemoteVideoStreams(muted: boolean): Promise<void>

  • 设置是否默认接收视频流。

    deprecated

    该方法自 v3.3.0 起废弃。

    默认取消或恢复订阅远端用户的视频流。

    该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

    Note 取消订阅视频流后，如果需要恢复订阅频道内的远端，可以进行如下操作：

    • 如果需要恢复订阅单个用户的视频流，调用 muteRemoteVideoStream(false)，并指定你想要订阅的远端用户 ID。
    • 如果想恢复订阅多个用户的视频流，则需要多次调用 muteRemoteVideoStream(false)。

    Parameters

    • muted: boolean

      是否默认取消订阅远端用户的视频流：

      • true：默认取消订阅。
      • false：（默认）默认订阅。

    Returns Promise<void>

setEncryptionMode

  • 设置内置的加密方案。

    deprecated

    自 v3.1.2 起废弃。请改用 enableEncryption。

    声网 SDK 支持内置加密功能，默认使用 AES128XTS 加密方式。如需使用其他加密方式，可以调用该 API 设置。

    同一频道内的所有用户必须设置相同的加密方式和密码才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

    Note

    • 请勿在转码推流场景中使用该方法。
    • 该方法需要在 setEncryptionSecret 之后调用。

    Parameters

    Returns Promise<void>

setEncryptionSecret

  • setEncryptionSecret(secret: string): Promise<void>

  • 启用内置加密，并设置数据加密密码。

    deprecated

    自 v3.1.2 起废弃。请改用 enableEncryption。

    如果需要启用加密，请在加入频道前调用该方法启用内置加密功能，并设置加密密码。

    同一频道内的所有用户应设置相同的密码。 当用户离开频道时，该频道的密码会自动清除。 如果未指定密码或将密码设置为空，则无法激活加密功能。

    Note

    • 为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。 16 字节是 AES 通用加密模式下最大填充块大小。
    • 请勿在转码推流场景中使用该方法。

    Parameters

    • secret: string

      加密密码。

    Returns Promise<void>

setLiveTranscoding

  • 设置直播转码。

    deprecated

    该方法自 3.6.2 版废弃，替代方案请参考发版说明。

    该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码参数 LiveTranscoding 时， SDK 会触发 TranscodingUpdated 回调。

    首次调用该方法设置转码参数时，不会触发 TranscodingUpdated 回调。

    Note

    • 请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
    • 该方法仅适用于直播场景下的主播用户。
    • 请确保先调用过该方法，再调用 addPublishStreamUrl。
    • 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

    Parameters

    Returns Promise<void>

setMaxMetadataSize

  • setMaxMetadataSize(size: number): Promise<void>

  • 设置 Metadata 的最大数据大小。

    Parameters

    • size: number

      Metadata 的最大数据大小，单位为 Byte，最大值不超过 1024。

    Returns Promise<void>

setRemoteDefaultVideoStreamType

  • setRemoteDefaultVideoStreamType(streamType: VideoStreamType): Promise<void>

  • 设置默认订阅的视频流类型。

    Note

    • 该方法只能在加入频道前调用。声网不支持你在加入频道后修改默认订阅的视频流类型。
    • 如果你既调用了该方法，也调用了 setRemoteVideoStreamType，则 SDK 以 setRemoteVideoStreamType 中的设置为准。

    Parameters

    Returns Promise<void>

setRemoteUserPriority

  • setRemoteUserPriority(uid: number, userPriority: UserPriority): Promise<void>

  • 设置用户媒体流优先级。

    该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。 如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。

    Note

    声网 SDK 仅允许将一名远端用户设为高优先级。

    Parameters

    • uid: number

      远端用户的 ID。

    • userPriority: UserPriority

      远端用户的需求优先级。

    Returns Promise<void>

setRemoteVideoStreamType

  • setRemoteVideoStreamType(uid: number, streamType: VideoStreamType): Promise<void>

  • 设置订阅的视频流类型。

    在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode 关闭双流模式， 接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流，小流则是低分辨率低码率的视频流。

    正常情况下，用户默认接收大流。如需节约带宽和计算资源，则可以调用该方法动态调整对应远端视频流的大小。 SDK 会根据该方法中的设置，切换大小流。

    视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

    Note 该方法在加入频道前后都能调用。如果既调用了 setRemoteVideoStreamType，也调用了 setRemoteDefaultVideoStreamType， 则 SDK 以 setRemoteVideoStreamType 中的设置为准。

    Parameters

    • uid: number

      远端用户的 ID。

    • streamType: VideoStreamType

      设置视频流大小类型。

    Returns Promise<void>

setRemoteVoicePosition

  • setRemoteVoicePosition(uid: number, pan: number, gain: number): Promise<void>

  • 设置远端用户声音的空间位置和音量，方便本地用户听声辨位。

    用户通过调用该接口，设置远端用户声音出现的位置，左右声道的声音差异会让用户产生声音的方位感， 从而判断出远端用户的实时位置。 在多人在线游戏场景，如吃鸡游戏中，该方法能有效增加游戏角色的方位感，模拟真实场景。

    Note

    • 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
    • 为获得最佳听觉体验，我们建议用户佩戴耳机。

    Parameters

    • uid: number

      远端用户的 ID。

    • pan: number

      设置远端用户声音出现的位置，取值范围为 [-1.0,1.0]：

      • 0.0：（默认）声音出现在正前方。
      • -1.0：声音出现在左边。
      • 1.0：声音出现在右边。
    • gain: number

      设置远端用户声音的音量，取值范围为 [0.0,100.0]，默认值为 100.0， 表示该用户的原始音量。取值越小，则音量越低。

    Returns Promise<void>

startChannelMediaRelay

startRtmpStreamWithTranscoding

  • startRtmpStreamWithTranscoding(url: string, transcoding: LiveTranscoding): Promise<void>

  • 开始 CDN 直播推流并设置转码属性。

    since

    v3.6.2

    调用该方法，你可以向指定的 CDN 推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流，如果你需要向多个地址转码推流，则需多次调用该方法。

    调用该方法后，SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告推流的状态。

    Note

    • 请确保已开通 CDN 推流服务，详见进阶功能旁路推流中的前提条件。
    • 请在加入频道后调用该方法。
    • 只有直播场景下的主播才能调用该方法。
    • 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 `stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。

    Parameters

    • url: string

      CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

    • transcoding: LiveTranscoding

      CDN 直播推流的转码属性，详见 LiveTranscoding。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 2(InvalidArgument)：url 为空或为长度为 0 的字符串。
      • 7(NotInitialized)：调用该方法前，未初始化 SDK。

startRtmpStreamWithoutTranscoding

  • startRtmpStreamWithoutTranscoding(url: string): Promise<void>

  • 开始非转码推流。

    since

    v3.6.2

    调用该方法，你可以向指定的 CDN 推流地址推送直播音视频流。 该方法每次只能向一个地址推送媒体流，如果你需要向多个地址推流，则需多次调用该方法。

    调用该方法后，SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告推流的状态。

    Note

    • 请确保已开通 CDN 推流服务，详见进阶功能旁路推流中的前提条件。
    • 请在加入频道后调用该方法。
    • 只有直播场景下的主播才能调用该方法。
    • 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 `stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。

    Parameters

    • url: string

      CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

    Returns Promise<void>

    • 方法调用成功时，无返回值。
    • 方法调用失败时，返回错误码。可能的错误包括：
      • 2(InvalidArgument)：url 为空或为长度为 0 的字符串。
      • 7(NotInitialized)：调用该方法前，未初始化 SDK。

stopChannelMediaRelay

  • stopChannelMediaRelay(): Promise<void>

stopRtmpStream

  • stopRtmpStream(url: string): Promise<void>

  • 结束 CDN 直播推流。

    since

    v3.6.2

    调用该方法，你可以结束指定的 CDN 推流地址上的直播。该方法每次只能结束一个推流地址上的直播。 如果你需要结束多个推流地址的直播，则需多次调用该方法。

    调用该方法后，SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告推流的状态。

    Parameters

    • url: string

      CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

    Returns Promise<void>

unpublish

  • unpublish(): Promise<void>

  • 停止将本地音视频流发布到本频道。

    deprecated

    该方法自 v3.4.5 起废弃，请改用 muteLocalAudioStream(true) 或 muteLocalVideoStream(true)。

    请确保你想要停止发布音视频流的频道 channelId，与当前正在 publish 音视频流的频道 channelId 一致， 否则 SDK 会返回 Refused(-5)。

    Returns Promise<void>

unregisterMediaMetadataObserver

  • unregisterMediaMetadataObserver(): Promise<void>

  • 注销媒体 Metadata 观测器。

    Returns Promise<void>

updateChannelMediaRelay

  • 更新媒体流转发的频道。

    成功开始跨频道转发媒体流后，如果你希望将流转发到多个目标频道，或退出当前的转发频道，可以调用该方法。

    成功调用该方法后，SDK 会触发 ChannelMediaRelayEvent 回调， 并在回调中报告状态码 UpdateDestinationChannel(7)。

    Note

    • 请在 startChannelMediaRelay 方法后调用该方法， 更新媒体流转发的频道。
    • 跨频道媒体流转发最多支持 4 个目标频道。

    Parameters

    Returns Promise<void>

updateRtmpTranscoding

  • 更新转码属性。

    since

    v3.6.2

    开启转码推流后，你可以根据场景需求，动态更新转码属性。转码属性更新后，SDK 会触发 TranscodingUpdated 回调。

    Parameters

    Returns Promise<void>

Static create

  • 创建并返回 RtcChannel 对象。

    你可以多次调用该方法，创建多个 RtcChannel 对象，再调用各 RtcChannel 对象中的 joinChannel 方法，实现同时加入多个频道。

    加入多个频道后，你可以同时订阅各个频道的音、视频流；但是同一时间只能在一个频道发布一路音、视频流。

    Parameters

    • channelId: string

      标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）：

      • 26 个小写英文字母 a-z
      • 26 个大写英文字母 A-Z
      • 10 个数字 0-9
      • 空格
      • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","

      Note

      • 该参数没有默认值，请确保对参数设值。
      • 请勿将该参数设为空字符 ""，否则 SDK 会返回 Refused(-5)。

    Returns Promise<RtcChannel>

    • 方法调用成功，返回 RtcChannel 对象。
    • 方法调用失败，返回 null。
    • 如果将 channelId 设为空字符 ""，则返回错误码 Refused(-5)。

Static destroyAll

  • destroyAll(): void

  • 销毁所有的 RtcChannel 对象。

    Returns void