Android使用指南

环境要求

• Android Studio 插件版本4.1.3

• Gradle 7.0.2

• Android Studio自带JDK11

集成SDK

1. 在项目级build.gradle项目文件中添加阿里云Maven仓库。

   allprojects {
       repositories {
           google()
           jcenter()
           maven { url 'https://maven.aliyun.com/repository/google' }
           maven { url 'https://maven.aliyun.com/repository/public' }
       }
   }

2. 在相应build.gradle项目文件下，引入ARTCAICallKit依赖项。

   dependencies {
       implementation 'com.aliyun.aio:AliVCSDK_ARTC:x.x.x'                  //修改x.x.x为你工程适配的版本
       implementation 'com.aliyun.auikits.android:ARTCAICallKit:2.1.0'
   }

   说明

   ARTC SDK版本请到官网获取最新适配版本号。

SDK使用示例

ARTCAICallEngine mARTCAICallEngine = null;

// 创建engine实例
void initEngine(Context context, String userId) {
    // 初始化
    // context -> Android Context
    // userId -> 进入rtc频道的用户id
    mARTCAICallEngine = new ARTCAICallDepositEngineImpl(context, userId);   
}

// 设置回调
void initCallback() {
    mARTCAICallEngine.setEngineCallback(mCallEngineCallbackWrapper); 
}

// 启动智能体后，开始通话
void call() {
    // 设置engine的启动参数
    ARTCAICallEngine.ARTCAICallConfig artcaiCallConfig = new ARTCAICallEngine.ARTCAICallConfig();
    // 如果有临时的智能体ID，可以配置
    artcaiCallConfig.aiAgentId = aiAgentId;
    mARTCAICallEngine.init(artcaiCallConfig);
    
    // 指定智能体的类型：纯语音、数字人、视觉理解
    ARTCAICallEngine.ARTCAICallAgentType aiAgentType = VoiceAgent;
    mARTCAICallEngine.setAiAgentType(aiAgentType);

    // 如果是数字人类型，则需要配置数字人显示的视图容器
    if (aiAgentType == AvatarAgent) {
        ViewGroup avatarlayer;
        mARTCAICallEngine.setAvatarAgentView(
            avatarlayer,
            new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
                                       ViewGroup.LayoutParams.MATCH_PARENT)
        );
    }
    // 如果是视觉理解类型，则需要配置本地视频预览显示的视图容器
    else if (aiAgentType == VisionAgent) {
        ViewGroup previewLayer;
        mARTCAICallEngine.setVisionPreviewView(previewLayer,
            new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
                                         ViewGroup.LayoutParams.MATCH_PARENT)
        );
    }

    // 进入频道
    String aIAgentInstanceId = “XXX”;
    String rtcAuthToken = "XXX";
    String aIAgentUserId = "XXX";
    String channelId = "XXX";
    mARTCAICallEngine.call(rtcAuthToken, aIAgentInstanceId, 
                           aIAgentUserId, channelId);
}

// 结束通话
void handup() {
    mARTCAICallEngine.handup();
}

// 其他功能调用示例，请参考API说明

// 回调处理（仅示例不分核心的回调操作）
ARTCAICallEngine.IARTCAICallEngineCallback mCallEngineCallbackWrapper = new ARTCAICallEngine.IARTCAICallEngineCallback() {
    @Override
    public void onErrorOccurs(ARTCAICallEngine.AICallErrorCode errorCode) {
        // 发生了错误，结束通话
        mARTCAICallEngine.handup();
    }

    @Override
    public void onCallBegin() {
        // 通话开始（入会）
    }

    @Override
    public void onCallEnd() {
        // 通话结束（离会）
    }

    @Override
    public void onAICallEngineRobotStateChanged(ARTCAICallEngine.ARTCAICallRobotState oldRobotState, ARTCAICallEngine.ARTCAICallRobotState newRobotState) {
        // 机器人状态同步
    }

    @Override
    public void onUserSpeaking(boolean isSpeaking) {
        // 用户说话回调
    }

    @Override
    public void onUserAsrSubtitleNotify(String text, boolean isSentenceEnd, int sentenceId) {
        // 同步ASR识别用户的话
    }

    @Override
    public void onAIAgentSubtitleNotify(String text, boolean end, int userAsrSentenceId) {
        // 同步智能体回应的话
    }

    @Override
    public void onNetworkStatusChanged(String uid, ARTCAICallEngine.ARTCAICallNetworkQuality quality) {
        // 网络状态回调
    }

    @Override
    public void onVoiceVolumeChanged(String uid, int volume) {
        // 音量变化
    }

    @Override
    public void onVoiceIdChanged(String voiceId) {
        // 当前通话的音色发生了改变
    }

    @Override
    public void onVoiceInterrupted(boolean enable) {
        // 当前通话的语音打断设置改变
    }

    @Override
    public void onAgentVideoAvailable(boolean available) {
        // 智能体视频是否可用（推流）
    }

    @Override
    public void onAgentAudioAvailable(boolean available) {
        // 智能体音频是否可用（推流）
    }
    
    @Override
    public void onAgentAvatarFirstFrameDrawn() {
        // 数字人首视频帧渲染
    }

    @Override
    public void onUserOnLine(String uid) {
        // 用户上线回调
    }

};

