### Speech Verification API

Source: https://docs.soapboxlabs.com/quickstart

The Verification API analyzes audio files to verify speaker identity against target prompts.

```APIDOC
## POST /v1/speech/verification

### Description
Analyzes audio files to verify speaker identity against target prompts.

### Method
POST

### Endpoint
`https://api.soapboxlabs.com/v1/speech/verification`

### Parameters
#### Request Body
- **file** (file) - Required - The audio file to analyze.
- **user_token** (string) - Required - A unique identifier for the speaker.
- **category** (string) - Required - The target prompt to search for within the audio.

### Request Example
```bash
curl -H "x-app-key:APP_KEY_HERE" \
     -F "file=@AudioFile.wav" \
     -F "user_token=USER_TOKEN_HERE" \
     -F "category=orange" \
     https://api.soapboxlabs.com/v1/speech/verification
```

### Response
#### Success Response (200)
- **verification_results** (object) - Details of the verification analysis.
```

--------------------------------

### Fluency API

Source: https://docs.soapboxlabs.com/quickstart

The Fluency API analyzes submitted audio files to provide an extra layer of analysis.

```APIDOC
## POST /v1/speech/fluency

### Description
Analyzes submitted audio files to provide an extra layer of analysis on top of STT.

### Method
POST

### Endpoint
`https://api.soapboxlabs.com/v1/speech/fluency`

### Parameters
#### Request Body
- **file** (file) - Required - The audio file to process.
- **reference_text** (file) - Required - The reference text for comparison.
- **model_id** (string) - Required - The ID of the model to use.
- **user_token** (string) - Required - A unique identifier for the speaker.

### Request Example
```bash
curl -H "x-app-key:APP_KEY_HERE" \
     -F "file=@AudioFile.wav" \
     -F "reference_text=@ReferenceText.txt" \
     -F "model_id=MODEL_ID" \
     -F "user_token=USER_TOKEN_HERE" \
     https://api.soapboxlabs.com/v1/speech/fluency
```

### Response
#### Success Response (200)
- **analysis** (object) - Details of the fluency analysis.
```

--------------------------------

### Speech-To-Text (STT) API

Source: https://docs.soapboxlabs.com/quickstart

The Speech-To-Text API transcribes spoken audio into text.

```APIDOC
## POST /v1/speech/recognition

### Description
Transcribes spoken audio into text using the Speech-To-Text solution.

### Method
POST

### Endpoint
`https://api.soapboxlabs.com/v1/speech/recognition`

### Parameters
#### Request Body
- **file** (file) - Required - The audio file to transcribe.
- **model_id** (string) - Required - The ID of the model to use.
- **user_token** (string) - Required - A unique identifier for the speaker.

### Request Example
```bash
curl -H "x-app-key:APP_KEY_HERE" \
     -F "file=@AudioFile.wav" \
     -F "model_id=CLM_ID" \
     -F "user_token=USER_TOKEN_HERE" \
     https://api.soapboxlabs.com/v1/speech/recognition
```

### Response
#### Success Response (200)
- **transcription** (string) - The transcribed text.
```

--------------------------------

### Send Audio for Fluency Analysis using CURL

Source: https://docs.soapboxlabs.com/quickstart

This command sends an audio file and reference text to the Fluency API for analysis. It requires an App Key, the audio file, reference text file, a model ID, and a user token. The API returns a JSON response detailing the fluency analysis.

```bash
curl -H "x-app-key:APP_KEY_HERE" \
  -F "file=@AudioFile.wav" \
  -F "reference_text=@ReferenceText.txt" \
  -F "model_id=MODEL_ID" \
  -F "user_token=USER_TOKEN_HERE" \
  https://api.soapboxlabs.com/v1/speech/fluency
