This document describes the cloud-based English speech evaluation Application Programming Interface (API). This API supports scoring when a user reads one of several possible sentences and provides a precise pronunciation assessment for each word.-Smart Science and Education Content Platform(SSECP)-阿里云帮助中心

This document is for developers who are integrating the English selective reading speech evaluation feature.

Scenarios:

You can set multiple possible answers. The service returns a score for the sentence that the user reads.
The response indicates which sentence the user read and provides a score for each word in that sentence.

Evaluation request parameters

Field	Type	Optional	Description
coreType	String	Required	en.pcha.score specifies the selective sentence reading and scoring question type.
rank	int	Optional	The scoring system for the total score.
precision	double	Optional	Sets the scoring precision. Valid values are 0.1, 0.5, and 1. The default value is 1. If you set this parameter to a value other than 0.1 or 0.5, the system uses 1.
lm	array	Required	Each `text` field represents a sentence. Note: The `lm` field is the lowercase form of LM.
cmd_word	int	Optional	0: Uses the standard decoding network. This is the default. 1: Uses a simplified decoding network. This network decodes faster but with lower accuracy. Set this parameter when the request contains a large amount of text.
attachAudioUrl	int	Optional	Specifies whether to return the audio URL in the evaluation result. 0: Do not return the URL. 1: Return the URL.

Parameter example

{
    "coreType": "en.pcha.score",
    "rank": 2,
    "precision": 0.5,
    "attachAudioUrl":1,
    "lm": [
        {
            "text": "In an office."
        },
        {
            "text": "In a store."
        },
        {
            "text": "In the street."
        }
    ]
}

Sample response

{
    "tokenId": "6128911b88bf5b0000010001",
    "applicationId": "a148",
    "audioUrl": "http:\/\/files.cloud.ssapi.cn:8080\/a148\/11ec0706927891bcb926a148a2611b16",
    "connect": {
        "param": {
            "app": {
                "timestamp": "1630048539",
                "applicationId": "a148",
                "sig": "4ed2c46a91797df21ab073c83da52deb3d59e157"
            },
            "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": "1630048539",
            "userId": "ssound_text",
            "sig": "4ed2c46a91797df21ab073c83da52deb3d59e157",
            "connect_id": "6128911b88bf5b0000030002",
            "clientId": "",
            "applicationId": "a148"
        },
        "audio": {
            "sampleBytes": 2,
            "audioType": "ogg",
            "sampleRate": 16000,
            "channel": 1
        },
        "request": {
            "lm": [
                {
                    "text": "In an office."
                },
                {
                    "text": "In a store."
                },
                {
                    "text": "In the street."
                }
            ],
            "tokenId": "6128911b88bf5b0000010001",
            "precision": 0.5,
            "attachAudioUrl": 1,
            "request_id": "6128911b88bf5b0000020001",
            "rank": 2,
            "coreType": "en.pcha.score"
        }
    },
    "recordId": "11ec0706927891bcb926a148a2611b16",
    "eof": 1,
    "result": {
        "index": 3,
        "wavetime": 2990,
        "precision": 0.5,
        "systime": 2896,
        "res": "eng.pcha.mfcc.0.1",
        "version": "0.0.80.2021.7.24.00:01:28",
        "info": {
            "tipId": 0,
            "clip": 0,
            "snr": 24.283798,
            "volume": 86
        },
        "rank": 2,
        "delaytime": 81,
        "details": [
            {
                "accent": "ea",
                "char": "In",
                "dur": 310,
                "score": 2,
                "end": 1130,
                "start": 820
            },
            {
                "accent": "ea",
                "char": "the",
                "dur": 160,
                "score": 2,
                "end": 1290,
                "start": 1130
            },
            {
                "accent": "ea",
                "char": "street",
                "dur": 660,
                "score": 2,
                "end": 1950,
                "start": 1290
            }
        ],
        "pretime": 2,
        "overall": 1.5
    },
    "dtLastResponse": "2021-08-27 15:15:38:989",
    "cloud_platform": {
        "origin_audio_length": 11600
    }
}

Response description

Key	Type	Description	Usage suggestion
recordId	string	The unique ID of the audio file.	For reference.
tokenId	string	The unique ID of the request.	For reference.
applicationId	string	The authorized account, which is the provided AppKey.	Internal parameter.
audioUrl	string	The URL of the user's audio. By default, the audio is stored in the cloud for one month. Save the audio to your product server.	For reference.
dtLastResponse	string	The timestamp of the cloud response.	Internal parameter.
eof	Int	0: The response is not complete. More results will follow. 1: All results for this evaluation have been returned.	Internal parameter.
params	object	Echoes the evaluation request parameters sent by the client.
- app	object
- - applicationId	string	The authorized account, which is the provided AppKey.
- - userId	string	The user ID. This is a custom string that helps locate and troubleshoot issues.
- - timestamp	string	The start time.
- - sig	string	The verification code.
- - clientId	string
- request	object	The node for scoring request parameters.
- audio	object	The node for audio parameters in the scoring request.

result	object	The evaluation result.
- res	string	The name of the resource used for evaluating this question type.	Internal parameter.
- version	string	The version and publish time of the DPI engine.	Internal parameter.
- rank	int	The scoring system.	Internal parameter.
- precision	float	The scoring precision.	Internal parameter.
- pretime	int	The time taken by the cloud to call the Start API, in ms.	Internal parameter.
- systime	int	The total time taken for the entire evaluation process, in ms.	Internal parameter.
- delaytime	int	The time from when the cloud finishes feeding the audio to when the result is obtained, in ms.	Internal parameter.
- wavetime	int	The duration of the audio, in ms.	For reference.
- overall	float	The total score.	Recommended field.
- index	int	Indicates which sentence was read. The value starts from 1.	Recommended field.
- details	array	The scoring details for the selected sentence.	Recommended field.
- - char	string	The word.
- - score	int	The pronunciation score for the word.
- - start	int	The start time of the word in the audio, in milliseconds (ms).
- - dur	int	The end time of the word in the audio is measured in milliseconds (ms).
- - end	int	Pronunciation duration per word, in milliseconds (ms)
- info	object
- - snr	float	The signal-to-noise ratio (SNR). A higher value indicates clearer audio. The range is 0 dB to 40 dB. If this parameter affects the score, the system sets a corresponding `tipId` value.	For reference.
- - clip	float	Indicates that the audio volume is too high, which causes clipping. The range is 0 to 1. If this parameter affects the score, the system sets a corresponding `tipId` value.	Internal parameter.
- - volume	int	The recording volume. The range is 0 dB to 180 dB.	For reference.
- - tipId	int	The audio quality. For more information, see tipId message description.	Recommended field.

Suggestions for displaying evaluation results

Dimension	Description	Details
overall	Total pronunciation score	An overall evaluation of the pronunciation of the selected sentence.
index	Sentence number	Shows which sentence was evaluated.
details.score	Score for each word	The score for each word in the selected sentence.

Response for a failed evaluation

If the `result` structure in the response is empty, the evaluation has failed. The response contains an `errId` and an `error`. Use the error code to handle the failure.

Error codes

For more information, see Evaluation error codes.