API说明

ARTCAICallEngine详情

init

初始化

/**
 * 初始化
 * @param config 初始化配置
 */
public abstract void init(ARTCAICallConfig config);

参数详情：

setAICallAgentType

设置智能体类型

/**
 * 设置智能体类型
 * @param aiAgentType
 */
public abstract void setAICallAgentType(ARTCAICallAgentType aiAgentType);

参数详情：

call

创建&开始通话

/**
 * 创建&开始通话
 */
public abstract void call(String rtcToken, String aiAgentInstanceId, String aiAgentUserId, String channelId);

参数详情：

handup

挂断

/**
 * 挂断
 */
public abstract void handup();

switchMicrophone

切换麦克风状态

/**
 * 切换麦克风状态
 * @param on
 */
public abstract void switchMicrophone(boolean on);

参数详情：

interruptSpeaking

打断机器人说话

/**
 * 打断机器人说话
 */
public abstract boolean interruptSpeaking();

enableVoiceInterrupt

开启/关闭智能打断

/**
 * 开启/关闭智能打断
 */
public abstract boolean enableVoiceInterrupt(boolean enable);

参数详情：

enableSpeaker

扬声器/听筒切换。true: 扬声器播放，false: 听筒播放

/**
 * 扬声器/听筒切换
 */
public abstract boolean enableSpeaker(boolean enable);

参数详情：

enablePushToTalk

开启/关闭对讲机模式

/**
 * 开启/关闭对讲机模式，对讲机模式下，只有在finishPushToTalk被调用后，智能体才会播报结果
 * @param enable
 * @return
 */
public abstract boolean enablePushToTalk(boolean enable);

参数详情：

isPushToTalkEnable

对讲机模式是否开启

/**
 * 对讲机模式是否开启
 * @return
 */
public abstract boolean isPushToTalkEnable();

startPushToTalk

对讲机模式：开始讲话

/**
 * 对讲机模式：开始讲话
 * @return
 */
public abstract boolean startPushToTalk();

finishPushToTalk

对讲机模式：结束讲话

/**
 * 对讲机模式：结束讲话
 * @return
 */
public abstract boolean finishPushToTalk();

cancelPushToTalk

对讲机模式：取消这次通话

/**
 * 对讲机模式：取消这次通话
 * @return
 */
public abstract boolean cancelPushToTalk();

switchRobotVoice

切换音色

/**
 * 切换音色
 */
public abstract boolean switchRobotVoice(String voiceId);

参数详情：

getRobotVoiceId

获取正在使用的音色

/**
 * 获取正在使用的音色
 * @return
 */
public abstract String getRobotVoiceId();

setEngineCallback

注册回调

/**
 * 注册回调
 * @param engineCallback
 */
public abstract void setEngineCallback(IARTCAICallEngineCallback engineCallback);

参数详情：

isMicrophoneOn

是否关闭麦克风

/**
 * 是否关闭麦克风
 * @return
 */
public abstract boolean isMicrophoneOn();

isSpeakerOn

是否是扬声器播放，true: 扬声器播放，false: 听筒播放。

/**
 * 是否是扬声器播放
 * @return
 */
public abstract boolean isSpeakerOn();

isVoiceInterruptEnable

智能打断是否开启

/**
 * 智能打断是否开启
 * @return
 */