```

--------------------------------

### Markup Element Example

Source: https://docs.soapboxlabs.com/guides-%26-tutorials/customizing-text-using-markup

Illustrates the structure of a basic markup element, demonstrating how opening and closing tags with content are used to define a specific instruction for an engine. It shows an example of how to bold text using a '<bold>' tag.

```text
_I will follow up_`<bold>` _asap_`</bold>`
```

--------------------------------

### Text Normalization Example

Source: https://docs.soapboxlabs.com/guides-%26-tutorials/customizing-text-using-markup

Shows a before and after example of text normalization, illustrating common transformations like stripping punctuation, lowercasing, and converting digits to words. The example converts '“I have 2 you can borrow,” she said.' to 'i have two you can borrow she said'.

```text
_“I have 2 you can borrow,” she said._ → _i have two you can borrow she said_
```

--------------------------------

### Send Audio for Speech Verification using CURL

Source: https://docs.soapboxlabs.com/quickstart

This command sends an audio file to the Speech Verification API to check for specific target prompts. It requires an App Key, the audio file, a user token, and one or more category values representing the target prompts. The API returns a JSON response with scoring details.

```bash
curl -H "x-app-key:APP_KEY_HERE" \
  -F "file=@AudioFile.wav" \
  -F "user_token=USER_TOKEN_HERE" \
  -F "category=orange" \
  https://api.soapboxlabs.com/v1/speech/verification
```

--------------------------------

### Example Calculation of Phoneme Pitch Indices

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29/fluency-prosody-features

This example applies the pitch index calculation formula to find the start and end indices for the phoneme 'ay' within the word 'like', using a pitch interval of 0.01 seconds.

```mathematics
start_pitch_index = ((2.25 / 0.01) - (2.04 / 0.01)) - 1
start_pitch_index = (225 - 204) - 1
start_pitch_index = 20

end_pitch_index = (2.46 / 0.01) - (2.04 / 0.01) - 1
end_pitch_index = (246 - 204) - 1
end_pitch_index = 41
```

--------------------------------

### Send Audio for Speech-To-Text (STT) Recognition using CURL

Source: https://docs.soapboxlabs.com/quickstart

This command sends an audio file to the STT API for speech recognition. It requires an App Key, the audio file, a model ID, and a user token. The API returns a JSON response with the transcribed text.

```bash
curl -H "x-app-key:APP_KEY_HERE" \
  -F "file=@AudioFile.wav" \
  -F "model_id=CLM_ID" \
  -F "user_token=USER_TOKEN_HERE" \
  https://api.soapboxlabs.com/v1/speech/recognition
```

--------------------------------

### C# Integration Example for Soapbox Labs Libraries

Source: https://docs.soapboxlabs.com/technical-docs/on-device-%28edgeai%29-technical-documentation/verification-%28on-device%29

This C# code sample demonstrates a minimal working example of integrating Soapbox Labs libraries. It shows how to import native methods for engine initialization, status checking, and audio verification, along with handling file input and target matching. Ensure the correct paths to the SBL library, models archive, and audio file are provided.

```csharp
using System;
using System.IO;
using System.Runtime.InteropServices;

namespace SBLOfflineTest {
    class SBL {
        // import the SBL library and setup native lib method signature hook
        [DllImport("LOCATION-OF-SBL-LIBRARY")]
        public static extern string Engine_init(string x);
        [DllImport("LOCATION-OF-SBL-LIBRARY")]
        public static extern string Engine_access_status();
        [DllImport("LOCATION-OF-SBL-LIBRARY")]
        public static extern string Verification_run(byte[] x, int y, string[] z, string model_key);
        
