human: 如何处理七牛云的实时音视频QNRTCClient

gpt: [实时音视频](https://developer.qiniu.com/rtc) > API 文档 > Web >QNRTCClient

#  QNRTCClient

最近更新时间: 2022-07-14 14:46:14

RTC 核心类，包含加入房间，离开房间，订阅、发布 Track，获取统计信息等功能

Hierarchy

  * EventEmitter 
    * QNRTCClient 

Index

Properties

  * userID
  * userData
  * roomName
  * remoteUsers

Event

  * user-joined
  * user-left
  * user-published
  * user-unpublished
  * connection-state-changed
  * message-received
  * user-reconnecting
  * user-reconnected
  * direct-livestreaming-state-changed
  * media-relay-state-changed
  * transcoding-livestreaming-state-changed
  * volume-indicator

Core Methods

  * join
  * leave
  * publish
  * unpublish
  * subscribe
  * unsubscribe
  * setClientMode
  * setClientRole
  * startMediaRelay
  * updateMediaRelay
  * stopMediaRelay
  * sendMessage
  * startDirectLiveStreaming
  * stopDirectLiveStreaming
  * startTranscodingLiveStreaming
  * stopTranscodingLiveStreaming
  * setTranscodingLiveStreamingTracks
  * removeTranscodingLiveStreamingTracks
  * getNetworkQuality
  * getUserNetworkQuality
  * enableAudioVolumeIndicator

Properties

userID

  * string | undefined
  * 本地用户的用户 ID

userData

  * string | undefined
  * 用户自定义数据

roomName

  * string | undefined
  * 当前房间的名称

remoteUsers

  * [QNRemoteUser](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9059/WebQNRemoteUser)[]
  * 房间当前的远端用户列表

Event

user-joined

  * (remoteUserID: string, userData?: string): void
  * 用户加入房间
    
        client.on('user-joined', function(remoteUserID, userData){
        console.log('user-joined', remoteUserID, userData)
    })

Parameters

    * remoteUserID: string 

远端用户 ID

    * Optional userData: string 

用户自定义数据

user-left

  * (remoteUserID: string): void
  * 用户离开房间
    
        client.on('user-left', function(remoteUserID){
        console.log('user-left', remoteUserID)
    })

Parameters

    * remoteUserID: string 

用户 ID

user-published

  * (userID: string, qntrack: ([QNRemoteAudioTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9087/WebQNRemoteAudioTrack) | [QNRemoteVideoTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9060/WebQNRemoteVideoTrack))[]): void
  * 用户添加媒体轨
    
        client.on('user-published', function(userID, qntrack){
        console.log('user-published', userID, qntrack)
    })

Parameters

    * userID: string 

用户 ID

    * qntrack: ([QNRemoteAudioTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9087/WebQNRemoteAudioTrack) | [QNRemoteVideoTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9060/WebQNRemoteVideoTrack))[] 

添加媒体轨信息

user-unpublished

  * (userID: string, qntrack: ([QNRemoteAudioTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9087/WebQNRemoteAudioTrack) | [QNRemoteVideoTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9060/WebQNRemoteVideoTrack))[]): void
  * 用户移除媒体轨
    
        client.on('user-unpublished', function(userID ,qntrack){
        console.log('user-unpublished', userID, qntrack)
    })

Parameters

    * userID: string 

用户 ID

    * qntrack: ([QNRemoteAudioTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9087/WebQNRemoteAudioTrack) | [QNRemoteVideoTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9060/WebQNRemoteVideoTrack))[] 

移除媒体轨信息

connection-state-changed

  * (connectionState: [QNConnectionState](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9080/WebQNConnectionState), info?: [QNConnectionDisconnectedInfo](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9071/WebQNConnectionDisconnectedInfo)): void
  * 连接状态改变
    
        client.on('connection-state-changed',function(connectionState,info){
        console.log('connection-state-changed',connectionState,info)
    })

Parameters

    * connectionState: [QNConnectionState](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9080/WebQNConnectionState)

连接状态

    * Optional info: [QNConnectionDisconnectedInfo](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9071/WebQNConnectionDisconnectedInfo)[] 

连接断开原因

message-received

  * (message: [QNCustomMessage](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9081/WebQNCustomMessage)): void
  * 信息接收
    
        client.on('message-received',function(message){
        console.log('message-received',message)
    })

Parameters

    * message: [QNCustomMessage](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9081/WebQNCustomMessage)

消息信息

user-reconnecting

  * (remoteUserID: string): void
  * 用户重连中
    
        client.on('user-reconnecting', function(remoteUserID){
        console.log('user-reconnecting', remoteUserID)
    })

Parameters

    * remoteUserID: string 

用户 ID

user-reconnected

  * (remoteUserID: string): void
  * 用户重连成功
    
        client.on('user-reconnected', function(remoteUserID) {
        console.log('user-reconnected', remoteUserID)
    })

Parameters

    * remoteUserID: string 

用户信息

direct-livestreaming-state-changed

  * (streamID: string, state: [QNLiveStreamingState](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9045/WebQNLiveStreamingState) ): void
  * CDN 转推状态变化
    
        client.on('direct-livestreaming-state-changed',function(streamID,state){
        console.log('direct-livestreaming-state-changed',streamID,state)
    })

Parameters

    * streamID: string 

转推任务 streamID

    * state: QNLiveStreamingState 

转推状态

media-relay-state-changed

  * (roomName: string, state: [QNMediaRelayState](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11353/QNMediaRelayState-Web)): void
  * 跨房状态变化

Parameters

    * roomName: string 

目标房间名

    * state: [QNMediaRelayState](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11353/QNMediaRelayState-Web)

跨房状态

transcoding-livestreaming-state-changed

  * (streamID: string, state: [QNLiveStreamingState](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9045/WebQNLiveStreamingState) ): void
  * 合流转推状态变化
    
        client.on('transcoding-livestreaming-state-changed',function(streamID,state){
        console.log('transcoding-livestreaming-state-changed',streamID,state)
    })

Parameters

    * streamID: string 

合流任务 streamID

    * state: QNLiveStreamingState 

合流状态

volume-indicator

  * (volumes: [QNVolumeIndicator](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/10265/WebQNVolumeIndicator)): void
  * 房间发声者音量实时监测
    
        client.on('volume-indicator', function(volumes){
        volumes.forEach(volume => { 
            console.log(`volume-indicator：userID ${volume.userID} trackID ${volume.trackID} level ${volume.level}`)
        })
    })

> 音量值 level 范围为 0 - 1，回调返回的为音量值大于 0.1 持续说话的列表。

Parameters

    * volumes: [QNVolumeIndicator](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/10265/WebQNVolumeIndicator)

房间说话者音量回调数据

Core Methods

join

  * join(token: string, userData?: string): Promise<void>
  * 加入房间

接口调用成功后，将会触发 [connection-state-
changed](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/undefined)
房间状态监听事件。

> 建议在加入房间之前，先对房间状态进行监听，根据当前状态处理相关逻辑。

Parameters

    * token: string 

房间 Token

    * Optional userData: string 

用户自定义数据

Returns Promise<void>

leave

  * leave(): Promise<void>
  * 离开房间

Returns Promise<void>

publish

  * publish(tracks: [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack) | [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack)[]): Promise<void>
  * 发布本地 Track

Parameters

    * tracks: [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack) | [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack)[] 

要发布的本地 Track

Returns Promise<void>

unpublish

  * unpublish(tracks: [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack) | [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack)[]): Promise<void>
  * 取消发布本地 Track

Parameters

    * tracks: [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack) | [QNLocalTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9085/WebQNLocalTrack)[] 

要取消发布的本地 Track

Returns Promise<void>

subscribe

  * subscribe(tracks: [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack) | [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack)[]): Promise<{ videoTracks: [QNRemoteVideoTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9060/WebQNRemoteVideoTrack)[]; audioTracks: [QNRemoteAudioTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9087/WebQNRemoteAudioTrack)[]}>
  * 订阅远端 Track

Parameters

    * tracks: [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack) | [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack)[] 

要订阅的远端 Track

Returns Promise<object>

unsubscribe

  * unsubscribe(tracks: [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack) | [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack)[]): Promise<void>
  * 取消订阅远端 Track

Parameters

    * tracks: [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack) | [QNRemoteTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9082/WebQNRemoteTrack)[] 

要取消订阅的远端 Track

Returns Promise<void>

setClientMode

  * setClientMode(mode: [QNClientMode](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11357/QNClientMode-Web)): Promise<void>
  * 设置跨房连麦场景

> 仅可 join room 前调用。

Parameters

    * mode: [QNClientMode](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11357/QNClientMode-Web)

场景

Returns Promise<void>

setClientRole

  * setClientRole(role: [QNClientRole](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11358/QNClientRole-Web)): Promise<void>
  * 设置互动直播场景下的用户角色

该方法在加入频道前后均可调用。

Parameters

    * role: [QNClientRole](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11358/QNClientRole-Web)

角色

Returns Promise<void>

startMediaRelay

  * startMediaRelay(config: [QNMediaRelayConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11355/QNMediaRelayConfig-Web)): Promise<[QNMediaRelayResult](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11356/QNMediaRelayResult-Web)>
  * 开始跨房媒体转推

如果已经开启，则调用失败

当所有目标房间跨房媒体转发都失败，则本次跨房媒体转发请求视为失败，使用跨房媒体转发功能需要再次调用此方法。

当有任意一个目标或多个目标房间媒体转发成功，则本次跨房媒体转发请求视为成功，具体每个房间的状态参考
[QNMediaRelayResult](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11356/QNMediaRelayResult-
Web) 。

> 注意：该方法仅适用于互动直播场景中角色类型为主播的用户。

Parameters

    * config: [QNMediaRelayConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11355/QNMediaRelayConfig-Web)

跨房配置

Returns
Promise<[QNMediaRelayResult](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11356/QNMediaRelayResult-
Web)>

updateMediaRelay

  * updateMediaRelay(config: [QNMediaRelayConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11355/QNMediaRelayConfig-Web)): Promise<[QNMediaRelayResult](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11356/QNMediaRelayResult-Web)>
  * 更新跨房媒体转发

成功开启跨房媒体转发后，如果您希望将流转发到多个目标房间，或退出当前正在转发的房间，可以调用该方法。

此方法为全量更新，正在跨房媒体转发中却未被包含在参数
[QNMediaRelayConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11355/QNMediaRelayConfig-
Web) 中的房间，将停止媒体转发

> 注意：调用此方法前必须确保已经成功开启跨房媒体转发，否则将调用失败；该方法仅适用互动直播场景中角色类型为主播的用户

Parameters

    * config: [QNMediaRelayConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11355/QNMediaRelayConfig-Web)

跨房配置

Returns
Promise<[QNMediaRelayResult](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11356/QNMediaRelayResult-
Web)>

stopMediaRelay

  * stopMediaRelay(): Promise<[QNMediaRelayResult](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11356/QNMediaRelayResult-Web)>
  * 结束跨房

如果未开启，则调用失败。

> 注意：此方法会停止在所有目标房间中的媒体转发；该方法仅适用互动直播场景中角色类型为主播的用户。

Returns
Promise<[QNMediaRelayResult](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/11356/QNMediaRelayResult-
Web)>

sendMessage

  * sendMessage(messageID: string, message: string, users?: [QNRemoteUser](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9059/WebQNRemoteUser)[]): Promise<void>
  * 发送自定义消息

Parameters

    * messageID: string 

自定义消息 ID

    * message: string 

自定义消息内容

    * Optional users: [QNRemoteUser](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9059/WebQNRemoteUser)[] 

默认群发，接收消息用户

传入值若为非数组或空数组，则会采用默认行为进行群发

Returns Promise<void>

startDirectLiveStreaming

  * startDirectLiveStreaming(config: [QNDirectLiveStreamingConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9049/WebQNDirectLiveStreamingConfig)): Promise<void>
  * 开启单路转推

Parameters

    * config: [QNDirectLiveStreamingConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9049/WebQNDirectLiveStreamingConfig)

单路转推配置

Returns Promise<void>

stopDirectLiveStreaming

  * stopDirectLiveStreaming(streamID: string): Promise<void>
  * 停止单路转推

Parameters

    * streamID: string 

转推任务的 streamID

Returns Promise<void>

startTranscodingLiveStreaming

  * startTranscodingLiveStreaming(config: [QNTranscodingLiveStreamingConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9086/WebQNTranscodingLiveStreamingConfig)): Promise<void>
  * 开启合流转推

Parameters

    * config: [QNTranscodingLiveStreamingConfig](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9086/WebQNTranscodingLiveStreamingConfig)

合流转推配置

Returns Promise<void>

stopTranscodingLiveStreaming

  * stopTranscodingLiveStreaming(streamID: string): Promise<void>
  * 停止合流转推

Parameters

    * streamID: string 

转推任务的 streamID

Returns Promise<void>

setTranscodingLiveStreamingTracks

  * setTranscodingLiveStreamingTracks(streamID: string | null, transcodingTracks: [QNTranscodingLiveStreamingTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9065/WebQNTranscodingLiveStreamingTrack)[]): Promise<void>
  * 新增、更新合流转推的布局

Parameters

    * streamID: string | null 

合流任务 streamID

streamID 为 null 时表示设置默认合流任务

    * transcodingTracks: [QNTranscodingLiveStreamingTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9065/WebQNTranscodingLiveStreamingTrack)

待新增、更新的合流转推布局配置

Returns Promise<void>

removeTranscodingLiveStreamingTracks

  * removeTranscodingLiveStreamingTracks(streamID: string | null, transcodingTracks: [QNTranscodingLiveStreamingTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9065/WebQNTranscodingLiveStreamingTrack)[]): Promise<void>
  * 新增、更新合流转推的布局

Parameters

    * streamID: string | null 

合流任务 streamID

streamID 为 null 时表示设置默认合流任务

    * transcodingTracks: [QNTranscodingLiveStreamingTrack](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9065/WebQNTranscodingLiveStreamingTrack)

需要移除的合流转推布局配置

Returns Promise<void>

getNetworkQuality

  * getNetworkQuality(): [QNNetworkQuality](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9058/WebQNNetworkQuality)
  * 获取自己的网络质量等级

Returns
[QNNetworkQuality](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9058/WebQNNetworkQuality)

getUserNetworkQuality

  * getUserNetworkQuality(userID: string): [QNNetworkQuality](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9058/WebQNNetworkQuality)
  * 获取远端用户的网络质量等级

Parameters

    * userID: string 

远端用户的 userID

Returns
[QNNetworkQuality](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9058/WebQNNetworkQuality)

enableAudioVolumeIndicator

  * enableAudioVolumeIndicator(): void
  * 开启房间发声者音量实时检测

> 该方法允许 SDK 定期报告正在说话的用户及其音量。启用音量提示后，无论频道中有没有人说话，SDK 都会定时 2S 触发
> QNRTCClient.on('[volume-
> indicator](https://developer.qiniu.com/rtc/9090/WebQNRTCClient/9090)') 回调

以上内容是否对您有帮助？