public abstract boolean isVoiceInterruptEnable();

setAvatarAgentView

设置数字人视图载体并指定渲染模式

public abstract void setAvatarAgentView(ViewGroup viewGroup, ViewGroup.LayoutParams avatarLayoutParams, ARTCAICallVideoCanvas canvas);

参数详情：

setVisionPreviewView

设置视觉理解本地视图载体并指定渲染模式

public abstract void setVisionPreviewView(ViewGroup viewGroup, ViewGroup.LayoutParams visionLayoutParams, ARTCAICallVideoCanvas canvas);

参数详情：

muteLocalCamera

关闭/取消关闭摄像头

/**
 * 关闭/取消关闭摄像头
 */
public abstract boolean muteLocalCamera(boolean mute);

参数详情：

isLocalCameraMute

摄像头是否关闭

/**
 * 摄像头是否关闭
 * @return
 */
public abstract boolean isLocalCameraMute();

switchCamera

切换前后摄像头

/**
 * 切换前后摄像头
 */
public abstract boolean switchCamera();

getRtcEngine

获取RTC引擎实例

/**
 * 获取rtc引擎实例
 * @return
 */
public abstract AliRtcEngine getRtcEngine();

/**
 * 获取官方协议实现
 * @return
 */
public abstract IARTCAICallService getIARTCAICallService();

/**
 * 发送自定义消息给LLM
 * @param req
*/
public  boolean sendTextToAgent(ARTCAICallSendTextToAgentRequest req);

/**
 * 发送自定义消息给AppServer
 * 复用智能体消息通道，向AppServer发送消息, 需要AppServer监听回调拿到自定义的消息
 * @param msg
 * @return true: 发送成功；false: 发送失败
*/
public boolean sendCustomMessageToServer(String msg);

/**
 * 更新llm的系统提示词，例如：“你是一位友好且乐于助人的助手，专注于为用户提供准确的信息和建议。”
 * @param prompt
 * @return true: 更新成功；false: 更新失败
*/
public boolean updateLlmSystemPrompt(String prompt)

/**
 * Vision智能体，开始启动自定义截帧，启动后，无法通过语音与智能体通话
 * @param request 请求参数
 * @return true: 发送成功；false: 发送失败
*/
public  boolean startVisionCustomCapture(ARTCAICallVisionCustomCaptureRequest request);

public  boolean stopVisionCustomCapture();

IARTCAICallEngineCallback详情

onErrorOccurs

发生了错误

/**
 * 发生了错误
 * @param errorCode 错误码
 */
void onErrorOccurs(AICallErrorCode errorCode);

参数详情：

onCallBegin

通话开始（入会）

/**
 * 通话开始（入会）
 */
void onCallBegin();

onCallEnd

通话结束（离会）

/**
 * 通话结束（离会）
 */
void onCallEnd();

onAICallEngineRobotStateChanged

机器人状态同步

/**
 * 机器人状态同步
 * @param oldRobotState
 * @param newRobotState
 */
void onAICallEngineRobotStateChanged(ARTCAICallRobotState oldRobotState, ARTCAICallRobotState newRobotState);

参数详情：

onUserSpeaking

用户说话回调

/**
 * 用户说话回调
 * @param isSpeaking 是否在说话
 */
void onUserSpeaking(boolean isSpeaking);

参数详情：

onUserAsrSubtitleNotify

同步ASR识别用户的话

/**
 * 同步ASR识别用户的话
 * @param text ASR识别出的具体文本
 * @param isSentenceEnd 当前文本是否为这句话的最终结果
 * @param sentenceId 当前文本属于的句子ID
 * @param voicePrintStatusCode 声纹识别状态
 */
void  void onUserAsrSubtitleNotify(String text, boolean isSentenceEnd, int sentenceId, VoicePrintStatusCode voicePrintStatusCode);

参数详情：

onAIAgentSubtitleNotify

同步智能体回应的话

/**
 * 同步智能体回应的话
 * @param text 智能体的话
 * @param end 当前回复是否结束
 * @param userAsrSentenceId 表示回应对应sentenceId语音输入的llm内容
 */
void onAIAgentSubtitleNotify(String text, boolean end, int userAsrSentenceId);

参数详情：

onNetworkStatusChanged

网络状态回调