        // entry point
        static void Main(string[] args) {
            // set the verification targets.
            // these are the targets/prompts you would like to search for in the audio file.
            // in this case we are checking for the target "right" in the audio file
            // add null to denote the end of the array (WIP)
            string[] targets = {"right", null};
            
            // run business logic
            try {
                // initialise the engine. this is mandatory. 
                // the location of the models archive should be passed as a parameter
                // the engine will initialise and load the models into memory
                string init = Engine_init("LOCATION-OF-MODELS-ARCHIVE");
                Console.WriteLine(init);
                
                // check engine status - optional
                string status = Engine_access_status();
                Console.WriteLine(status);
                
                // read in the test audio file as a byte array
                string path = @"LOCATION-OF-AUDIO-FILE";
                byte[] bytes = File.ReadAllBytes(path);
                
                // run the audio verification service, passing the audio byte array 
                // and the list of targets to check for
                Console.WriteLine("Running Verification");
                string result = Verification_run(bytes, bytes.Length, targets, "");
                Console.WriteLine("Result: " + result);
            }
            catch (Exception e) {
                Console.WriteLine($"An error occurred - '{e}'");
            }
        }
    }
}
```

--------------------------------

### Markup Element with Attribute Example

Source: https://docs.soapboxlabs.com/guides-%26-tutorials/customizing-text-using-markup

Demonstrates how to use attributes within an opening tag to provide additional information to the parsing engine. This example shows a '<link>' tag with a 'url' attribute to create a hyperlink.

```text
_Please visit my website_`<link url = "mywebsite.me">` _here_`</link>`
```

--------------------------------

### Example Phoneme Data JSON Structure

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature/working-with-short-sounds

This JSON snippet illustrates the structure of data representing individual phonemes within a word, including their start and end times, duration, quality score, and the specific phoneme identifier. This format is used to analyze spoken sounds.

```json
{
    "duration": 0.24,
    "quality_score": 64,
    "end": 0.93,
    "start": 0.69,
    "phone": "d"
}
```

--------------------------------

### Hyperlink Markup with Attribute Example

Source: https://docs.soapboxlabs.com/guides-%26-tutorials/customizing-text-using-markup

Illustrates how to use a 'link' markup tag with a 'url' attribute to create a hyperlink. The example shows the original text with markup and the rendered output where 'here' becomes a clickable link to the specified URL. This requires an engine that supports the 'link' tag and 'url' attribute.

```plaintext
_Please visit my website_`<link url = "mywebsite.me">` _here_`</link>`

