### Start and Evaluate Oral Recording in Android Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Initiates real-time oral evaluation by registering listeners, configuring parameters, and starting the recording process. Ensure all necessary SDK imports and private information are correctly set up. ```java import com.tencent.taisdk.*; import java.util.UUID; public class OralEvaluationActivity extends AppCompatActivity { private TAIOralEvaluation oral = new TAIOralEvaluation(); public void startInternalRecording() { // 1. 注册监听器 oral.setListener(new TAIOralEvaluationListener() { @Override public void onEvaluationData(TAIOralEvaluationData data, TAIOralEvaluationRet result) { // 每个分片的实时评测回调（流式模式下多次触发） // data.seqId — 分片序号；data.bEnd — 是否最后一片 // result.pronAccuracy — 发音精准度 [-1, 100] // result.pronFluency — 发音流利度 [0, 1] // result.pronCompletion — 发音完整度 [0, 1] Log.d("SOE", "实时结果 seq=" + data.seqId + " 精准度=" + result.pronAccuracy); } @Override public void onFinalEvaluationData(TAIOralEvaluationData data, TAIOralEvaluationRet result) { // 最终评测结果（录音结束后触发一次） // result.suggestedScore — 建议分数 [0, 100] // result.words — List 逐词评分 runOnUiThread(() -> Log.i("SOE", "最终分数：" + result.suggestedScore) ); } @Override public void onEvaluationError(TAIOralEvaluationData data, TAIError error) { Log.e("SOE", "评测失败 seqId=" + data.seqId + " code=" + error.code + " " + error.desc); } @Override public void onEndOfSpeech(boolean isSpeak) { // isSpeak=true：已检测到声音后静音；false：从未检测到声音 // 可在此自动停止录音 oral.stopRecordAndEvaluation(); } @Override public void onVolumeChanged(int volume) { // 实时音量回调，范围 [0, 120]，可用于展示录音波形 runOnUiThread(() -> progressBar.setProgress(volume)); } }); // 2. 构建评测参数 TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.context = this; param.appId = PrivateInfo.appId; param.soeAppId = PrivateInfo.soeAppId; param.secretId = PrivateInfo.secretId; param.secretKey = PrivateInfo.secretKey; param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.STREAM; // 流式传输（推荐） param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; // 句子评测 param.storageMode = TAIOralEvaluationStorageMode.DISABLE; // 不存储音频 param.serverType = TAIOralEvaluationServerType.ENGLISH; // 英文评测 param.fileType = TAIOralEvaluationFileType.MP3; param.textMode = TAIOralEvaluationTextMode.NORMAL; param.scoreCoeff = 1.0; // 苛刻指数 [1.0-4.0] param.refText = "how are you"; // 待评测参考文本 param.audioPath = getFilesDir() + "/" + param.sessionId + ".mp3"; // 本地音频保存路径 param.timeout = 5; // 流式模式建议 5s 超时 param.retryTimes = 5; // 失败重试次数 // 3. 配置录音分片和静音检测参数 TAIRecorderParam recordParam = new TAIRecorderParam(); recordParam.fragEnable = true; // 开启分片 recordParam.fragSize = 1024; // 分片大小（字节），建议为 1024 的整数倍 recordParam.vadEnable = true; // 开启静音检测 recordParam.vadInterval = 5000; // 静音检测间隔（ms） recordParam.db = 20; // 静音检测分贝阈值 oral.setRecorderParam(recordParam); // 4. 开始录制并评测 oral.startRecordAndEvaluation(param); } public void stopRecording() { oral.stopRecordAndEvaluation(); } } ``` -------------------------------- ### Initialize Parameters and Start Internal Recording for Oral Evaluation Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Initialize parameters for oral evaluation and set recorder parameters for internal recording. This includes configuring session, work mode, evaluation mode, server type, file type, and silence detection. ```java //三、初始化参数 TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.context = this; param.appId = ""; param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.ONCE; param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.scoreCoeff = 1.0; param.refText = ""; param.secretId = ""; param.secretKey = ""; //四、设置分片和静音检测 TAIRecorderParam recordParam = new TAIRecorderParam(); recordParam.fragSize = 1024; recordParam.fragEnable = true; recordParam.vadEnable = true; recordParam.vadInterval = Integer.parseInt(this.vadInterval.getText().toString()); this.oral.setRecorderParam(recordParam); //五、开始录制 this.oral.startRecordAndEvaluation(param); ``` -------------------------------- ### Configure Recorder Parameters with Silence Detection Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Configure recorder parameters, including enabling silence detection and setting the detection interval and decibel threshold. This should be done before starting the recording. ```java //在开始调用`startRecordAndEvaluation`前设置录制参数 TAIRecorderParam recordParam = new TAIRecorderParam(); recordParam.fragSize = 1024; recordParam.fragEnable = true; recordParam.vadEnable = true; recordParam.vadInterval = 5000; recordParam.db = 20; //静音检测分贝阈值 this.oral.setRecorderParam(recordParam); ``` -------------------------------- ### Get String to Sign for Signature Generation Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Obtain the string required for signature generation. This is used when employing external signature methods. ```java //获取签名所需字符串 public String getStringToSign(long timestamp); ``` -------------------------------- ### Get TAISDK Version Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Retrieve the current SDK version string using TAIManager.getVersion(). This is useful for debugging and compatibility checks. ```java import com.tencent.taisdk.TAIManager; public class MainActivity extends AppCompatActivity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // 在标题栏展示当前 SDK 版本，便于调试 String sdkVersion = TAIManager.getVersion(); this.setTitle(String.format("教育AI（%s）", sdkVersion)); // 预期输出标题：教育AI（1.2.3.92） } } ``` -------------------------------- ### External Signature for Oral Evaluation Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Use this when secretKey should not be stored client-side. The SDK provides getStringToSign to get the string to sign, and the backend calculates the signature using Tencent Cloud's signing rules. The secretKey can be left empty when using an external signature. ```java long timestamp = System.currentTimeMillis() / 1000; // 1. Get the string to sign (provided by the SDK) String stringToSign = oral.getStringToSign(timestamp); // 2. Send stringToSign to the backend, which calculates the signature (HMAC-SHA256) and returns it String signature = yourBackend.sign(stringToSign); // Backend implementation // 3. Construct parameters with external signature (secretKey not required) TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.appId = PrivateInfo.appId; param.soeAppId = PrivateInfo.soeAppId; param.secretId = PrivateInfo.secretId; // secretId is still required param.signature = signature; // External signature: required param.timestamp = timestamp; // Must match the timestamp used in getStringToSign param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.STREAM; param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.scoreCoeff = 1.0; param.refText = "how are you"; // Leave secretKey empty, the SDK will use the signature for authentication ištoral.startRecordAndEvaluation(param); ``` -------------------------------- ### TAIOralEvaluation - Real-time Oral Evaluation Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt This method starts the real-time oral evaluation process. It automatically records microphone audio, streams it to the Tencent Cloud SOE service for evaluation, and provides real-time feedback. It is recommended for scenarios requiring real-time waveform display and automatic silence detection. Call `stopRecordAndEvaluation` to end the process. ```APIDOC ## startRecordAndEvaluation(param) ### Description Starts the real-time oral evaluation process. The SDK internally records microphone audio and streams it in real-time to the Tencent Cloud SOE service for evaluation. This is recommended for scenarios where real-time waveform display and automatic silence detection are needed. ### Method `oral.startRecordAndEvaluation(param)` ### Parameters - **param** (TAIOralEvaluationParam) - Required - An object containing the parameters for the oral evaluation. - **context** (Context) - Required - The Android Context. - **appId** (String) - Required - Your Tencent Cloud App ID. - **soeAppId** (String) - Required - Your SOE App ID. - **secretId** (String) - Required - Your Tencent Cloud Secret ID. - **secretKey** (String) - Required - Your Tencent Cloud Secret Key. - **sessionId** (String) - Required - A unique session ID for the evaluation. - **workMode** (TAIOralEvaluationWorkMode) - Required - The work mode, typically `STREAM` for real-time streaming. - **evalMode** (TAIOralEvaluationEvalMode) - Required - The evaluation mode, e.g., `SENTENCE` for sentence evaluation. - **storageMode** (TAIOralEvaluationStorageMode) - Required - The storage mode, e.g., `DISABLE` to not store audio. - **serverType** (TAIOralEvaluationServerType) - Required - The server type, e.g., `ENGLISH` for English evaluation. - **fileType** (TAIOralEvaluationFileType) - Required - The type of audio file, e.g., `MP3`. - **textMode** (TAIOralEvaluationTextMode) - Required - The text mode, e.g., `NORMAL`. - **scoreCoeff** (Double) - Optional - The score coefficient, typically between 1.0 and 4.0. - **refText** (String) - Required - The reference text to be evaluated against. - **audioPath** (String) - Optional - The local path to save the audio file if storage is enabled. - **timeout** (Integer) - Optional - The timeout for the streaming mode, recommended to be around 5 seconds. - **retryTimes** (Integer) - Optional - The number of times to retry on failure. ### Recorder Parameters (via `setRecorderParam`) - **fragEnable** (Boolean) - Optional - Enables audio fragmentation. Recommended to be `true`. - **fragSize** (Integer) - Optional - The size of each audio fragment in bytes. Recommended to be a multiple of 1024. - **vadEnable** (Boolean) - Optional - Enables Voice Activity Detection (VAD) for silence detection. Recommended to be `true`. - **vadInterval** (Integer) - Optional - The interval for VAD in milliseconds. Recommended to be 5000ms. - **db** (Integer) - Optional - The decibel threshold for VAD. Recommended to be 20. ### Callbacks (via `setListener`) - **onEvaluationData**: Called for each audio fragment with real-time evaluation results. - **onFinalEvaluationData**: Called once after recording ends with the final evaluation results. - **onEvaluationError**: Called when an evaluation error occurs. - **onEndOfSpeech**: Called when silence is detected after speech, can be used to automatically stop recording. - **onVolumeChanged**: Called with the real-time audio volume level. ### Request Example (Java) ```java // ... (listener setup and param building as shown in the source code) oral.startRecordAndEvaluation(param); ``` ### Response - **Success Response**: Callbacks provide real-time and final evaluation results. - **Error Response**: `onEvaluationError` callback provides error details. ``` -------------------------------- ### Initialize Parameters and Transmit Audio Data for External Recording Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Initialize parameters for oral evaluation and transmit audio data using external recording. This involves reading audio data from a file and passing it to the SDK. ```java //三、初始化参数 TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.context = this; param.appId = ""; param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.ONCE; param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.scoreCoeff = 1.0; param.refText = "hello guagua"; param.secretId = ""; param.secretKey = ""; //四、传输数据 try{ InputStream is = getAssets().open("hello_guagua.mp3"); byte[] buffer = new byte[is.available()]; is.read(buffer); is.close(); TAIOralEvaluationData data = new TAIOralEvaluationData(); data.seqId = 1; //分片序号从1开始 data.bEnd = true; data.audio = buffer; this.oral.oralEvaluation(param, data); } catch (Exception e){ } ``` -------------------------------- ### Oral Evaluation with External Audio (Java) Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Initiates an oral evaluation using a pre-recorded audio file. Ensure the audio is 16kHz, 16bit, mono. Configure evaluation parameters and provide the audio byte array. ```java import com.tencent.taisdk.*; import java.io.InputStream; import java.util.UUID; public class OralEvaluationActivity extends AppCompatActivity { private TAIOralEvaluation oral = new TAIOralEvaluation(); public void startExternalAudioEvaluation() { // 1. 注册监听器 oral.setListener(new TAIOralEvaluationListener() { @Override public void onEvaluationData(TAIOralEvaluationData data, TAIOralEvaluationRet result) { // 分片回调，外部 ONCE 模式通常只触发一次 Gson gson = new Gson(); Log.d("SOE", "结果：" + gson.toJson(result)); } @Override public void onFinalEvaluationData(TAIOralEvaluationData data, TAIOralEvaluationRet result) { // result.words 包含每个单词的详细评分 for (TAIOralEvaluationWord word : result.words) { // word.word — 单词文本 // word.pronAccuracy — 单词发音准确度 [-1, 100] // word.matchTag — 0:匹配 1:新增 2:缺少 // word.phoneInfos — List 音素详情 Log.i("SOE", word.word + " 准确度=" + word.pronAccuracy + " 匹配=" + word.matchTag); } } @Override public void onEvaluationError(TAIOralEvaluationData data, TAIError error) { Log.e("SOE", "错误：" + error.code + " " + error.desc + " requestId=" + error.requestId); } @Override public void onEndOfSpeech(boolean isSpeak) {} @Override public void onVolumeChanged(int volume) {} }); // 2. 构建评测参数 TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.context = this; param.appId = PrivateInfo.appId; param.soeAppId = PrivateInfo.soeAppId; param.secretId = PrivateInfo.secretId; param.secretKey = PrivateInfo.secretKey; param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.ONCE; // 一次性传输（外部录制推荐） param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.textMode = TAIOralEvaluationTextMode.NORMAL; param.scoreCoeff = 1.0; param.refText = "hello guagua"; // 参考文本 param.timeout = 30; // ONCE 模式建议 30s 超时 // 3. 读取本地音频文件并构建数据对象 try { InputStream is = getAssets().open("hello_guagua.mp3"); // assets 中的 MP3 文件 byte[] buffer = new byte[is.available()]; is.read(buffer); is.close(); TAIOralEvaluationData data = new TAIOralEvaluationData(); data.seqId = 1; // 分片序号，从 1 开始 data.bEnd = true; // ONCE 模式只有一片，直接标记为最后一片 data.audio = buffer; // 音频字节数组 // 4. 发起评测 oral.oralEvaluation(param, data); } catch (Exception e) { Log.e("SOE", "读取音频文件失败：" + e.getMessage()); } } } ``` -------------------------------- ### Parameter Descriptions Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Detailed explanations of common parameters used across various SDK operations. ```APIDOC ## Common Parameters ### TAICommonParam | Parameter | Type | Required | Description | |---|---|---|---| | context | Context | Yes | Application context | | appId | String | Yes | Application ID | | timeout | int | No | Timeout duration, default is 30 seconds | | secretId | String | Yes | Secret ID | | secretKey | String | Internal signing: Required | Secret Key | | signature | String | External signing: Required | Signature | | timestamp | long | External signing: Required | Second-level timestamp | ### TAIError | Parameter | Type | Description | |---|---|---| | code | int | Error code | | desc | String | Error description | | requestId | String | Request ID for error locating | ## Math Correction Parameters ### TAIMathCorrectionParam | Parameter | Type | Required | Description | |---|---|---|---| | sessionId | String | Yes | Unique identifier for a correction task | | imageData | byte[] | Yes | Image data for correction | ### TAIMathCorrectionRet | Parameter | Type | Description | |---|---|---| | sessionId | String | Unique identifier for a correction task | | formula | String | The recognized formula | | items | List | Results of the formula breakdown | ### TAIMathCorrectionItem | Parameter | Type | Description | |---|---|---| | result | boolean | The result of a sub-expression | | rect | Rect | The bounding box coordinates of the sub-expression | | formula | String | The string representation of the sub-expression | ``` -------------------------------- ### Oral Evaluation - Internal Recording Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md This section demonstrates how to use the SDK for oral evaluation with internal audio recording. The SDK handles audio capture, processing, and transmission. ```APIDOC ## Initialize and Set Listener ### Description Declare an `TAIOralEvaluation` object and set up listeners for evaluation data, final results, and errors. ### Code ```java // Declare and define the object private TAIOralEvaluation oral = new TAIOralEvaluation(); // Set data callbacks this.oral.setListener(new TAIOralEvaluationListener() { @Override public void onEvaluationData(final TAIOralEvaluationData data, final TAIOralEvaluationRet result) { // Data and result callback } @Override public void onFinalEvaluationData(final TAIOralEvaluationData data, final TAIOralEvaluationRet result) { // Final evaluation result callback } @Override public void onEvaluationError(TAIOralEvaluationData data, TAIError error) { // Evaluation failure callback } }); ``` ## Initialize Parameters and Start Recording ### Description Configure the `TAIOralEvaluationParam` and `TAIRecorderParam` for the evaluation, then start the recording and evaluation process. ### Code ```java // Initialize parameters TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.context = this; param.appId = ""; param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.ONCE; param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.scoreCoeff = 1.0; param.refText = ""; param.secretId = ""; param.secretKey = ""; // Set fragmentation and silence detection TAIRecorderParam recordParam = new TAIRecorderParam(); recordParam.fragSize = 1024; recordParam.fragEnable = true; recordParam.vadEnable = true; recordParam.vadInterval = Integer.parseInt(this.vadInterval.getText().toString()); this.oral.setRecorderParam(recordParam); // Start recording and evaluation this.oral.startRecordAndEvaluation(param); ``` ## Stop Recording ### Description Call this method to stop the ongoing recording and evaluation process. ### Code ```java // Stop recording this.oral.stopRecordAndEvaluation(); ``` ``` -------------------------------- ### Speech Detection Callbacks (Java) Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Configures the SDK for speech detection using `TAIRecorderParam`. Enables `vadEnable` to trigger `onEndOfSpeech` on silence and `onVolumeChanged` for real-time volume visualization. ```java TAIRecorderParam recordParam = new TAIRecorderParam(); recordParam.fragEnable = true; recordParam.fragSize = 1024; recordParam.vadEnable = true; // 必须为 true，以下静音检测才生效 recordParam.vadInterval = 3000; // 3 秒静音后触发 onEndOfSpeech recordParam.db = 20; // 低于 20 分贝视为静音 oral.setRecorderParam(recordParam); oral.setListener(new TAIOralEvaluationListener() { @Override public void onEndOfSpeech(boolean isSpeak) { runOnUiThread(() -> { if (!isSpeak) { // 从未检测到声音，提示用户重新录制 Toast.makeText(ctx, "未检测到声音，请重试", Toast.LENGTH_SHORT).show(); } else { // 检测到静音，自动停止录制 oral.stopRecordAndEvaluation(); } }); } @Override public void onVolumeChanged(final int volume) { // volume 范围 [0, 120]，可驱动 ProgressBar 或自定义波形 View runOnUiThread(() -> volumeProgressBar.setProgress(volume)); } // 其他回调方法省略... @Override public void onEvaluationData(TAIOralEvaluationData d, TAIOralEvaluationRet r) {} @Override public void onFinalEvaluationData(TAIOralEvaluationData d, TAIOralEvaluationRet r) {} @Override public void onEvaluationError(TAIOralEvaluationData d, TAIError e) {} }); ``` -------------------------------- ### Import TAISDK Dependency Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Add this dependency to your app's build.gradle file to include the TAISDK. ```gradle implementation 'com.tencent.edu:TAISDK:1.2.3.78' ``` -------------------------------- ### Oral Evaluation - External Recording Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md This section covers using the SDK for oral evaluation when audio is recorded externally. You provide the audio data directly to the SDK. ```APIDOC ## Initialize Parameters and Transmit Data ### Description Configure the `TAIOralEvaluationParam` and then transmit externally recorded audio data to the SDK for evaluation. ### Code ```java // Initialize parameters TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.context = this; param.appId = ""; param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.ONCE; param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.scoreCoeff = 1.0; param.refText = "hello guagua"; param.secretId = ""; param.secretKey = ""; // Transmit data try{ InputStream is = getAssets().open("hello_guagua.mp3"); byte[] buffer = new byte[is.available()]; is.read(buffer); is.close(); TAIOralEvaluationData data = new TAIOralEvaluationData(); data.seqId = 1; // Fragment sequence number starts from 1 data.bEnd = true; data.audio = buffer; this.oral.oralEvaluation(param, data); } catch (Exception e){ } ``` ### Notes External recording currently only supports 16kHz sampling rate, 16-bit encoding, mono audio. Inconsistent formats may lead to inaccurate or failed evaluations. ``` -------------------------------- ### Configure Tencent Cloud Security Credentials Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Provide your Tencent Cloud appId, secretId, secretKey, and specific application IDs for SOE and HCM in your project's configuration. ```java public class PrivateInfo { static final String appId = "your_app_id"; // 腾讯云主账号 AppId static final String soeAppId = "your_soe_app_id"; // 口语评测应用 ID（SOE 控制台创建） static final String hcmAppId = "your_hcm_app_id"; // 数学批改应用 ID（HCM 控制台创建） static final String secretId = "your_secret_id"; // 访问密钥 Id static final String secretKey = "your_secret_key"; // 访问密钥 Key（线上建议用临时密钥） static final String token = ""; // 临时密钥 Token（使用临时密钥时填写） } ``` -------------------------------- ### TAIManager.getVersion() Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Retrieves the current integrated SDK version string. This is useful for displaying debugging information and checking version compatibility. ```APIDOC ## TAIManager — SDK 版本管理 ### TAIManager.getVersion() 获取当前集成的 SDK 版本字符串，常用于调试信息展示和版本兼容性检查。 ```java import com.tencent.taisdk.TAIManager; public class MainActivity extends AppCompatActivity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // 在标题栏展示当前 SDK 版本，便于调试 String sdkVersion = TAIManager.getVersion(); this.setTitle(String.format("教育AI（%s）", sdkVersion)); // 预期输出标题：教育AI（1.2.3.92） } } ``` ``` -------------------------------- ### PrivateInfo - Tencent Cloud Security Credentials Configuration Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Configure your Tencent Cloud `appId`, `secretId`, and `secretKey` in the `PrivateInfo` class before using any SDK features. `soeAppId` and `hcmAppId` are specific to Oral Evaluation and Math Correction respectively. ```APIDOC ## PrivateInfo — 配置腾讯云安全凭证 在使用任何 SDK 功能前，需将腾讯云控制台获取到的 `appId`、`secretId`、`secretKey` 填入项目配置文件。`soeAppId` 用于口语评测，`hcmAppId` 用于数学批改，均需在对应控制台新建应用后获取。 ```java // com/tencent/taidemo/PrivateInfo.java public class PrivateInfo { static final String appId = "your_app_id"; // 腾讯云主账号 AppId static final String soeAppId = "your_soe_app_id"; // 口语评测应用 ID（SOE 控制台创建） static final String hcmAppId = "your_hcm_app_id"; // 数学批改应用 ID（HCM 控制台创建） static final String secretId = "your_secret_id"; // 访问密钥 Id static final String secretKey = "your_secret_key"; // 访问密钥 Key（线上建议用临时密钥） static final String token = ""; // 临时密钥 Token（使用临时密钥时填写） } ``` ``` -------------------------------- ### Silence Detection Configuration Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Configure silence detection parameters to control how the SDK identifies and handles periods of silence during recording. ```APIDOC ## Configure Silence Detection ### Description Set `TAIRecorderParam` before calling `startRecordAndEvaluation` to enable and configure silence detection. ### Code ```java // Set recorder parameters before calling startRecordAndEvaluation TAIRecorderParam recordParam = new TAIRecorderParam(); recordParam.fragSize = 1024; recordParam.fragEnable = true; recordParam.vadEnable = true; recordParam.vadInterval = 5000; recordParam.db = 20; // Silence detection decibel threshold this.oral.setRecorderParam(recordParam); ``` ### Callbacks Notifications for silence detection or volume changes are provided through `TAIOralEvaluationListener`. ```java // Detected silence (isSpeak: true - sound detected since recording started, false - no sound detected) @Override public void onEndOfSpeech(boolean isSpeak) { // Handle business logic here, e.g., stop recording or prompt user } // Volume change public void onVolumeChanged(final int volume) { // Callback for recording decibel level [0-120] } ``` ### TAIRecorderParam Parameters | Parameter | Type | Description | |---|---|---| | fragEnable | boolean | Whether to enable fragmentation, default is YES | | fragSize | int | Fragmentation size, default is 1024. Recommended to be a multiple of 1024, range [1k-10k] | | vadEnable | boolean | Whether to enable silence detection, default is NO | | vadInterval | int | Silence detection time interval, unit [ms] | | db | int | Silence detection decibel threshold | ``` -------------------------------- ### Math Problem Correction Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md This snippet demonstrates how to use the TAISDK for math problem correction. It covers object declaration, parameter initialization, and the actual correction call with success and error callbacks. ```APIDOC ## Math Problem Correction ### Description This operation allows for the correction of mathematical problems using the TAISDK. It requires initialization with relevant parameters and provides callbacks for success and error scenarios. ### Method `correction` ### Parameters #### Request Body (TAIMathCorrectionParam) - **context** (Context) - Required - The Android context. - **appId** (String) - Required - The application ID obtained from the console. - **sessionId** (String) - Required - A unique session identifier. - **imageData** (byte[]) - Required - The image data of the math problem in JPEG format. - **secretId** (String) - Required - The secret ID for authentication. - **secretKey** (String) - Required - The secret key for authentication. ### Request Example ```java // Initialize TAIMathCorrection object private TAIMathCorrection correction = new TAIMathCorrection(); // Initialize parameters TAIMathCorrectionParam param = new TAIMathCorrectionParam(); param.context = this; param.appId = ""; // Replace with your appId param.sessionId = UUID.randomUUID().toString(); // Convert bitmap to byte array ByteArrayOutputStream outputStream = new ByteArrayOutputStream(this.bitmap.getByteCount()); this.bitmap.compress(Bitmap.CompressFormat.JPEG, 50, outputStream); param.imageData = outputStream.toByteArray(); param.secretId = ""; // Replace with your secretId param.secretKey = ""; // Replace with your secretKey // Perform correction this.correction.correction(param, new TAIMathCorrectionCallback() { @Override public void onError(TAIError error) { // Handle error } @Override public void onSuccess(final TAIMathCorrectionRet result) { // Handle success with TAIMathCorrectionRet } }); ``` ### Response #### Success Response - **TAIMathCorrectionRet** - The result object containing the correction details. ``` -------------------------------- ### oral.oralEvaluation(param, data) Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Initiates an oral evaluation using provided parameters and audio data. This method is suitable for scenarios where the audio is already available or recorded through a custom process. The audio format must be 16kHz sampling rate, 16-bit encoding, and mono channel for accurate results. ```APIDOC ## oral.oralEvaluation(param, data) ### Description Initiates an oral evaluation using provided parameters and audio data. This method is suitable for scenarios where the audio is already available or recorded through a custom process. The audio format must be 16kHz sampling rate, 16-bit encoding, and mono channel for accurate results. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```java import com.tencent.taisdk.*; import java.io.InputStream; import java.util.UUID; public class OralEvaluationActivity extends AppCompatActivity { private TAIOralEvaluation oral = new TAIOralEvaluation(); public void startExternalAudioEvaluation() { // 1. 注册监听器 oral.setListener(new TAIOralEvaluationListener() { @Override public void onEvaluationData(TAIOralEvaluationData data, TAIOralEvaluationRet result) { // 分片回调，外部 ONCE 模式通常只触发一次 Gson gson = new Gson(); Log.d("SOE", "结果：" + gson.toJson(result)); } @Override public void onFinalEvaluationData(TAIOralEvaluationData data, TAIOralEvaluationRet result) { // result.words 包含每个单词的详细评分 for (TAIOralEvaluationWord word : result.words) { // word.word — 单词文本 // word.pronAccuracy — 单词发音准确度 [-1, 100] // word.matchTag — 0:匹配 1:新增 2:缺少 // word.phoneInfos — List 音素详情 Log.i("SOE", word.word + " 准确度=" + word.pronAccuracy + " 匹配=" + word.matchTag); } } @Override public void onEvaluationError(TAIOralEvaluationData data, TAIError error) { Log.e("SOE", "错误：" + error.code + " " + error.desc + " requestId=" + error.requestId); } @Override public void onEndOfSpeech(boolean isSpeak) {} @Override public void onVolumeChanged(int volume) {} }); // 2. 构建评测参数 TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.context = this; param.appId = PrivateInfo.appId; param.soeAppId = PrivateInfo.soeAppId; param.secretId = PrivateInfo.secretId; param.secretKey = PrivateInfo.secretKey; param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.ONCE; // 一次性传输（外部录制推荐） param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.textMode = TAIOralEvaluationTextMode.NORMAL; param.scoreCoeff = 1.0; param.refText = "hello guagua"; // 参考文本 param.timeout = 30; // ONCE 模式建议 30s 超时 // 3. 读取本地音频文件并构建数据对象 try { InputStream is = getAssets().open("hello_guagua.mp3"); // assets 中的 MP3 文件 byte[] buffer = new byte[is.available()]; is.read(buffer); is.close(); TAIOralEvaluationData data = new TAIOralEvaluationData(); data.seqId = 1; // 分片序号，从 1 开始 data.bEnd = true; // ONCE 模式只有一片，直接标记为最后一片 data.audio = buffer; // 音频字节数组 // 4. 发起评测 oral.oralEvaluation(param, data); } catch (Exception e) { Log.e("SOE", "读取音频文件失败：" + e.getMessage()); } } } ``` ### Response #### Success Response (200) None explicitly documented. #### Response Example None explicitly documented. ``` -------------------------------- ### Handle End of Speech and Volume Changes Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Implement callbacks for `onEndOfSpeech` to detect the end of spoken input and `onVolumeChanged` to monitor audio volume levels during evaluation. ```java //检测到静音 isSpeak true:录音开始到现在检测到声音 false:未检测到声音 @Override public void onEndOfSpeech(boolean isSpeak) { //这里可以根据业务逻辑处理，如停止录音或提示用户 } //音量发生变化 public void onVolumeChanged(final int volume) { //回调录音分贝大小[0-120] } ``` -------------------------------- ### Gradle Dependency Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt Add the TAISDK dependency to your app's build.gradle file to include the SDK in your project. ```APIDOC ## Gradle 引入依赖 在 `app/build.gradle` 的 `dependencies` 中添加： ```groovy // 当前最新版本为 1.2.3.92 implementation 'com.tencent.edu:TAISDK:1.2.3.92' ``` ``` -------------------------------- ### Initialize and Call Math Correction API Source: https://github.com/tencentcloud/tencentcloud-sdk-android-soe/blob/master/README.md Initialize TAIMathCorrectionParam with necessary details like context, app ID, session ID, image data, and API credentials. Then, call the correction method with the parameters and a callback to handle success or error. ```java //二、初始化参数 TAIMathCorrectionParam param = new TAIMathCorrectionParam(); param.context = this; param.appId = ""; param.sessionId = UUID.randomUUID().toString(); ByteArrayOutputStream outputStream = new ByteArrayOutputStream(this.bitmap.getByteCount()); this.bitmap.compress(Bitmap.CompressFormat.JPEG, 50, outputStream); param.imageData = outputStream.toByteArray(); param.secretId = ""; param.secretKey = ""; //三、作业批改 this.correction.correction(param, new TAIMathCorrectionCallback() { @Override public void onError(TAIError error) { //错误返回 } @Override public void onSuccess(final TAIMathCorrectionRet result) { //成功返回TAIMathCorrectionRet } }); ``` -------------------------------- ### External Signature Generation for Oral Evaluation Source: https://context7.com/tencentcloud/tencentcloud-sdk-android-soe/llms.txt When the `secretKey` is not suitable for plain text storage on the client, the business backend can generate a temporary key or signature string. The SDK provides `getStringToSign` to obtain the string to be signed. The backend then calculates the `signature` according to Tencent Cloud's signature rules and returns it to the client. ```APIDOC ## oral.getStringToSign(timestamp) ### Description Generates a string to be signed for external signature authentication in oral evaluation. ### Method Signature `String getStringToSign(long timestamp)` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Parameters for `startRecordAndEvaluation` (when using external signature) - **appId** (String) - Required - Your Tencent Cloud App ID. - **soeAppId** (String) - Required - Your SOE App ID. - **secretId** (String) - Required - Your Tencent Cloud Secret ID. - **signature** (String) - Required - The signature calculated by your backend using `getStringToSign`. - **timestamp** (long) - Required - The timestamp used when generating the string to sign. Must match the timestamp used in `getStringToSign`. - **sessionId** (String) - Required - A unique session identifier. - **workMode** (TAIOralEvaluationWorkMode) - Required - The work mode (e.g., STREAM). - **evalMode** (TAIOralEvaluationEvalMode) - Required - The evaluation mode (e.g., SENTENCE). - **serverType** (TAIOralEvaluationServerType) - Required - The server type (e.g., ENGLISH). - **fileType** (TAIOralEvaluationFileType) - Required - The type of the audio file (e.g., MP3). - **storageMode** (TAIOralEvaluationStorageMode) - Required - Storage mode (e.g., DISABLE). - **scoreCoeff** (double) - Optional - Score coefficient. - **refText** (String) - Optional - The reference text for evaluation. ### Request Example (Java) ```java // External signature flow example long timestamp = System.currentTimeMillis() / 1000; // Current second-level timestamp // 1. Get the string to sign (provided by SDK) String stringToSign = oral.getStringToSign(timestamp); // 2. Send stringToSign to your backend; backend calculates signature using Tencent Cloud signature rules (HMAC-SHA256) and returns it String signature = yourBackend.sign(stringToSign); // Backend implementation // 3. Construct parameters using the external signature (no need to pass secretKey) TAIOralEvaluationParam param = new TAIOralEvaluationParam(); param.appId = PrivateInfo.appId; param.soeAppId = PrivateInfo.soeAppId; param.secretId = PrivateInfo.secretId; // secretId is still required param.signature = signature; // External signature: required param.timestamp = timestamp; // Must be consistent with the timestamp for getStringToSign param.sessionId = UUID.randomUUID().toString(); param.workMode = TAIOralEvaluationWorkMode.STREAM; param.evalMode = TAIOralEvaluationEvalMode.SENTENCE; param.serverType = TAIOralEvaluationServerType.ENGLISH; param.fileType = TAIOralEvaluationFileType.MP3; param.storageMode = TAIOralEvaluationStorageMode.DISABLE; param.scoreCoeff = 1.0; param.refText = "how are you"; // Leave secretKey empty; SDK will use signature for authentication ištoral.startRecordAndEvaluation(param); ``` ### Response This method does not directly return a response. It is used to obtain a string that is then signed by the backend. The `startRecordAndEvaluation` method will handle the actual API call and return results or errors. ```