/**
 * 网络状态回调
 * @param uid 入会用户id
 * @param quality 网络状态
 */
void onNetworkStatusChanged(String uid, ARTCAICallNetworkQuality quality);

参数详情：

onVoiceVolumeChanged

音量变化

/**
 * 音量变化
 * @param uid 用户id
 * @param volume 音量[0-255]
 */
void onVoiceVolumeChanged(String uid, int volume);

参数详情：

onVoiceIdChanged

当前通话的音色发生了改变

/**
 * 当前通话的音色发生了改变
 */
void onVoiceIdChanged(String voiceId);

参数详情：

onVoiceInterrupted

当前通话的语音打断设置改变

/**
 * 当前通话的语音打断设置改变
 */
void onVoiceInterrupted(boolean enable);

参数详情：

onAgentVideoAvailable

智能体视频是否可用（推流）

/**
 * 智能体视频是否可用（推流）
 */
void onAgentVideoAvailable(boolean available);

参数详情：

onAgentAudioAvailable

智能体音频是否可用（推流）

/**
 * 智能体音频是否可用（推流）
 */
void onAgentAudioAvailable(boolean available);

参数详情：

onAudioDelayInfo

音频回环延迟

/**
         * 音频回环延迟
         *  @param id 语句ID
         *  @param delay_ms 延迟
         */
public void onAudioDelayInfo(int id, int delay_ms) {}

参数详情：

onAgentAvatarFirstFrameDrawn

数字人首视频帧渲染

/**
*  数字人首视频帧渲染
*/
void onAgentAvatarFirstFrameDrawn();

onUserOnLine

用户上线回调

/**
*  用户上线回调
*/
void onUserOnLine(String uid);

参数详情：

onSpeakingInterrupted

智能体当前讲话被打断

public void onSpeakingInterrupted(ARTCAICallSpeakingInterruptedReason reason);

参数说明：

onVisionCustomCapture

当前视觉理解通话是否启用了自定义截帧模式

public void onVisionCustomCapture(boolean enable)

参数说明：

onAgentWillLeave

当前智能体即将离开（结束当前通话）

/**
 * 当前智能体即将离开（结束当前通话）
 * @param reason 原因：2001（闲时退出），2002（真人接管结束）， 0（其他）
 * @param message 描述原因
 */
void onAgentWillLeave(int reason, String message);

参数详情：

onHumanTakeoverWillStart

当真人即将接管当前智能体

public void onHumanTakeoverWillStart(String takeoverUid, int takeoverMode);

当真人即将接管当前智能体

onHumanTakeoverConnected

当真人接管已经接通

public void onHumanTakeoverConnected(String takeoverUid);

当真人接管已经接通

onReceivedAgentCustomMessage

智能体自定义消息

/**
 * 智能体自定义消息
 * @param data 自定义消息体，使用JSON字符串
 */
public void onReceivedAgentCustomMessage(String data);

参数详情：

onAgentEmotionNotify

智能体情绪结果通知

public void onAgentEmotionNotify(String emotion,int userAsrSentenceId);

参数详情：

IARTCAICallService详情

generateAIAgentShareCall

请求启动分享的智能体通话

/**
 * 请求启动分享的智能体通话
 * @param userId 当前登录的用户id
 * @param aiAgentId 智能体id
 * @param aiAgentType 智能体类型
 * @param artcaiCallConfig 智能体配置
 * @param callback 请求回调
 */
void generateAIAgentShareCall(String userId, String aiAgentId, ARTCAICallEngine.ARTCAICallAgentType aiAgentType, ARTCAICallEngine.ARTCAICallConfig artcaiCallConfig, IARTCAICallServiceCallback callback);

ARTCAIAgentUtil详情

parseAiAgentShareInfo

解析分享智能体的信息

/**
 * 解析分享智能体的信息
 * @param shareInfoText
 * @return 分享智能体的结构化配置
 */
public static ARTCAIAgentShareInfo parseAiAgentShareInfo(String shareInfoText);

parseAiAgentInfo

解析智能体启动的响应信息

/**
 * 解析智能体启动的响应信息
 * @param jsonObject 智能体启动的响应信息
 * @return 智能体启动响应的结构化信息
 */
public static ARTCAIAgentInfo parseAiAgentInfo(JSONObject jsonObject);