_Please visit my website _here__
```

--------------------------------

### Specify Letter Pronunciation with <letter pronunciation='...'>

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature/letter-name-examples

This example shows how to use the `pronunciation` attribute within the `<letter>` tag to enforce a specific pronunciation for a letter. This is useful for letters with multiple common pronunciations. The JSON output reflects the specified pronunciation.

```xml
<letter pronunciation="ey"> a </letter>
or
<letter pronunciation="ah"> a </letter>
```

```json
{
  "results": [
    {
      "hypothesis_score": 94,
      "duration": 2.46,
      "hypothesis_duration": 0.69,
      "category": "a",
      "end": 1.83,
      "start": 1.14,
      "word_breakdown": [
        {
          "duration": 0.69,
          "quality_score": 94,
          "token_type": "letter",
          "end": 1.83,
          "start": 1.14,
          "phone_breakdown": [
            {
              "duration": 0.69,
              "quality_score": 91,
              "end": 1.83,
              "start": 1.14,
              "phone": "ey"
            }
          ],
          "word": "a",
          "target_transcription": "ey"
        }
      ]
    }
  ]
}
```

--------------------------------

### STT API Full JSON Response Example

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/speech-to-text-%28online%29

This is a complete example of the JSON response received from the STT Web Service upon successful audio analysis. It includes all fields: user_id, language_code, result_id, time, audio_duration, num_alternatives, and a detailed 'results' array containing transcription and word-level data.

```json
{
  "audio_duration": 5.1363749504089355,
  "user_id": "abc123",
  "results": [
    {
      "confidence": 87.196960449219,
      "transcription": "i like stripes",
      "words": [
        {
          "confidence": 86.65843963623047,
          "end": 1.8,
          "start": 1.17,
          "phone_breakdown": [
            {
              "quality_score": 82.96692657470703,
              "end": 1.8,
              "start": 1.17,
              "phone": "ay"
            }
          ],
          "word": "i"
        },
        {
          "confidence": 82.57804870605469,
          "end": 2.79,
          "start": 2.04,
          "phone_breakdown": [
            {
              "quality_score": 91.5013198852539,
              "end": 2.25,
              "start": 2.04,
              "phone": "l"
            },
            {
              "quality_score": 69.76779174804688,
              "end": 2.46,
              "start": 2.25,
              "phone": "ay"
            },
            {
              "quality_score": 74.07825469970703,
              "end": 2.79,
              "start": 2.46,
              "phone": "k"
            }
          ],
          "word": "like"
        },
        {
          "confidence": 92.35440063476562,
          "end": 4.62,
          "start": 3.0,
          "phone_breakdown": [
            {
              "quality_score": 91.634033203125,
              "end": 3.21,
              "start": 3.0,
              "phone": "s"
            },
            {
              "quality_score": 95.79405975341797,
              "end": 3.3,
              "start": 3.21,
              "phone": "t"
            },
            {
              "quality_score": 97.87104034423828,
              "end": 3.39,
              "start": 3.3,
              "phone": "r"
            },
            {
              "quality_score": 95.29679870605469,
              "end": 3.51,
              "start": 3.39,
              "phone": "ay"
            },
            {
              "quality_score": 98.2538070678711,
              "end": 3.72,
              "start": 3.51,
              "phone": "p"
            },
            {
              "quality_score": 66.72088623046875,
              "end": 4.62,
              "start": 3.72,
              "phone": "s"
            }
          ],
          "word": "stripes"
        }
      ]
    }
  ],
  "num_alternatives": 1,
  "language_code": "en-GB",
  "result_id": "abc123-282_1638878309646",
  "time": "2021-12-07T11:58:30.257Z"
}
```

--------------------------------

### Use <sound-out> with Optional Pronunciation Attribute

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature

Demonstrates the optional use of the `pronunciation` attribute with the `<sound-out>` tag. If omitted, the SoapBox Engine provides a default pronunciation. This example shows how to specify a pronunciation for the letter 'a'.

```html
<sound-out pronunciation="aa">a</sound-out>
```

--------------------------------

### JSON Example: Word Transcription with Pitch and Silence Data

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29/fluency-prosody-features

This JSON snippet demonstrates the structure of word transcription data, including normalized word, confidence scores, start and end times, phone breakdowns, and pitch values. It highlights how `time_since_previous` indicates pauses, which can be inferred from the `end` time of the preceding word and the `start` time of the current word. Silence is typically represented by zeroes in the pitch values array during these pauses.

```json
{
    "normalised_word": "very",
    "reference_index": 0,
    "reference_word": "Very",
    "sub_types": {},
    "transcription_details": {
        "confidence": 99.458404541016,
        "end": 1.56,
        "phone_breakdown": [
            {
                "duration": 0.09,
                "end": 1.26,
                "phone": "v",
                "score": 0.09,
                "start": 1.17
            },
            {
                "duration": 0.12,
                "end": 1.38,
                "phone": "eh",
                "score": 0.12,
                "start": 1.26
            },
            {
                "duration": 0.09,
                "end": 1.47,
                "phone": "r",
                "score": 0.09,
                "start": 1.38
            },
            {
                "duration": 0.09,
                "end": 1.56,
                "phone": "iy",
                "score": 0.09,
                "start": 1.47
            }
        ],
        "pitch": {
            "values": [
                263, 262, 260, 259, 258, 258, 259, 260, 262, 264,
                267, 268, 270, 271, 271, 270, 266, 263, 260, 258, 256, 253,
                248, 244, 240, 238, 236, 233, 231, 229, 226, 225, 224, 223,
                222, 222, 221, 220, 220
            ]
        },
        "start": 1.17,
        "time_since_previous": 0
    },
    "transcription_index": 0,
    "transcription_word": "very",
    "type": "CORRECT"}
, {
    "normalised_word": "annoying",
    "reference_index": 1,
    "reference_word": "annoying.",
    "sub_types": {},
    "transcription_details": {
        "confidence": 93.530090332031,
        "end": 2.13,
        "phone_breakdown": [
            {
                "duration": 0.06,
                "end": 1.62,
                "phone": "ah",
                "score": 0.06,
                "start": 1.56
            },
            {
                "duration": 0.06,
                "end": 1.68,
                "phone": "n",
                "score": 0.06,
                "start": 1.62
            },
            {
                "duration": 0.24,
                "end": 1.92,
                "phone": "oy",
                "score": 0.24,
                "start": 1.68
            },
            {
                "duration": 0.06,
                "end": 1.98,
                "phone": "ih",
                "score": 0.06,
                "start": 1.92
            },
            {
                "duration": 0.15,
                "end": 2.13,
                "phone": "ng",
                "score": 0.15,
                "start": 1.98
            }
        ],
        "pitch": {
            "values": [
                220, 220, 220, 221, 223, 225, 226, 226, 228, 229,
                231, 233, 233, 231, 230, 232, 233, 233, 233, 232, 230, 229,
                228, 225, 223, 220, 214, 207, 200, 193, 187, 183, 183
            ]
        },
        "start": 2.13,
        "time_since_previous": 0
    },
    "transcription_index": 1,
    "transcription_word": "annoying",
    "type": "CORRECT"}

