This document describes the parameter settings, scoring mechanism, and response format for the English word speech evaluation feature. It supports phoneme-level scoring, stress detection, and differentiation between British and American accents.-Smart Science and Education Content Platform(SSECP)-阿里云帮助中心

This document provides technical details for developers to integrate the speech evaluation feature for word repetition tasks.

Note

Evaluates English words and phrases with phoneme-level precision.
Supports scoring based on custom pronunciations, syllable stress detection, and differentiation between British and American accents.
Feedback dimensions include the overall word score, stress evaluation, and phoneme scores.

Evaluation request parameters

Field	Type	Optional	Description
coreType	string	Required	en.word.score indicates English word evaluation.
refText	string	Required	The reference text for scoring. Supports words and phrases. There are two ways to specify custom pronunciation: 1. directory(z:d ih r eh k tr ih): The phonemes follow the internal phoneme standard. 2. directory(p:dəˈrektəri): Specifies the pronunciation using the original phonetic alphabet. If the original phonetics correspond to multiple standards, the processing priority is IP88 > KK > IP66.
attachAudioUrl	int	Optional	Specifies whether to return the audio URL in the evaluation result. 0: Does not return the URL. 1: Returns the URL.
rank	int	Optional	The scoring scale. You can set this to any value. The final score is recalculated based on its ratio to 100.
symbol	int	Optional	Specifies whether to display punctuation marks. Set to 0 or 1. The default value is 0, which disables this feature. If there are multiple consecutive punctuation marks before a word, only the first one is displayed. If there are multiple consecutive punctuation marks at the end of a word, only the three closest to the word are output.
precision	double	Optional	Sets the scoring precision. Only 0.1, 0.5, or 1 are supported. The default value is 1. If you set a value other than 0.1 or 0.5, it is treated as 1.
typeThres	int	Optional	The scoring strictness. A higher score has less impact. 1: Strict. 2: Loose. 3: Very strict. 4: Very loose. The default value is 0, which disables this feature.
phdet	int	Optional	Phoneme error detection. 1 enables this feature. The default is 0, which disables it. You can only set this to 0 or 1.
syldet	int	Optional	Syllable error detection. 1 enables this feature. The default is 0, which disables it. You can only set this to 0 or 1.
feedback	int	Optional	1: Enables the real-time feedback feature, which provides the text position corresponding to the currently read audio. 0: The default value, which disables this feature.
accent	string	Optional	"accent":"en" specifies evaluation for a British accent. "accent":"am" specifies evaluation for an American accent. If this parameter is not set, the engine intelligently determines the accent (British or American) based on the pronunciation.

Parameter example

{
    "coreType":"en.word.score",
    "refText":"classical",
    "attachAudioUrl": 1,
    "rank":100,
    "precision":0.5
}

Response example

