Android使用指南_智能媒体服务(IMS)-阿里云帮助中心

本文将介绍如何将AICallKit SDK集成到您的Android应用中。

环境要求

Android Studio 插件版本4.1.3
Gradle 7.0.2
Android Studio自带JDK11

集成SDK

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

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

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

dependencies {
    implementation 'com.aliyun.aio:AliVCSDK_ARTC:x.x.x'                  //修改x.x.x为你工程适配的版本
    implementation 'com.aliyun.auikits.android:ARTCAICallKit:1.5.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说明

API概览

类/协议	API	说明
ARTCAICallEngine 引擎接口定义	init	初始化
	setAICallAgentType	设置智能体类型
	call	创建&开始通话
	handup	挂断
	switchMicrophone	切换麦克风状态
	interruptSpeaking	打断机器人说话
	enableVoiceInterrupt	开启/关闭智能打断
	enableSpeaker	开启/关闭扬声器
	enablePushToTalk	开启/关闭对讲机模式
	isPushToTalkEnable	对讲机模式是否开启
	startPushToTalk	对讲机模式：开始讲话
	finishPushToTalk	对讲机模式：结束讲话
	cancelPushToTalk	对讲机模式：取消这次通话
	switchRobotVoice	切换音色
	getRobotVoiceId	获取正在使用的音色
	setEngineCallback	注册回调
	isMicrophoneOn	是否关闭麦克风
	isSpeakerOn	扬声器是否开启
	isVoiceInterruptEnable	智能打断是否开启
	setAvatarAgentView	设置数字人视图载体
	setVisionPreviewView	设置本地视频预览视图载体
	muteLocalCamera	关闭/取消关闭摄像头
	isLocalCameraMute	摄像头是否关闭
	switchCamera	切换前后摄像头
	getRtcEngine	获取RTC引擎实例
	getIARTCAICallService	获取官方协议实现
IARTCAICallEngineCallback 引擎回调事件	onErrorOccurs	发生了错误
	onCallBegin	通话开始
	onCallEnd	通话结束
	onAICallEngineRobotStateChanged	机器人状态同步
	onUserSpeaking	用户说话回调
	onUserAsrSubtitleNotify	同步ASR识别用户的话
	onAIAgentSubtitleNotify	同步智能体回应的话
	onNetworkStatusChanged	网络状态回调
	onVoiceVolumeChanged	音量变化
	onVoiceIdChanged	onVoiceIdChanged
	onVoiceInterrupted	当前通话的语音打断设置改变
	onAgentVideoAvailable	智能体视频是否可用（推流）
	onAgentAudioAvailable	智能体音频是否可用（推流）
	onAgentAvatarFirstFrameDrawn	数字人首视频帧渲染
	onUserOnLine	用户上线回调
	onAgentWillLeave	当前智能体即将离开（结束当前通话）
	onHumanTakeoverWillStart	当真人即将接管当前智能体
	onHumanTakeoverConnected	当真人接管已经接通
	onReceivedAgentCustomMessage	智能体自定义消息
IARTCAICallService类	generateAIAgentShareCall	请求启动分享的智能体通话
ARTCAIAgentUtil类	parseAiAgentShareInfo	解析分享智能体的信息
ARTCAIAgentUtil类	parseAiAgentInfo	解析智能体启动的响应信息

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

开启/关闭扬声器

/**
 * 开启/关闭扬声器
 */
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

扬声器是否开启

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

isVoiceInterruptEnable

智能打断是否开启

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

setAvatarAgentView

设置数字人视图载体

/**
 * 设置数字人视图载体
 * @param viewGroup
 * @param avatarLayoutParams
 */
public abstract void setAvatarAgentView(ViewGroup viewGroup, ViewGroup.LayoutParams avatarLayoutParams);

setVisionPreviewView

设置本地视频预览视图载体

/**
 * 设置本地视频预览视图载体
 * @param viewGroup
 * @param visionLayoutParams
 */
public abstract void setVisionPreviewView(ViewGroup viewGroup, ViewGroup.LayoutParams visionLayoutParams);

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();

getIARTCAICallService

获取官方协议实现

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

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
 */
void onUserAsrSubtitleNotify(String text, boolean isSentenceEnd, int sentenceId);

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);

onAgentAvatarFirstFrameDrawn

数字人首视频帧渲染

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

onUserOnLine

用户上线回调

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

onAgentWillLeave

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

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

onHumanTakeoverWillStart

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

public void onHumanTakeoverWillStart(String takeoverUid, int takeoverMode);

参数详情：

参数	类型	含义
takeoverUid	String	真人uid
takeoverMode	Int	1：表示使用真人音色输出；0：表示使用智能体音色输出

onHumanTakeoverConnected

当真人接管已经接通

public void onHumanTakeoverConnected(String takeoverUid);

参数详情：

参数	类型	含义
takeoverUid	String	真人uid

onReceivedAgentCustomMessage

智能体自定义消息

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

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);