```

--------------------------------

### Example JSON Response with Pitch Data

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29/fluency-prosody-features

This JSON snippet illustrates the structure of a response containing pitch information. The 'pitch' object includes an array of 'values' representing pitch in Hertz at word-level, along with 'start' and 'end' times for the word.

```json
{
    "confidence": 99.5146484375,
    "duration": 0.75,
    "end": 2.79,
    "phone_breakdown": [
        {
            "duration": 0.21,
            "end": 2.25,
            "phone": "l",
            "score": 99.620590209961,
            "start": 2.04,
            "top10_phones": []
        },
        {
            "duration": 0.21,
            "end": 2.46,
            "phone": "ay",
            "score": 98.380950927734,
            "start": 2.25,
            "top10_phones": []
        },
        {
            "duration": 0.33,
            "end": 2.79,
            "phone": "k",
            "score": 99.893486022949,
            "start": 2.46,
            "top10_phones": []
        }
    ],
    "phonetic_transcription": "l ay k",
    "pitch": { 
        "values": [
289, 299, 306, 306, 299, 288, 274, 266, 259, 253, 243, 244, 259, 
        253, 246, 242, 237, 232, 230, 230, 228, 226, 225, 223, 221, 221, 221, 
        222, 222, 222, 222, 220, 217, 214, 213, 213, 213, 205, 190, 190, 188, 
        196, 204, 211, 215, 219, 221, 222, 223, 223, 223, 223, 223, 224, 225, 
        226, 228, 229, 230, 231, 232, 233, 234, 236, 237, 238, 239, 240, 242, 
        243, 244, 245, 246, 248, 249
        ]
    },
    "start": 2.04,
    "time_since_previous": 0.24,
    "word": "like"
}
```

--------------------------------

### Bold Text Markup Example

Source: https://docs.soapboxlabs.com/guides-%26-tutorials/customizing-text-using-markup

Demonstrates how to use a 'bold' markup tag to make text appear in bold. It shows the original text with markup and the resulting formatted text. This requires an engine capable of parsing the 'bold' tag.

```plaintext
_I will follow up_`<bold>` _asap_`</bold>`

