10 分钟接入：集成发音评测 Android SDK

如果你正打算开发一个语言学习 App，在了解了 DolphinSOE 的功能之后，你一定想马上动手开始开发。DolphinSOE 已经准备了多种开发语言的 SDK，能够帮助开发者快速上手集成发音评测功能。本文就以 Android SDK 为例，手把手带你体验 10 分钟快速跑通一个能出分的英语发音评测 DEMO。

Android Studio 中运行的 DolphinSOE 发音评测 Demo 界面

DolphinSOE Android Demo 运行界面

在 Android 上集成发音评测，真的只需要 10 分钟吗？

跑通一个最小可运行 Demo，确实只需要 10 分钟：完成凭证申请、引入 SDK、初始化引擎、执行一次录音并获取评分。但跑通 Demo 不等于可以直接上线生产环境，业务上线还需要完成题库准备、业务 UI 开发、异常逻辑处理等工作。

但即便只是跑通 Demo，这个过程也比大多数人想象中简单得多。DolphinSOE 提供的 Android SDK 已经把录音采集、Token 维护、音频传输、获取打分结果这一整条链路都包进了客户端几行调用里。从零开始，大概需要以下的操作步骤：

步骤	预计耗时
提交官网表单、接收自动回复邮件	2 分钟
下载 SDK，把 appid/appsecret 填进示例代码	2 分钟
设置题型参数（评分题型、参考答案等）	2 分钟
编译、运行	4 分钟

日文版接入流程

中文版接入流程

准备好开发环境，跟我们一起开始吧。

两分钟完成测试申请

DolphinSOE 的测试通道相当简单：

① 提交测试申请：在官网提交「联系我们」表单，
② 接收自动回复的邮件：只需几秒钟，系统会自动回复一封邮件，邮件里附带试用的 appid / appsecret。这套测试凭证支持英语、日语、中文三种语言的发音评测，最大支持 2 路并发，能够满足本地调试和单设备演示需求。邮件里还附了 SDK 下载地址和接口文档，安卓 SDK 下载下来解压就能用。

下载后的 Demo 工程内置完整测试界面，录音、音频播放、评分展示等基本功能均已实现，无需开发者从头搭建 UI，有效提升集成调试效率。

三步跑通第一个发音评测流程

以调用英语基础题型为例，DEMO 把接入压缩成了三步：

Step 1 · 放入 SDK 文件。 将压缩包中的 .aar 文件放入项目的 app/libs 目录。请根据项目目标设备架构（x86 / ARM）选择对应的 aar 包。

Step 2 · 填入凭证。 打开项目中的 MainActivity.java 文件，把邮件中收到的 appid / appsecret 填进这两个常量：

// MainActivity.java
private static final String appIdEn = "";     // ← 填写邮件里的 appid
private static final String appSecretEn = ""; // ← 填写邮件里的 appsecret

Step 3 · 编译运行。 实测运行，在 DEMO 的测试界面上选择题型，开始录音、朗读、结束录音，分数立刻出来。

到这里，一个最简单的发音评测 DEMO 就已经跑通了，是不是非常简单？

如果你接下来想把发音评测 SDK 嵌入到自己的 App里，那请继续往下看。

DEMO 在背后做了什么

如果你要把评测嵌进自己的业务界面，而不是用 DEMO 的测试页，那你需要了解引擎的初始化流程。具体在 EvalLogic.java 这个文件中。

// 1) 创建引擎单例
SpeechEval eval = SpeechEval.createInstance(this);

// 2) 基础配置
eval.setSampleRate(16000);                       // 采样率固定 16000
eval.setListener(evalListener);                  // 实现 EventListener，接收结果/错误事件
eval.setInitLanguageEn(SpeechEval.InitSettingOnline.OralOnLine); //设置为在线评测模式

// 3) 初始化单例
eval.setServerAPI("api.soe.dolphin-ai.jp");
eval.init(appIdEn, appSecretEn, "user01");

初始化结果通过 engineInitState 回调回来，成功码是 "00000"。常见的失败码：13010（缺少网络权限）、11011（签名错误）、11013（appId 不存在）。在开发调试时，可优先通过该状态码配合状态码表排查相关问题。

一次评测要设置哪些参数？

在一次评测中，参数分为两类：公共参数和题型参数。

公共参数：管「怎么连接、用什么语言、什么评分规则」，它是整个会话级别的配置，跟“评什么”无关。
题型参数：管「这一题评什么、怎么评」，这是每个评测任务（每次请求）的配置，核心就是“选题型+提供参考答案”。

跑通 DEMO 时，在 UI.java 中已经配置了相关的公共参数，比如语种 langType、采样率 sampleRate 等。如果你需要设置某个参数，使用 SpeechEval 类中提供的 set 方法就可以了。在这里注意，如果不希望云端留存音频数据，请调用 setAudioUrl(false) 进行设置；如需云端保存音频，请设置 setAudioUrl(true) ，音频的下载链接将随评分结果一同返回，云端存储的数据将在 30 天后自动删除。

对于题型参数，需要通过 setParamsJson 传进去：

JSONObject json = new JSONObject();
json.put("mode", "word");              // 题型：word / sentence / chapter 等等
json.put("refText", "good morning");  // 参考文本，引擎照它打分
eval.setParamsJson(json);

不同题型在参考文本怎么组织、评到什么粒度上差别很大。各题型的时长限制、refText 与评分维度差异，我们在英语发音评测基础题型这篇文章里系统讲过；完整的参数列表（以英语单词题型为例），请参考接口文档。

最后建议每次评测都传入 userId（可以自定义，DEMO 里示例是“user01”），userId 会随评测结果原样回传，便于问题排查与数据追溯。

怎样开始录音并得到评分结果？

配置好之后，评测有两种发起方式：

录音方式：createRecorder() 建好录音器，再 start(recorder, startListener) 开始；用户念完调 stop() 结束（也可以开后置静音检测让它自动停）。startListener 用来监听开始 / 结束状态，体验更稳。
传文件方式：start(wavPath, startListener)，直接把一段已有的音频送进去评。文件要求 16000Hz / 16Bit / 单声道 的 wav 或 pcm，发完自动结束，不用再调用 stop()。

如果中途想取消，使用 cancel() 取消本次评测，不会返回结果。

结果在 onResult 回调里以 JSON 字符串形式返回：

eval.setListener(new SpeechEval.EventListener() {
    @Override
    public void onResult(String result, boolean online) {
        // result 是 JSON 字符串，从中解析出各维度得分
        // 具体格式请参考接口协议文档
    }
    @Override
    public void onWarning(String taskId, String code, String msg) {
        // 处理Warning事件
    }
    @Override
    public void onError(String taskId, String code, String msg) {
        // 处理Error事件
    }
});