# Score Text/Markup Language

{% hint style="info" %}
**Run in Postman:** [Scoring text using markup language](https://docs.speechace.com/#63ea84b0-b0d9-432f-a9ad-b83dff1a4d28)
{% endhint %}

Markup language allows you to override Speechace lexicon and define your own.

### Markup Syntax

When `markup_language=arpa_mark` is specified, the input text can have markups on zero, one or multiple words. This flag can be used in scoring pronunciation, multiple choice or[ Validate Text ](https://api-docs.speechace.com/api-reference/score-text-validate-text)requests.

Each markup has the pattern: `[l1|l2|...|ln]{s1|s2|...|sn}`, where:

* `l1`, `l2`, ..., `ln` are substrings of a word in the input text, and
* `s1`, `s2`, ..., `sn` are syllables of the word corresponding to `l1`, `l2`, ..., `ln`.
* Each syllable, `si`, has this pattern: `p1` `p2` ... `pk`, where `pi` is a phoneme in [ARPABET notation](https://api-docs.speechace.com/guides-on-common-topics/phonetic-notation) for the dialect. 
* If `pi` is a vowel phoneme, `pi` ends with 0, 1 or 2 to denote the stress level of the syllable.
* There should be at most one vowel per syllable.

{% hint style="info" %}
Let's take a word "Nothing" and divide it into its syllables and phonemes along with its stress level to understand it better:

1. **\[noth | ing]**: "Nothing" has two syllables, "noth" and "ing".
2. **{n ah1 th | ih0 ng}**: This part is a phonetic transcription where:
   1. **n**: Represents the phoneme /n/, as in "no".
   2. **ah1**: Represents the stressed vowel phoneme /ʌ/, as in "cup". The "1" indicates primary stress.
   3. **th**: Represents the phoneme /θ/, as in "think".
   4. **ih0**: Represents the vowel phoneme /ɪ/, as in "sit", with "0" indicating no stress or secondary stress.
   5. **ng**: Represents the phoneme /ŋ/, as in "sing".
      {% endhint %}

### Markup Language Use-cases

1. Marking up a word to explicitly specify syllable boundaries and phoneme mapping\
   `There was [noth|ing]{n ah1 th|ih0 ng} on the rock.`
2. Specifying which word is intended in a heteronym (i.e. 2 words which share the same spelling but have different pronunciation and meaning). *Here the heteronyms are "read" and "fragments".*\
   `He [read]{r eh1 d} his [frag|ments]{f r ae1 g|m ah0 n t s} aloud.`
3. Handling special acronyms, numbers, or terms\
   `Agent [0||||07]{d ah1 | b ah0 l | ow1 | s eh1 | v ah0 n} worked for MI6.`

{% hint style="info" %}
Note: In the above example in order to map 007 to "Double-O Seven" and no other possible pronunciation of the number "007", we create multiple empty syllables in the word "007". 

For detailed explanation of markup language, refer the Markup Language [guide](https://api-docs.speechace.com/guides-on-common-topics/markup-language).
{% endhint %}

### Request Response Example

We will evaluate the sentence using the markup language applied to the word "read," as demonstrated below:

{% code overflow="wrap" %}

```
I love to [read]{r iy1 d}. Last year I [read]{r eh1 d} Anna Karenina by [Tol|stoy]{t ow1 l|s t oy2}.
```

{% endcode %}

The request parameters which you can see in the cURL below can be found in [Score Text/Pronunciation](https://api-docs.speechace.com/api-reference/score-text-pronunciation).

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" lineNumbers="true" %}

```curl
curl --location -g 'https://api.speechace.co/api/scoring/text/v9/json?key={{speechacekey}}' \
--form 'text="I love to [read]{r iy1 d}. Last year I [read]{r eh1 d} Anna Karenina by [Tol|stoy]{t ow1 l|s t oy2}."' \
--form 'user_audio_file=@"ilovetoread.mp3"' \
--form 'markup_language="arpa_mark"'
```

{% endcode %}
{% endtab %}
{% endtabs %}

Notice the different phonemes for both instances of the word "read" in the sentence and compare them with the phonemes present in the response for the same words.

{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "status": "success",
  "quota_remaining": -1,
  "text_score": {
    "text": "I love to read. Last year I read Anna Karenina by Tolstoy.",
    "word_score_list": [
    {....<word score for other words},
    {
        "word": "read",
        "quality_score": 100,
        "phone_score_list": [
          {
            "phone": "r",
            "stress_level": null,
            "extent": [
              63,
              72
            ],
            "quality_score": 99.33333333333333,
            "sound_most_like": "r"
          },
          {
            "phone": "iy",
            "stress_level": 1,
            "extent": [
              72,
              87
            ],
            "quality_score": 100,
            "stress_score": 100,
            "predicted_stress_level": 1,
            "sound_most_like": "iy"
          },
          {
            "phone": "d",
            "stress_level": null,
            "extent": [
              87,
              99
            ],
            "quality_score": 100,
            "sound_most_like": "d"
          }
        ],
        "ending_punctuation": ".",
        "syllable_score_list": [
          {
            "phone_count": 3,
            "stress_level": 1,
            "letters": "read",
            "quality_score": 100,
            "stress_score": 100,
            "predicted_stress_level": 1,
            "extent": [
              63,
              99
            ]
          }
        ]
      },
      {....<word score for other words},
      {
        "word": "read",
        "quality_score": 84,
        "phone_score_list": [
          {
            "phone": "r",
            "stress_level": null,
            "extent": [
              213,
              222
            ],
            "quality_score": 99.66666666666667,
            "sound_most_like": "r"
          },
          {
            "phone": "eh",
            "stress_level": 1,
            "extent": [
              222,
              231
            ],
            "quality_score": 55.222222222222214,
            "stress_score": 100,
            "predicted_stress_level": 1,
            "sound_most_like": "iy"
          },
          {
            "phone": "d",
            "stress_level": null,
            "extent": [
              231,
              240
            ],
            "quality_score": 97.33333333333333,
            "sound_most_like": "d"
          }
        ],
        "syllable_score_list": [
          {
            "phone_count": 3,
            "stress_level": 1,
            "letters": "read",
            "quality_score": 84,
            "stress_score": 100,
            "predicted_stress_level": 1,
            "extent": [
              213,
              240
            ]
          }
        ]
      },
      {....<word score for other words},
      ],
    "ielts_score": {
      "pronunciation": 8.5
    },
    "pte_score": {
      "pronunciation": 83
    },
    "speechace_score": {
      "pronunciation": 94
    }
  },
  "version": "9.1"
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.speechace.com/api-reference/score-text-markup-language.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.