Scripted API Info - Elsa API

12/19/23, 10:24 PM Scripted API info | Elsa API
API info Scripted Api Info
Scripted API Information

Introduction
Execution of the scripted API via cUrl (batch) or websocket (streaming) gives out the same result.
Here, we show the returned result from executing the example sentence, together with an
explanation of what each field means.
IMPORTANT: Depending on the api_plan you select, the output will vary. Below we the properties
that appear in “premium” plans.
Feedback overview - Version 2

Overall, the feedback is a hierarchical-nested structure with several “utterance” → ”word” →
“phoneme” levels. In each level we indicate parameters computed at that level and a list of items
(e.g. an utterance contains a list of words and a word contains a list of phonemes). A special case
is word stress, which is added inside each word, alongside the phonemes structure.
A description of each field in the json response can be found below:
{
"api_version": "code indicating the version of the API that is being called.",
"total_time": "Total duration of the audio (for all utterances)",
"utterance":"[] field displaying information about the played stream and the
results obtained by the user."
[
{
"initial_silence": "flag indicating whether there is at least one
frame of silence at the beginning of the audio recording. This is useful to warn
the user he needs to wait a bit before speaking when returned as “false”.",
"sentence": "String with the word(s) that the user is prompted to
pronounce.",
"sentence_id": "ID of the processed sentence indicating which of the
input sentences is most likely to have been pronounced by the user. Default is 0
(only one sentence is input). This is used in our multi-input mode.",
"total_time": "duration of the utterance in seconds.",
"has_speech": "(deprecated, use attempt_type instead). flag indicating
whether the audio sample has any speech. It is a simple way to inform the user
when the microphone did not pick up anything. It is equivalent to the “UNSPOKEN”
type in attempt_type below.",
"attempt_type": "Characterizes the content of the speech attempt. It
can have the following values: ",
https://api-external-doc.elsanow.co/Scripted-api-info 1/20
"snr": " Signal to noise ratio (i.e. percentage of energy of speech

parts versus silent parts in the audio).",
"decision": "tring indicating how proficient the user was at
pronouncing the utterance. It is computed from the parameter nativeness_score.
Possible values are “correct”, “almost_correct” or “incorrect”.",
"nativeness_score": "nativeness score achieved by the user in the
current utterance (0-100 range).",
"nativeness_score_partial": "nativeness score achieved by the user on
those words that have been decoded and have a minimum score of at least 25%.",
"ipa": "ˈpi.tsə ˈpɑr.ti",
"speed_metrics":
{
"words_per_minute": "words per minute (even if incorrect).",
"syllables_per_minute": "syllables per minute (even if
incorrect).",
"phones_per_minute": "phones per minute (even if incorrect)",
"articulated_words_per_minute": "words per minute excluding pauses
(only considering articulation time).",
"articulated_syllables_per_minute": "words per minute excluding
pauses (only considering articulation time).",
"articulated_phones_per_minute": "phones per minute excluding
pauses (only considering articulation time)."
},
"pronunciation_rate_metrics":
{
"correct_words_per_minute": "correct words per minute.",
"correct_syllables_per_minute": "correct syllables per minute",
"correct_phones_per_minute": "correct phones per minute.",
"correct_words_ratio": "ratio of correctly pronounced words in the
sentence (0-1 range).",
"correct_syllables_ratio": "ratio of correctly pronounced
syllables in the sentence (0-1 range).",
"correct_phones_ratio": "ratio of correctly pronounced phones in
the sentence (0-1 range)."
},
"pausing_metrics":
{
"pause_ratio": "total time ratio of pauses in the utterance (0-1
range).",
"pause_ratio_without_initial_sil": "total time ratio of pauses in
the utterance excluding initial pause (0-1 range)."
},
"advanced_metrics_confidence": "NONE",
"words":"list of entries that includes information about the words
that constitute the sentence and how the user pronounced them. Each entry has the
following fields:"
[
{
"start_index": "position of the first character of this word
within the original sentence (as received by the server).",
"end_index": "position of the last character of this word

"start_time": "time (in seconds) in which the word in this
entry starts within the audio recording.",
"end_time": " time (in seconds) in which the word in this
"trans_arpabet": "phonetic transcription of the word in
ArpaBET format.",
"decoded": "flag indicating whether the word was decoded (i.e.
the audio contains something that resembles this word).",
"text": "string with the word after text normalization has
been applied to the input text.",
"text_orig": "string with the original word text.",
"ipa": "ˈpi.tsə",
"nativeness_score": "nativeness score achieved by the user in
this word.",
"decision": "string indicating how proficient the user was at
pronouncing the word. It is computed according to nativeness_score. Possible
values are “correct”, “almost_correct” or “incorrect”.",
"phonemes":"list of entries with information about the sounds
that constitute the current word and how the user pronounced them. Each entry has
the following fields"
[
{
"start_index": "position of the first character in the
sentence that is represented in this entry.",
"end_index": "position of the last character in the
"text": "set of characters in the word that
corresponds with the phoneme(s) of this entry.",
"trans": "phonetic transcription of the sounds
represented in this entry, in API format.",
"trans_arpabet": "phonetic transcription of the sounds
represented in this entry using ArpaBET format.",
"start_time": "time (in seconds) in which the sound in
this entry starts within the audio recording.",
"end_time": "time (in seconds) in which the sound in
this entry ends within the audio recording.",
"decision": "string indicating whether the user
correctly pronounced the phonemes in this entry. Possible values are “correct”,
“warning” or “error”.",
"nativeness_score": "score achieved by the user for
the sound or sounds represented in this entry, in the rance 0-100.",
"phoneme_error": "whenever we find an error (decision
== “incorrect”) and the error is a substitution we detect, this field presents the
correct phonetic transcription and what we detected that the user pronounced. This
is in IPA format. If all is correct, we return “correct”.",
"phoneme_error_arpabet": "when the error is a
substitution, this field presents the correct phonetic transcription and that
pronounced by the user in ArpaBET. If all is correct, we return “correct”."
},
{
},
{
"feedback":"List with automatically generated hints
for the user to improve their pronunciation of the sounds in this entry."
[
{
"id": "internal numeric identifier for the
feedback sentence.",
"audio_link": "link to an audio recording with
the hint in spoken format.",
"text": "string with the hint in written
format.",
"language": "language in which the feedback is
presented. By default hints are sent in English on the API results."
}
]
},
{
}
],
"word_stress":"list of entries that includes information about

