Phonics
This document describes the technical specifications for the phonics speech assessment feature. It is intended for developers who are integrating this feature into their products.
Question type description
Scores the pronunciation of English phonics and supports error detection for phonetic symbols.
Provides separate scores for phonetic symbols and words.
Assessment request parameters
Field | Type | Optional | Description |
coreType | String | Required | en.nsp.score indicates a phonics assessment. |
refText | String | Required | Two formats are available for the reference text: |
attachAudioUrl | int | Optional | Specifies whether to return the audio URL in the assessment result. |
rank | int | Optional | The scoring scale. You can set this to any value. The final score is recalculated based on its ratio to 100. |
phdet | int | Optional | Phoneme error detection. Set to 1 to enable this feature. The default value is 0, which disables the feature. Valid values are 0 and 1. |
accent | string | Optional | "accent":"en" specifies a British English pronunciation assessment. |
Parameter example
The following is an example of the assessment parameters:
{
"coreType":"en.nsp.score",
"refText":"a(z:ae) a(z:ae) ant",
"rank":100,
"phdet":1,
"attachAudioUrl": 1
}Response example
{
"tokenId": "61264be788bf5b0000070001",
"applicationId": "a148",
"dtLastResponse": "2021-08-25 21:55:51:11",
"connect": {
"param": {
"app": {
"timestamp": "1629899603",
"applicationId": "a148",
"sig": "3ff6f9eda22673ac320a1976d45e6538d9fb8cec"
},
"sdk": {
"os": "6.2(9200)1",
"product": "",
"source": 7,
"protocol": 1,
"os_version": "6.2(9200)",
"arch": "586",
"version": 16778752
}
},
"cmd": "connect"
},
"params": {
"app": {
"timestamp": "1629899751",
"userId": "ssound_text",
"sig": "b3181b14371395759adbb6a056d465ada6969805",
"connect_id": "61264b5388bf5b0000060002",
"clientId": "",
"applicationId": "a148"
},
"audio": {
"sampleBytes": 2,
"audioType": "ogg",
"sampleRate": 16000,
"channel": 1
},
"request": {
"request_id": "61264be788bf5b0000080001",
"tokenId": "61264be788bf5b0000070001",
"coreType": "en.nsp.score",
"refText": "a(z:ae) a(z:ae) ant"
}
},
"recordId": "11ec05ac25efcaf2b1c6a148u2619eed",
"refText": "a(z:ae) a(z:ae) ant",
"result": {
"pron": 70,
"forceout": 0,
"precision": 1,
"systime": 2458,
"res": "eng.nsp.online.0.2",
"version": "0.0.80.2021.7.24.00:01:28",
"info": {
"tipId": 0,
"clip": 0,
"snr": 30.972075,
"volume": 81
},
"rank": 100,
"delaytime": 16,
"wavetime": 1990,
"details": [
{
"stress": [
{
"ref": 0,
"score": 1,
"char": "ae"
}
],
"accent": "ea",
"char": "a",
"dur": 360,
"score": 83,
"phone": [
{
"char": "ae",
"score": 83,
"end": 880,
"start": 520
}
],
"end": 880,
"start": 520
},
{
"stress": [
{
"ref": 0,
"score": 1,
"char": "ae"
}
],
"accent": "ea",
"char": "a",
"dur": 310,
"score": 81,
"phone": [
{
"char": "ae",
"score": 81,
"end": 1470,
"start": 1160
}
],
"end": 1470,
"start": 1160
},
{
"stress": [
{
"ref": 0,
"score": 1,
"char": "ae_n_t"
}
],
"accent": "ea",
"char": "ant",
"dur": 290,
"score": 45,
"phone": [
{
"char": "ae",
"score": 83,
"end": 1830,
"start": 1640
},
{
"char": "n",
"score": 79,
"end": 1900,
"start": 1830
},
{
"char": "t",
"score": 10,
"end": 1930,
"start": 1900
}
],
"end": 1930,
"start": 1640
}
],
"pretime": 1,
"overall": 70
},
"eof": 1,
"cloud_platform": {
"origin_audio_length": 7807
}
}Description of the response
Key | Type | Description | Recommended use |
recordId | string | The unique ID of the audio file. | For reference |
tokenId | string | The unique ID of the user request. | For reference |
applicationId | string | The authorized account and the evaluation AppKey | Internal parameter |
dtLastResponse | string | The time when the cloud responded. | Internal parameter |
eof | int | 0 indicates that the response is not complete and more results will follow. 1 indicates that all results for this assessment have been returned. | Internal parameter |
refText | string | The input assessment text. | For reference |
params | object | Echoes the assessment request parameters sent by the client. | |
- app | object | ||
- - applicationId | string | An evaluation Appkey is provided for the authorized account. | |
- - userId | string | The user ID. | |
- - timestamp | string | The start time. | |
- - sig | string | The verification code. | |
- request | object | The node for the scoring request parameter settings. | |
- audio | object | The node for the audio parameter settings of the scoring request. | |
result | object | The assessment result. | |
- version | string | The version of the engine, including the release time. | Internal parameter |
- rank | int | The scoring scale. | Internal parameter |
- precision | float | The scoring precision. | Internal parameter |
- res | string | The name of the resource used for assessing this question type. | Internal parameter |
- forceout | int | Internal parameter | |
- pretime | int | The time taken by the cloud to call the Start API. Unit: ms. | Internal parameter |
- systime | int | The total time taken for the entire assessment process. Unit: ms. | Internal parameter |
- delaytime | int | The time from when the cloud finishes feeding the audio to when the result is obtained. Unit: ms. | Internal parameter |
- wavetime | int | The duration of the audio. Unit: ms. | For reference |
- overall | float | The overall score. | Recommended field |
- pron | float | The pronunciation score. | Internal parameter |
- details | array | ||
- - accent | string | This field is not returned if accent is configured in the request parameters. Otherwise, this field is returned, for example, "accent":"ea". | |
- - dur | int | The duration of the word's pronunciation. Unit: ms. | For reference |
- - char | string | The normalized word text. | For reference |
- - score | int | The score for the word. | For reference |
- - dp_type | int | Indicates if a word was read normally (the dp_type field is not returned), omitted (1), or repeated (2). | |
- - start | int | The start time of the word in the audio. Unit: milliseconds (ms). | For reference |
- - end | int | The end time of the word in the audio. Unit: milliseconds (ms). | For reference |
- - stress | array | Stress pronunciation. | |
- - - char | string | The phoneme. | For reference |
- - - ref | int | Indicates whether the current syllable requires stress. | |
- - - score | int | The stress score (0 or 1). | |
- - phone | array | Phoneme-level scoring results. For more information, see Phoneme reference table. | |
- - - char | string | The phoneme. If accent is set in the request parameters, this field contains standard British or American English phonemes. Otherwise, it contains internal mapped phonemes. | For reference |
- - - score | int | The phoneme score (0-100). | For reference |
- - - phid | int | The position of the phoneme in the word's phonetic transcription. | This field is returned only when phdet is set. |
- - - pherr | int | Indicates whether an error was detected in the phoneme (0 or 1). | This field is returned only when phdet is set. |
- - - ph2alpha | string | The letter in the word that corresponds to the current phoneme. | This field is returned only when phdet is set. |
- info | object | ||
- - snr | float | The signal-to-noise ratio (SNR). A higher value indicates clearer audio. Range: 0-40 dB. If this parameter affects the score, a corresponding tipId value is set. | For reference |
- - clip | float | Indicates audio clipping due to high volume. Range: 0-1. If this parameter affects the score, a corresponding tipId value is set. | Internal parameter |
- - volume | int | The recording volume. Range: 0-180 dB. | For reference |
- - tipId | int | The audio quality. | Recommended field |
Recommended display dimensions for assessment results
Dimension | Description | Details |
overall | Overall score | The assessment score for the question type. |
Response for a failed assessment
An empty result structure in the response indicates that the assessment failed.
The response provides an errId and an error message. Your application can use the error code to determine the next steps.
Error codes
For more information, see Assessment error codes.