Agora Cocos Creator js SDK 包含如下 API:

初始化 Agora agora.init(appid)

Param Type Description
appid String Agora App ID

Examples:

require("js-agora");
agora.init("AGORA APP ID");

初始化 Agora
注意: 在整个应用全局,开发者只需要对引擎做一次初始化。另外引擎的异步调用的回调,如:加入频道成功、退出频道成功等消息,都在同一个对象里。

Agora 音频实时云传输服务,不区分调试环境和正式环境。

设置频道属性 agora.setChannelProfile(profile)

Param Type Description
profile Number
  • 0 : 通信模式(默认)
  • 1 : 直播模式
  • Examples:

    agora.setChannelProfile(0)

    该方法用于设置频道模式(Profile)。引擎需知道应用程序的使用场景(例如通信模式或直播模式), 从而使用不同的优化手段。

    参数只可使用枚举类型对应的整型值。其它 API 类同。

    目前 Agora Native SDK 支持以下几种模式:

    模式 描述
    通信 通信为默认模式,用于常见的一对一或群聊,频道中的任何用户可以自由说话
    直播 直播模式有主播和观众两种用户角色,可以通过调用 setClientRole 设置。主播可收发语音和视频,但观众只能收,不能发
    游戏语音 频道内任何用户可自由发言。该模式下默认使用低功耗低码率的编解码器
    • 同一频道内只能同时设置一种模式。
    • 不同的频道模式必须使用不同的 App ID。
    • 该方法必须在加入频道前调用和进行设置,进入频道后无法再设置。

    设置用户角色 agora.setClientRole(role)

    agora.setClientRole(2);
    Param Type Description
    role Number
  • 1 : 主播
  • 2 : 观众(默认)
  • 直播模式下,在加入频道前,用户需要通过本方法设置观众(默认)或主播模式;在加入频道后,用户可以通过本方法切换用户模式。

    加入频道 agora.joinChannel(token, channelId, [info], [uid])

    agora.joinChannel("", "CHANNEL_ID");
    Param Type Description
    token String
  • 安全要求不高:将值设置为空字符串
  • 安全要求高: 将值设置为 Token 值。 如果你已经启用了 App 证书, 请务必使用 Token。 关于如何获取 Token,详见密钥说明
  • channelId String 标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符): a-z,A-Z,0-9,space,! #$%&,()+, -,:;<=.#$%&,()+,-,:;<=.,>?@[],^_,{
    [info] String (非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串,或频道相关信息。该信息不会传递给频道内的其他用户
    [uid] number (非必选项) 用户 ID,32 位无符号整数。建议设置范围:1 到 (232-1),并保证唯一性。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调方法中返回,App 层必须记住该返回值并维护,SDK 不对该返回值进行维护,uid 在 SDK 内部用 32 位无符号整数表示,由于 Java 不支持无符号整数,uid 被当成 32 位有符号整数处理,对于过大的整数,Java 会表示为负数,如有需要可以用(uid&0xffffffffL)转换成 64 位整数

    该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的应用程序是不能互通的。如果已在通话中,用户必须调用 agora.leaveChannel() 退出当前通话,才能进入下一个频道。

    同一个频道里不能出现两个相同的 UID。如果你的 App 支持多设备同时登录,即同一个用户账号可以在不同的设备上同时登录(例如微信支持在 PC 端和移动端同时登录),请保证传入的 UID 不相同。 例如你之前都是用同一个用户标识作为 UID, 建议从现在开始加上设备 ID, 以保证传入的 UID 不相同 。如果你的 App 不支持多设备同时登录,例如在电脑上登录时,手机上会自动退出,这种情况下就不需要在 UID 上添加设备 ID。

    离开频道 agora.leaveChannel()

    agora.leaveChannel();

    离开频道,即挂断或退出通话。
    joinChannel 后,必须调用 leaveChannel 以结束通话,否则不能进行下一次通话。不管当前是否在通话中,都可以调用 leaveChannel,没有副作用。如果成功,则返回值为 0。leaveChannel 会把会话相关的所有资源释放掉。

    leaveChannel 是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。

    打开音频 agora.enableAudio()

    agora.enableAudio();

    该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。

    关闭音频 agora.disableAudio()

    agora.disableAudio();

    该方法设置内部引擎为禁用状态,在 leaveChannel 后仍然有效。

    将自己静音 agora.muteLocalAudioStream(mute)

    agora.muteLocalAudioStream(true);
    Param Type Description
    mute Boolean
  • true: 麦克风静音
  • false: 取消麦克风静音
  • 静音/取消静音。该方法用于允许/禁止往网络发送本地音频流。

    关闭/重启本地语音功能 agora.enableLocalAudio(enabled)

    agora.enableLocalAudio(true);
    Param Type Description
    enabled Boolean
  • true:重新开启本地语音功能,即开启本地语音采集或处理
  • false:关闭本地语音功能,即停止本地语音采集或处理
  • 当用户加入频道时,语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能,停止或重新开始本地音频采集及处理。
    该方法不影响接收或播放远端音频流,适用于只听不发的用户场景。

    • 该方法需要在 joinChannel 之后调用才能生效。
    • 该方法与 muteLocalAudioStream 的区别在于:
      • enableLocalAudio:开启或关闭本地语音采集及处理
      • muteLocalAudioStream:停止或继续发送本地音频流

    静音所有远端音频 agora.muteAllRemoteAudioStreams(mute)

    Param Type Description
    mute Boolean
  • True: 停止接收和播放所有远端音频流
  • False: 允许接收和播放所有远端音频流
  • 该方法用于允许/禁止播放远端用户的音频流,即对所有远端用户进行静音与否。

    静音指定用户音频 agora.muteRemoteAudioStream(uid, mute)

    agora.muteRemoteAudioStream("UID", true);
    Param Type Description
    uid String 指定用户 ID
    mute Boolean
  • true: 停止接收和播放指定音频流
  • talse: 允许接收和播放指定音频流
  • 静音指定远端用户/对指定远端用户取消静音。

    如果之前有调用过 muteAllRemoteAudioStreams (true) 对所有远端音频进行静音,在调用本 API 之前请确保你已调用 muteAllRemoteAudioStreams (false) 。 muteAllRemoteAudioStreams 是全局控制,muteRemoteAudioStream 是精细控制。

    启用说话者音量提示 agora.enableAudioVolumeIndication(interval, smooth)

    agora.enableAudioVolumeIndication(1000, 3)
    Param Type Description
    interval Number 指定音量提示的时间间隔
  • <= 0:禁用音量提示功能
  • > 0:返回音量提示的间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调
  • smooth Number 平滑系数,指定音量提示的灵敏度。取值范围为 [0-10],建议值为 3,数字越大,波动越灵敏;数字越小,波动越平滑。

    该方法允许 SDK 定期向应用程序反馈当前谁在说话以及说话者的音量。启用该方法后,无论频道内是否有人说话,都会在 onAudioVolumeIndication 回调中按设置的间隔时间返回音量提示。

    agora.adjustRecordingSignalVolume(volume)

    调节录音信号音量

    Param Type Description
    volume Number 录音信号音量可在 0 ~ 400 范围内进行调节

    调节播放信号音量 agora.adjustPlaybackSignalVolume(volume)

    agora.adjustPlaybackSignalVolume(100)
    Param Type Description
    volume Number 录音信号音量可在 0~400 范围内进行调节:
  • 0: 静音
  • 100: 原始音量
  • 400: 最大可为原始音量的 4 倍(自带溢出保护)
  • 该方法调节录音信号音量。

    修改默认的语音路由 agora.setDefaultAudioRouteToSpeakerphone(bVal)

    agora.setDefaultAudioRouteToSpeakerphone(true)
    Param Type Description
    bVal Boolean
  • true: 默认路由改为外放(扬声器)
  • false: 默认路由改为听筒
    无论语音是从外放还是听筒出声,如果插上耳机或连接蓝牙,语音路由会发生相应改变。拔出耳机或断开蓝牙后语音路由将恢复成默认路由。
    • 该方法只在纯音频模式下工作,在有视频的模式下不工作。
    • 该方法需要在 joinChannel 前设置,否则不生效。

    如有必要,调用该方法修改默认的语音路由。默认的语音路由如下:

    频道模式 默认语音路由
    通信
  • 语音通话: 听筒
  • 视频通话: 外放
  • 视频通话中关闭视频 : 听筒
  • 直播 外放
    游戏语音 外放

    已调用 disableVideo 或 已调用 muteLocalVideoStreammuteAllRemoteVideoStreams

    自定义参数 agora.setParameters(profile)

    agora.setParameters('{"key": "value"}');
    Param Type Description
    profile String/code> JSON 字符串形式的参数

    通过 JSON 配置 SDK 提供技术预览或特别定制功能。

    JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。

    查询 SDK 版本号 agora.getVersion()

    agora.getVersion();


    该方法返回 SDK 版本号的字符串。

    设置日志文件 agora.setLogFile(filePath)

    agora.setLogFile(filePath);
    Param Type Description
    filePath String 日志文件的完整路径。该日志文件为 UTF-8 编码。

    设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。应用程序必须保证指定的目录存在而且可写。

    设置日志过滤器等级 agora.setLogFilter(filter)

    agora.setLogFilter(0x80f);
    Param Type Description
    filter Number 设置过滤器等级:
  • LOG_FILTER_OFF = 0:不输出日志信息
  • LOG_FILTER_DEBUG = 0x80f:输出所有 API 日志信息
  • LOG_FILTER_INFO = 0x0f:输出 CRITICAL、ERROR、WARNING 和 INFO 级别的日志信息
  • LOG_FILTER_WARNING = 0x0e:输出 CRITICAL、ERROR 和 WARNING 级别的日志信息
  • LOG_FILTER_ERROR = 0x0c:输出 CRITICAL 和 ERROR 级别的日志信息
  • LOG_FILTER_CRITICAL = 0x08:输出 CRITICAL 级别的日志信息
  • 设置 SDK 的输出日志过滤等级。不同的过滤等级可以单独或组合使用。

    日志级别顺序依次为 OFF_、_CRITICAL_、_ERROR_、_WARNING_、_INFO 和 _DEBUG_。选择一个级别,你就可以看到在该级别之前所有级别的日志信息。

    例如,你选择 WARNING 级别,就可以看到在 CRITICAL_、_ERRORWARNING 级别上的所有日志信息。

    监听事件信息 agora.on(event, callback, target)

    Agora SDK 通过该方法监听上述方法触发的事件,主要包含如下事件。更多事件操作请参考 EventTarget

    加入频道成功回调 agora.on('join-channel-success', (channel, uid, elapsed) => {}, this);

    Kind: global function

    Param Type Description
    channel String 频道名称
    uid Number 用户ID。如果 joinChannel 中指定了 uid,则此处返回该 ID;否则使用 Agora 服务器自动分配的 ID
    elapsed Number 从 joinChannel 开始到该事件产生的延迟(毫秒)

    说话声音音量提示回调 agora.on('audio-volume-indication', (speakers, speakerNumber, totalVolume) => {}, this);

    Kind: global function

    Param Type Description
    speakers Array 说话者(数组)。每个 speaker():
  • uid: 说话者的用户 ID。如果返回的 uid 为 0,则默认为本地用户
  • volume: 说话者的音量(0~255)
  • speakerNumber Number speakers 数组的大小
    totalVolume Number (混音后的)总音量(0~255)

    发生错误回调 agora.on('error', (err, msg) => {}, this);

    Kind: global function

    Param Type Description
    err * 错误码
    msg String 错误描述

    离开频道回调 agora.on('leave-channel', (stat) => {}, this);

    Kind: global function

    Param Type Description
    stat Object 通话相关的统计信息。
  • duration: 通话时长(秒)
  • txBytes: 发送字节数(bytes)
  • rxBytes: 接收字节数(bytes)
  • txKBitRate: 发送码率(kbps)
  • rxKBitRate: 接收码率(kbps)
  • rxAudioKBitRate: 音频接收码率 (kbps)
  • txAudioKBitRate: 音频发送频率 (kbps)
  • rxVideoKBitRate: 视频接收码率 (kbps)
  • txVideoKBitRate: 视频发送码率 (kbps)
  • userCount: 用户离开频道时频道内的瞬时人数
  • cpuAppUsage: 当前应用程序的 CPU 使用率 (%)
  • cpuTotalUsage: 当前系统的 CPU 使用率 (%)
  • 其他用户加入当前频道回调 agora.on('user-joined', (uid, elapsed) => {}, this);

    Kind: global function

    Param Type Description
    uid Number 用户 ID
    elapsed Number joinChannel 开始到该回调触发的延迟(毫秒)

    其他用户离开当前频道回调 agora.on('user-offline', (uid, reason) => {}, this);

    Kind: global function

    Param Type Description
    uid Number 用户 ID
    reason Number 离线原因

    用户被静音回调 agora.on('user-mute-audio', (uid, muted) => {}, this);

    Kind: global function

    Param Type Description
    uid Number 用户 ID
    muted Boolean 是否静音

    网络中断回调 agora.on('connection-interrupted', () => {}, this);

    Kind: global function

    Token 过期回调 agora.on('request-token', () => {}, this);

    Kind: global function

    上下麦回调 agora.on('client-role-changed', (oldRole, newRole) => {}, this);

    Kind: global function

    Param Type Description
    oldRole * 切换前的角色
    newRole * 切换后的角色

    重新加入频道成功回调 agora.on('rejoin-channel-success', (channel, uid, elapsed) => {}, this);

    Kind: global function

    Param Type Description
    channel String 频道名称
    uid Number 用户ID。
    elapsed Number 从 joinChannel 开始到该事件产生的延迟(毫秒)

    声音质量回调 agora.on('audio-quality', (uid, quality, delay, lost) => {}, this);

    Kind: global function

    Param Type Description
    uid * 用户 ID
    quality * 音频质量
    delay * 延迟,单位为毫秒
    lost * 丢包率,单位为百分比

    发生警告回调 agora.on('warning', (warn, msg) => {}, this);

    Kind: global function

    Param Type Description
    warn * 警告码
    msg * 警告描述

    频道内网络质量报告回调 agora.on('network-quality', (uid, txQuality, rxQuality) => {}, this);

    Kind: global function

    Param Type Description
    uid * 用户ID
    txQuality * 上行网络质量
    rxQuality * 下行网络质量

    声音路由发生变化 agora.on('audio-routing-changed', (routing) => {}, this);

    Kind: global function

    Param Type Description
    routing * 路由信息

    连接丢失回调 agora.on('connection-lost', () => {}, this);

    Kind: global function

    连接已被禁止回调 agora.on('connection-banned', () => {}, this);

    Kind: global function

    agora 初始化成功 agora.on("init-success", () => {}, this);

    Kind: global function

    录音设备发生变化回调 agora.on('recording-device-changed', (state, device) => {}, this);

    Kind: global function

    Param Type Description
    state * 设备状态
    device * 设备