the syllables that constitute the word, the type of stress they have and whether
it was correctly uttered by the user. Each entry has the following fields:"
[
{
correctly stressed the syllable.Possible values are correct or incorrect.",
"stress_level_measured": "string indicating the stress
produced by the user. Its value is “high” if the user stressed the syllable and
“low” otherwise."
},
{
"decision": "position of the last character in the
}
]
},
{
"end_index": "position of the last character in the sentence
that is represented in this entry.",
"start_time": "time (in seconds) in which the sound in this
"end_time": "time (in seconds) in which the sound in this
entry ends within the audio recording.",
"text_orig": "string with the original word text.",
"ipa": "ˈpɑr.ti",
"nativeness_score":"nativeness score achieved by the user in
the current utterance (0-100 range)." ,

that constitute the current word and how the user pronounced them"
[
{
},
{

},
{
},
{

},
{
}
],
it was correctly uttered by the user. "
[
{

correctly stressed the syllable. Possible values are correct or incorrect.",
},
{
}
]
}
]
}
],
"success": "flag indicating whether the call was successful, does not say
anything about the content."
}
Notes about the json values:
Attempt type can have the following values:
“INCOMPLETE” → The user spoke only part of what was expected. This could also be
returned when the user speaks something unrelated but part of it is close enough to the
target text.
“UNSPOKEN” → There is no speech detected in the submitted audio.
“UNRELATED” → Speech is detected, but it does not seem to correspond to what was
requested.
“RELEVANT” → Text and audio match sufficiently well, the scoring is reliable.
Feedback overview - Version 3