_I will follow up**asap**_
```

--------------------------------

### Prosody Engine Output Example (JSON)

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29/fluency-prosody-features/example-of-mapping-prosody-data-to-a-rubric

This JSON snippet represents the output from the SoapBox prosody engine for a single word. It includes confidence scores, duration, start and end times, phonetic transcription, and detailed pitch values. The 'time_since_previous' field is useful for analyzing phrasing.

```json
{
    "confidence": 99.51,
    "duration": 0.75,
    "end": 2.79,
    "phone_breakdown": [{...}],
    "phonetic_transcription": "l ay k",
    "pitch": {
        "values": [
            289, 299, 306, 306, 299, 288, 274, 266, 259, 253, 243, 
            244, 259, 253, 246, 242, 237, 232, 230, 230, 228, 226, 225, 223, 
            221, 221, 221, 222, 222, 222, 222, 220, 217, 214, 213, 213, 213, 
            205, 190, 190, 188, 196, 204, 211, 215, 219, 221, 222, 223, 223, 
            223, 223, 223, 224, 225, 226, 228, 229, 230, 231, 232, 233, 234, 
            236, 237, 238, 239, 240, 242, 243, 244, 245, 246, 248, 249
        ]
    },
    "start": 2.04,
    "time_since_previous": 0.24,
    "word": "like"
}
```

--------------------------------

### Self Correction JSON Example with Tripe/Stripes

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29/fluency-self-corrections-feature

This JSON snippet illustrates a self-correction scenario where a child says 'tripe' (an INSERTION) and then corrects to 'stripes' (CORRECT). The 'sub_types' for 'stripes' indicates a 'self_correction' and links to the 'transcription_index' of 'tripe' via 'reparandums'. It shows start and end times, normalized words, and reference details.

```json
{
    "end": 9.69,
    "start": 9.06,
    "normalised_word": "",
    "reference_index": 1,
    "reference_word": "",
    "sub_types": {},
    "transcription_details": {
        "time_since_previous": 0.11
    },
    "transcription_index": 2,
    "transcription_word": "tripe",
    "type": "INSERTION"
}, {
    "end": 10.95,
    "start": 10.23,
    "normalised_word": "stripes",
    "reference_index": 2,
    "reference_word": "stripes",
    "sub_types": {
        "self_correction": {
            "reparandums": [2]
        }
    },
    "transcription_details": {
        "time_since_previous": 0.54
    },
    "transcription_index": 3,
    "transcription_word": "stripes",
    "type": "CORRECT"
}
```

--------------------------------

### C# Engine Initialization for On-Device Verification

Source: https://docs.soapboxlabs.com/technical-docs/on-device-%28edgeai%29-technical-documentation/verification-%28on-device%29

Initializes the Soapbox Labs On-Device verification engine by loading required models into memory. It requires the path to the models archive and returns a status message that should be inspected for successful initialization.

```csharp
string init = Engine_init("LOCATION-OF-MODELS-ARCHIVE");
```

--------------------------------

### Calculating Pitch Index for Phonemes

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29/fluency-prosody-features

This formula demonstrates how to calculate the start and end indices within the pitch values array that correspond to a specific phoneme. It uses the phoneme's start and end times, the word's start time, and the pitch interval duration.

```mathematics
start_pitch_index = ((start_of_phoneme / pitch_interval) - (start_of_word / pitch_interval)) - 1
end_pitch_index = ((end_of_phoneme / pitch_interval) - (start_of_word / pitch_interval)) - 1
```

--------------------------------

### Differentiate Similar Sounds with Multiple <sound-out> Targets

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature

This example illustrates how to handle phonetically similar targets by using multiple `<sound-out>` tags with distinct pronunciations for the same word content. This helps the system differentiate between sounds, such as the 'a' sound represented by 'aa' and 'ah'.

```html
<sound-out pronunciation="aa">aa</sound-out>
<sound-out pronunciation="ah">ah</sound-out>
```

--------------------------------

### Analyze 'x' sound with custom multi-phoneme pronunciation

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature/letter-sound-examples

This example shows how to handle sounds like 'x' that require multiple phonemes (/k/, /s/) for pronunciation. The `<custom-word>` markup is used, and the output includes a single 'quality_score' for 'x' and 'token_type' set to 'custom-word', detailing the breakdown of its constituent phonemes.

```json
{
  "results": [
    {
      "category": "x",
      "hypothesis_score": 93,
      "word_breakdown": [
        {
          "quality_score": 93,
          "target_transcription": "k s",
          "word": "x",
          "token_type": "custom-word",
          "phone_breakdown": [
            {
              "phone": "k",
              "quality_score": 91,
              "end": 0.51,
              "start": 0.39,
              "duration": 0.12
            },
            {
              "phone": "s",
              "quality_score": 88,
              "end": 1.14,
              "start": 0.51,
              "duration": 0.63
            }
          ],
          "end": 1.14,
          "start": 0.39,
          "pitch": {
            "values": []
          },
          "duration": 0.75
        }
      ],
      "end": 1.14,
      "start": 0.39,
      "duration": 1.53,
      "hypothesis_duration": 0.75
    }
  ]
}
```

--------------------------------

### Verify Sounded-Out Word Pronunciation using <sound-out> Tag

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature

This example shows the usage of the `<sound-out>` tag to verify the sounded-out pronunciation of a word. The basic usage without a custom pronunciation is demonstrated here for the word 'dog'.

```html
<sound-out>dog</sound-out>
```

--------------------------------

### Say Individual Letter Name with <letter> Markup

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature/letter-name-examples

This snippet demonstrates how to use the `<letter>` tag to specify a single letter name as a target. The output includes scoring, timing, and breakdown of the spoken letter name.

```xml
<letter>g</letter>
```

```json
{
  "results": [
    {
      "hypothesis_score": 93.0,
      "duration": 2.04,
      "hypothesis_duration": 0.75,
      "category": "g",
      "end": 1.44,
      "start": 0.69,
      "word_breakdown": [
        {
          "duration": 0.75,
          "quality_score": 93.0,
          "token_type": "letter",
          "end": 1.44,
          "start": 0.69,
          "phone_breakdown": [
            {
              "duration": 0.18,
              "quality_score": 88.0,
              "end": 0.87,
              "start": 0.69,
              "phone": "jh"
            },
            {
              "duration": 0.57,
              "quality_score": 92.0,
              "end": 1.44,
              "start": 0.87,
              "phone": "iy"
            }
          ],
          "word": "g",
          "target_transcription": "jh iy"
        }
      ]
    }
  ]
}
```

--------------------------------

### Making a Fluency Request with Last Word Type

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29/fluency-last-word-feature

Example cURL command to make a POST request to the Soapbox Labs API for speech fluency analysis. This example demonstrates how to include the 'last_word_type' form-data to specify how the fluency calculation should end.

```bash
curl -X POST \
  -H "x-app-key:YOUR_API_KEY_HERE" \
  -F "file=@AudioFile.wav" \
  -F "user_token=abc123" \
  -F "reference_text=@ReferenceText.txt" \
  -F "model_id=XXXX" \
  -F "last_word_type=read" \