{
    "applicationId":"axxx",
    "audioUrl": "http:\/\/xxx.xxx.ssapi.cn:8080\/axxx\/11ebeeb24003be329ce2a1xxxxxxxx", // User audio download URL
    "recordId":"5af5686d28c338cdad00606b", // The unique ID of the data in the cloud. Save this to your product database for troubleshooting.
    "dtLastResponse":"2018-05-11 17:54:56:309", // Data timestamp of the response
    "result":{
        "forceout":0,
        "pron":77,               
        "version":"0.0.80.2018.5.9.10:53:11",
        "rank":100,               // Scoring scale. 100 indicates a 100-point scale, 10 indicates a 10-point scale, and so on.
        "pretime":143,         // Time taken by the cloud to call the Start API, in ms.
        "delaytime":58,       // Time taken from the end of audio feeding to getting the result in the cloud, in ms.
        "overall":77,             // Overall pronunciation score
        "info":{
            "volume":81,
            "clip":0,
            "snr":20.770369,
            "tipId":0   // Audio quality code
        },
        "wavetime":2990, // Duration of the audio file
        "systime":3243, // Duration of the evaluation calculation in the cloud
        "details":[
            {
                "dur":930,  // Word pronunciation duration, in ms
                "phone":[  // Phoneme combination of the word
                    {
                        "char":"k",  // The returned value is a phoneme, not an International Phonetic Alphabet (IPA) symbol. If your product requires it, convert it to an IPA symbol.
                        "pherr":0, // Detects if there is a phoneme error (0 or 1). This field is output only when phdet is set in the request.
                        "phid":"1", // Index of the phoneme in the phonetic transcription
                        "score":79 // Phoneme score
                    },
                    {
                        "char":"l",
                        "pherr":0,
                        "phid":"2",
                        "score":77
                    },
                    {
                        "char":"ae",
                        "pherr":0,
                        "phid":"3",
                        "score":75
                    },
                    {
                        "char":"s",
                        "pherr":0,
                        "phid":"4_5",
                        "score":77
                    },
                    {
                        "char":"ih",
                        "pherr":0,
                        "phid":"6",
                        "score":75
                    },
                    {
                        "char":"k",
                        "pherr":0,
                        "phid":"7",
                        "score":79
                    },
                    {
                        "char":"l",
                        "pherr":0,
                        "phid":"9",
                        "score":80
                    }
                ],
                "end":1770,          // End time of the word in the audio, in ms
                "char":"classical",
                "stress":[                // Stress pronunciation
                    {
                        "char":"k_l_ae",  // Syllable
                        "ref":1,              // Indicates if the current syllable should be stressed. 1 means stressed, 0 means not stressed.
                        "score":0         
                    },
                    {
                        "char":"s_ih",
                        "ref":0,
                        "score":1
                    },
                    {
                        "char":"k_l",
                        "ref":0,
                        "score":0
                    }
                ],
                "start":840,   // Start time of the word in the audio, in ms
                "score":77    // Pronunciation score for a single word
            }
        ],
        "precision":0.5,
        "res":"eng.wrd.online.0.2"
    },
    "eof":1,
    "params":{
        "app":{
            "timestamp":"1526032357",
            "sig":"6cc2b777cf134afa191de8932826eabce58db24b",
            "applicationId":"aXXX",   // The product's AppKey
            "clientId":"",
            "userId":"ssound_text",  // A custom string for the product. We recommend using a unique userId for each user to help with troubleshooting.
            "connect_id":"5af567cb000df30000060004"
        },
        "request":{                  // Parameter node for the scoring request
            "coreType":"en.word.score",  // Task type
            "phdet":1,                 // Phoneme error detection. 1 enables this feature. The default is 0, which disables it. You can only set this to 0 or 1.
            "refText":"classical",    // Text content
            "precision":0.5,         // Scoring precision
            "request_id":"5af567e5000df30000120001",
            "syldet":1,
            "attachAudioUrl": 1,  // Specifies whether to return the audio URL in the evaluation result. 0: No. 1: Yes.
            "rank":100          // Scoring scale. The default is 100 for a 100-point scale. You can set this to any value. The final score is recalculated based on its ratio to 100.
        },
        "audio":{                    // Audio format parameters for the scoring request
            "sampleRate":16000,  // Sample rate
            "channel":1,    // Sound channel. 1 is mono, 2 is stereo. Evaluation only supports mono.
            "sampleBytes":2,
            "audioType":"ogg"  // Audio type
        }
    },
    "refText":"classical"  
}

Description of the response