In this version, we introduce the following metrics:
utterance.nativeness_score and utterance.nativeness_score_partial changed to

utterance.pronunciation_score and utterance.pronunciation_score_partial
utterance.eps_score, utterance.cefr_score, utterance.toefl_score, utterance.toeic_score,
utterance.pte_score are added
utterance.decision can now be “correct”, “warning”, “incorrect” (from “correct”,
“almost_correct”, “incorrect” in v2)
utterance.has_speech is removed, a “false” is equivalent to the “UNSPOKEN” type in
utterance.attempt_type
utterance.words.text is the equivalent to v2’s utterance.words.text_orig
utterance.words.word is the equivalent to v2’s utterance.words.text
utterance.words.decision can now be “correct”, “warning”, “incorrect” (from “correct”,
“almost_correct”, “incorrect” in v2)
utterance.words.phonemes.ipa is the equivalent to v2’s utterance.words.phonemes.trans
utterance.words.phonemes.decision can now be “correct”, “warning”, “incorrect” (from
“correct”, “warning”, “error” in v2)
A description of each field in the json response can be found below:
{
"api_version": "code indicating the version of the API that is being called.",
"total_time": "Total duration of the audio (for all utterances)",
"utterance":"[] field displaying information about the played stream and the
results obtained by the user."
[
{
"initial_silence": "flag indicating whether there is at least one
frame of silence at the beginning of the audio recording. This is useful to warn
the user he needs to wait a bit before speaking when returned as “false”.",
"sentence": "String with the word(s) that the user is prompted to
pronounce.",
"sentence_id": "ID of the processed sentence indicating which of the
input sentences is most likely to have been pronounced by the user. Default is 0
(only one sentence is input). This is used in our multi-input mode.",
"total_time": "duration of the utterance in seconds.",
"attempt_type": "Characterizes the content of the speech attempt. It
can have the following values: ",
"snr": " Signal to noise ratio (i.e. percentage of energy of speech
parts versus silent parts in the audio).",
"decision": "tring indicating how proficient the user was at
"ipa": "ˈpi.tsə ˈpɑr.ti",
"intonation_score": "evaluates the ability to emphasize the key words
in the sentence (0-100 range).",

"fluency_score": "evaluates the ability to use natural rhythm and
pausing at the right times (0-100 range).",
"speed_metrics":
{
"words_per_minute": "words per minute (even if incorrect).",
"syllables_per_minute": "syllables per minute (even if
incorrect).",
"phones_per_minute": "phones per minute (even if incorrect)",
"articulated_words_per_minute": "words per minute excluding pauses
(only considering articulation time).",
"articulated_syllables_per_minute": "words per minute excluding
pauses (only considering articulation time).",
"articulated_phones_per_minute": "phones per minute excluding
pauses (only considering articulation time)."
},
"pronunciation_rate_metrics":
{
"correct_words_per_minute": "correct words per minute.",
"correct_syllables_per_minute": "correct syllables per minute",
"correct_phones_per_minute": "correct phones per minute.",
"correct_words_ratio": "ratio of correctly pronounced words in the
sentence (0-1 range).",
"correct_syllables_ratio": "ratio of correctly pronounced
syllables in the sentence (0-1 range).",
"correct_phones_ratio": "ratio of correctly pronounced phones in
the sentence (0-1 range)."
},
"pausing_metrics":
{
"pause_ratio": "total time ratio of pauses in the utterance (0-1
range).",
"pause_ratio_without_initial_sil": "total time ratio of pauses in
the utterance excluding initial pause (0-1 range).",
"pausing_score_percentage": "percentage of correct pauses in the
utterance (0-100 range)."
},
"advanced_metrics_confidence": "NONE",
"ielts_score": "an IELTS level estimate based on eps_score (1.5-9).",
"cefr_score": "a CEFR level estimate based on eps_score (A1-C2).",
"toefl_score": "a TOEFL iBT speaking score estimate based on eps_score
(0-30).",
"toeic_score": "a TOEIC speaking score estimate based on eps_score (0-
200).",
"pte_score": "a PTE score estimate based on eps_score (0-90).",
"pronunciation_score": "nativeness score achieved by the user in the
current utterance (0-100 range).",
"pronunciation_score_partial": "nativeness score achieved by the user
on those words that have been decoded and have a minimum score of at least 25%.",
"eps_score": "Global ELSA Proficiency Score, combining pronunciation,
fluency and intonation (0-100 range).",