https://api.soapboxlabs.com/v1/async/request/speech/fluency
```

--------------------------------

### GET /v1/async/results/{id}

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/fluency-%28online%29

Retrieves the results of an asynchronous speech fluency analysis.

```APIDOC
## GET /v1/async/results/{id}

### Description
Retrieves the results of a previously submitted asynchronous speech fluency analysis using the status URI provided in the initial request response. If the results are not yet available, a 404 error will be returned, and you should retry later.

### Method
GET

### Endpoint
`https://api.soapboxlabs.com/v1/async/results/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the analysis request, obtained from the `status_uri`.

### Request Example
```bash
curl https://api.soapboxlabs.com/v1/async/results/abc123
```

### Response
#### Success Response (200)
- **user_id** (string) - The user_id specified in the request.
- **language_code** (string) - The language detected in the audio file.
- **result_id** (string) - A unique identifier for this specific result.
- **time** (string) - The UTC time the request was processed.
- **results** (object) - The detailed fluency results object.
- **audio_duration** (number) - The duration of the audio file in seconds.

#### Response Example
```json
{
  "user_id": "user123",
  "language_code": "en-US",
  "result_id": "abc123",
  "time": "2023-10-27T10:00:00Z",
  "results": {},
  "audio_duration": 60.5
}
```

#### Error Response (404)
- Returned if the results are not yet available. The client should wait and retry the request.
```

--------------------------------

### Verify Letter Sounds using cURL

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature

This cURL command shows how to verify letter sounds (phonemes) with the Short Sounds V1 API. It includes an app key, an audio file, the category marked as '<sound-out>dog</sound-out>', a user token, and a model ID, targeting the speech verification API.

```shell
curl -s -k -H x-app-key:<app-key> -F 'file=@<path-to-audio-file>' -F 'category="<sound-out>dog</sound-out>"' -F user_token=<user-token> -F model_id=<model-id> https://api.soapboxlabs.com/v1/speech/verification
```

--------------------------------

### Verify Custom Word Pronunciation using <custom-word> Tag

Source: https://docs.soapboxlabs.com/technical-docs/online-technical-documentation/verification-%28online%29/short-sounds-feature

This snippet illustrates how to use the `<custom-word>` tag for words not found in the standard dictionary, such as nonsense words. The `pronunciation` attribute is required and must use ARPABET notation. The example verifies the custom word 'foojag'.

```html
<custom-word pronunciation="f uw jh ae g"> foojag </custom-word>
```