Key	Type	Description	Suggestion
recordId	string	The unique ID of the audio file.	For reference.
tokenId	string	The unique ID of the user request.	For reference.
audioUrl	string	The download URL for the user's audio. The audio is stored for about 20 days by default. For long-term storage, download it to your own server. The domain name varies by access region. The actual returned URL prevails.	For reference.
applicationId	string	The evaluation AppKey for the authorized account.	Internal parameter.
dtLastResponse	string	The timestamp of the response from the cloud.	Internal parameter.
eof	int	Real-time feedback flag. 0 indicates that the response is not complete and more results will follow. 1 indicates that this is the final result for the current evaluation.	Internal parameter.
refText	string	The evaluation text.	For reference.
params	object	Echoes the evaluation request parameters passed in by the client.
- app	object
- - applicationId	string	The authorized account, which is the AppKey provided for evaluation.
- - userId	string	User ID.
- - timestamp	string	Start time.
- - sig	string	Verification code.
- request	object	The parameter settings node for the scoring request.
- audio	object	The audio parameter settings node for the scoring request.
result	object	Evaluation result.
- version	string	The engine version, including the release date.	Internal parameter.
- rank	int	Scoring scale.	Internal parameter.
- precision	float	Scoring precision.	Internal parameter.
- res	string	The name of the resource used for evaluating this task type.	Internal parameter.
- forceout	int		Internal parameter.
- pretime	int	Time taken by the cloud to call the Start API, in ms.	Internal parameter.
- systime	int	Total time for the entire evaluation process, in ms.	Internal parameter.
- delaytime	int	Time taken from the end of audio feeding to getting the result in the cloud, in ms.	Internal parameter.
- wavetime	int	Audio duration, in ms.	For reference.
- overall	float	Overall score.	Recommended field.
- pron	float	Pronunciation score.	Internal parameter.
- details	array
- - start	int	Start time of the word in the audio, in ms.	For reference.
- - end	int	End time of the word in the audio, in ms.	For reference.
- - dur	int	Word pronunciation duration, in ms.	For reference.
- - char	string	Word text.	For reference.
- - score	int	Word score.	For reference.
- - fake_pron	int	This field is output only when the word is not in the dictionary (out-of-vocabulary). To evaluate out-of-vocabulary words, pass the phonetic transcription using the refText parameter.
- - accent	string	British or American accent feedback. This field is not returned if the accent parameter is configured in the request. Otherwise, it is returned, for example, "accent":"ea".
- - dp_type	int	Indicates if a word was read normally (the `dp_type` field is not output), omitted (1), or repeated (2). Normal: This field is not output. Omission: dp_type is 1. Repetition: dp_type is 2.
- - syllable	array	Syllable error detection.
- - - char	string	Syllable pronunciation.	For reference.
- - - score	int	Syllable pronunciation score (0–100).	For reference.
- - - start	int	Start time of the syllable within the word, in ms.	For reference.
- - - end	int	End time of the syllable within the word, in ms.	For reference.
- - stress	array	Stress pronunciation.
- - - char	string	Phoneme.	For reference.
- - - ref	int	Indicates if the current syllable should be stressed. 1 means stressed, 0 means not stressed.
- - - score	int	Stress score (0 or 1).
- - phone	array	Phoneme-level scoring result. For more information, see Phoneme reference table.
- - - char	string	Phoneme. If the accent parameter is set in the request, this field contains standard British or American phonemes. Otherwise, it contains internal mapped phonemes.	For reference.
- - - score	int	Phoneme score (0–100).	For reference.
- - - phid	int	The position of the phoneme in the word's phonetic transcription. This field is output only when phdet is set.
- - - pherr	int	Detects if there is a phoneme error (0 or 1). This field is output only when phdet is set.
- - - ph2alpha	string	The letter in the word corresponding to the current phoneme. You do not need to calculate this using phid. This field is output only when phdet is set.
- realtime_details	object	Real-time feedback information.
-- char	string	Word.	For reference.
-- dp_type	int	0: Normal reading. 1: Omitted or not read. 2: Repeated.	For reference.
- info	object
- - snr	float	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	Recording volume. Range: 0–180 dB.	For reference.
- - tipId	int	Audio quality. For more information, see tipId message descriptions.	Recommended field.

Recommended dimensions for displaying evaluation results

Dimension	Description	Details
overall	Overall word score.	Overall evaluation of the word.
score	Pronunciation score.	Word accuracy score.
details.stress.score	Word stress score.	Evaluation of the stress in the word. Check for a null value before retrieving this score.
details.phone.score	Phoneme score.	Evaluation of a specific phoneme in the word. Check for a null value before retrieving this score.
details.dp_type	Word insertion or omission.	Indicates whether the word is repeated or skipped. For more information, see the response description for the corresponding question type.
details.fake_pron	Audio Spoofing	Indicates whether the word is in the dictionary. If not, a pronunciation is predicted for the word.

Response when evaluation fails

If the result structure in the response is empty, the evaluation has failed.
You can retrieve the errId and error from the response. Your product can then perform further checks and handle the issue based on the corresponding error code.

Error codes

For more information, see Evaluation error codes.