"recording_quality": "Characterizes the quality of the recording.
Possible values: “ok”, “loud”, “quiet”, “noisy”, “mixed” (mixed issues)",
"words":"list of entries that includes information about the words
that constitute the sentence and how the user pronounced them. Each entry has the
following fields:"
[
{
"start_index": "position of the first character of this word
"end_index": "position of the last character of this word
"start_time": "time (in seconds) in which the word in this
"end_time": " time (in seconds) in which the word in this
"trans_arpabet": "phonetic transcription of the word in
ArpaBET format.",
"ipa": "ˈpi.tsə",
"nativeness_score": "nativeness score achieved by the user in
this word.",
pronouncing the word. It is computed according to nativeness_score. Possible
values are “correct”, “almost_correct” or “incorrect”.",
"word": "string with the original word text.",
that constitute the current word and how the user pronounced them. Each entry has
the following fields"
[
{

},
{
},
{

"feedback":"List with automatically generated hints
for the user to improve their pronunciation of the sounds in this entry."
[
{
"id": "internal numeric identifier for the
feedback sentence.",
"audio_link": "link to an audio recording with
the hint in spoken format.",
"text": "string with the hint in written
format.",
"language": "language in which the feedback is
presented. By default hints are sent in English on the API results."
}
]
},
{

}
],
it was correctly uttered by the user. Each entry has the following fields:"
[
{
correctly stressed the syllable.Possible values are correct or incorrect.",
}
]
},
{
"end_index": "position of the last character in the sentence
that is represented in this entry.",
"start_time": "time (in seconds) in which the sound in this
"end_time": "time (in seconds) in which the sound in this
entry ends within the audio recording.",
"ipa": "ˈpɑr.ti",
"nativeness_score":"nativeness score achieved by the user in
the current utterance (0-100 range)." ,
that constitute the current word and how the user pronounced them"
[
{

},
{
},
{
},
{

},
{
}
],
it was correctly uttered by the user. "
[
{
},
{
}
]
}
]
}
],
"success": "flag indicating whether the call was successful, does not say
anything about the content."
}

Scripted API Info - Elsa API

Uploaded by

Copyright:

Available Formats

Scripted API Info - Elsa API

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Scripted API Info - Elsa API

Uploaded by

Copyright:

Available Formats

12/19/23, 10:24 PM Scripted API info | Elsa API

API info Scripted Api Info

Scripted API Information

Feedback overview - Version 2

A description of each field in the json response can be found below:

"snr": " Signal to noise ratio (i.e. percentage of energy of speech

"end_index": "position of the last character of this word

"word_stress":"list of entries that includes information about

"phonemes":"list of entries with information about the sounds

the sound or sounds represented in this entry, in the rance 0-100.",

"end_time": "time (in seconds) in which the sound in

sentence that is represented in this entry.",

Notes about the json values:

Attempt type can have the following values:

Feedback overview - Version 3

utterance.nativeness_score and utterance.nativeness_score_partial changed to

A description of each field in the json response can be found below:

in the sentence (0-100 range).",

fluency and intonation (0-100 range).",

the sound or sounds represented in this entry, in the rance 0-100.",

"decision": "string indicating whether the user

is in IPA format. If all is correct, we return “correct”.",

"end_index": "position of the last character in the

the sound or sounds represented in this entry, in the rance 0-100.",

You might also like

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.