# Improving transcription accuracy with medical custom vocabularies
To improve transcription accuracy in Amazon Transcribe Medical, create and use one or more medical custom vocabularies. A *custom vocabulary* is a collection of words or phrases that are domain-specific. This collection helps improve the performance of Amazon Transcribe Medical in transcribing those words or phrases.
You are responsible for the integrity of your own data when you use Amazon Transcribe Medical. Do not enter confidential information, personal information (PII), or protected health information (PHI), into a custom vocabulary.
For best results, create separate small custom vocabularies that each help transcribe a specific audio recording. You receive greater improvements in transcription accuracy than if you created one large custom vocabulary to use with all of your recordings.
By default, you can have up to 100 custom vocabularies in your AWS account. A custom vocabulary can't exceed 50 KB in size. For information on requesting an increase to the number of custom vocabularies that you can have in your AWS account, see [AWS service quotas](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html).
Custom vocabularies are available in US English (en-US).
**Topics**
+ [Creating a text file for your medical custom vocabulary](create-med-vocab-text.md)
+ [Using a text file to create a medical custom vocabulary](create-med-custom-vocabulary.md)
+ [Transcribing an audio file using a medical custom vocabulary](start-med-custom-vocab-job.md)
+ [Transcribing a real-time stream using a medical custom vocabulary](start-med-vocab-stream.md)
+ [Character set for Amazon Transcribe Medical](charsets-med.md)
# Creating a text file for your medical custom vocabulary
To create a custom vocabulary, you create a text file that is in UTF-8 format. In this file, you create a four column table, with each column specifying a field. Each field tells Amazon Transcribe Medical either how the domain-specific terms are pronounced or how to display these terms in your transcriptions. You store the text file containing these fields in an Amazon S3 bucket.
## Understanding how to format your text file
To create a medical custom vocabulary, you enter the column names as a header row. You enter the values for each column beneath the header row.
The following are the names of the four columns of the table:
+ `Phrase` – column required, values required
+ `IPA` – column required, values can be optional
+ `SoundsLike` – column required, values can be optional
+ `DisplayAs` – column required, values can be optional
When you create a custom vocabulary, make sure that you:
+ Separate each column with a single Tab character. Amazon Transcribe throws an error message if you try to separate the columns with spaces or multiple Tab characters.
+ Make sure that there's no trailing spaces or white space after each value within a column.
Make sure that the values that you enter for each column:
+ Have fewer than 256 characters, including hyphens
+ Use only characters from the allowed character set, see [Character set for Amazon Transcribe Medical](charsets-med.md).
## Entering values for the columns of the table
The following information shows you how to specify values for the four columns of the table:
+ `Phrase` – The word or phrase that should be recognized. You must enter values in this column.
If the entry is a phrase, separate the words with a hyphen (-). For example, enter **cerebral autosomal dominant arteriopathy with subcortical infarcts and leukoencephalopathy** as **cerebral-autosomal-dominant-arteriopathy-with-subcortical-infarcts-and-leukoencephalopathy**.
Enter acronyms or other words whose letters should be pronounced individually as single letters followed by dots, such as **D.N.A.** or **S.T.E.M.I.**. To enter the plural form of an acronym, such as "STEMIs," separate the "s" from the acronym with a hyphen: "**S.T.E.M.I-s**" You can use either uppercase or lowercase letters for acronyms.
The `Phrase` column is required. You can use any of the allowed characters for the input language. For allowed characters, see [Character set for Amazon Transcribe Medical](charsets-med.md). If you don't specify the `DisplayAs` column, Amazon Transcribe Medical uses the contents of the `Phrase` column in the output file.
+ `IPA` (column required, values can be optional) – To specify the pronunciation of a word or phrase, you can include characters in the [International Phonetic Alphabet (IPA)](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet) in this column. The `IPA` column can't contain leading or trailing spaces, and you must use a single space to separate each phoneme in the input. For example, in English you would enter the phrase **acute-respiratory-distress-syndrome** as **ə k j u t ɹ ɛ s p ɪ ɹ ə t ɔ ɹ i d ɪ s t ɹ ɛ s s ɪ n d ɹ oʊ m**. You would enter the phrase **A.L.L.** as **eɪ ɛ l ɛ l**.
Even if you don't specify the contents of the `IPA` column, you must include a blank `IPA` column. If you include values in the `IPA` column, you can't provide values for the `SoundsLike` column.
For a list of allowed IPA characters for a specific language, see [Character set for Amazon Transcribe Medical](charsets-med.md). US English is the only language available in Amazon Transcribe Medical.
+ `SoundsLike` (column required, values can be optional) – You can break a word or phrase down into smaller segments and provide a pronunciation for each segment using the standard orthography of the language to mimic the way that the word sounds. For example, you can provide pronunciation hints for the phrase **cerebral-autosomal-dominant-arteriopathy-with-subcortical-infarcts-and-leukoencephalopathy** like this: **sir-e-brul-aut-o-som-ul-dah-mi-nant-ar-ter-ri-o-pa-thy-with-sub-cor-ti-cul-in-farcts-and-lewk-o-en-ce-phul-ah-pu-thy**. The hint for the phrase **atrioventricular-nodal-reentrant-tachycardia** would look like this: **ay-tree-o-ven-trick-u-lar-node-al-re-entr-ant-tack-ih-card-ia**. You separate each part of the hint with a hyphen (-).
Even if you don't provide values for the `SoundsLike` column, you must include a blank `SoundsLike` column. If you include values in the `SoundsLike` column, you can't provide values for the `IPA` column.
You can use any of the allowed characters for the input language. For the list of allowed characters, see [Character set for Amazon Transcribe Medical](charsets-med.md).
+ `DisplayAs` (column required, values can be optional) – Defines how the word or phrase looks when it's output. For example, if the word or phrase is **cerebral-autosomal-dominant-arteriopathy-with-subcortical-infarcts-and-leukoencephalopathy**, you can specify the display form as `cerebral autosomal dominant arteriopathy with subcortical infarcts and leukoencephalopathy`, so that the hyphen is not present. You can also specify `DisplayAs` as `CADASIL` if you'd like to show the acronym instead of the full term in the output.
If you don't specify the `DisplayAs` column, Amazon Transcribe Medical uses the `Phrase` column from the input file in the output.
You can use any UTF-8 character in the `DisplayAs` column.
You can include spaces only for the values in the `IPA` and `DisplayAs` columns.
To create the text file of your custom vocabulary, place each word or phrase in your text file on a separate line. Separate the columns with Tab characters. Include spaces only for values in the `IPA` and `DisplayAs` columns. Save the file with the extension `.txt` in an Amazon S3 bucket in the same AWS Region where you use Amazon Transcribe Medical to create your custom vocabulary.
If you edit your text file in Windows, make sure that your file is in `LF` format and not in `CRLF` format. Otherwise, you will be unable to create your custom vocabulary. Some text editors enable you to change the formatting with Find and Replace commands.
The following examples show text that you can use to create custom vocabularies. To create a custom vocabulary from these examples, copy an example into a text editor, replace `[TAB]` with a Tab character, and upload the saved text file to Amazon S3.
```
Phrase[TAB]IPA[TAB]SoundsLike[TAB]DisplayAs
acute-respiratory-distress-syndrome[TAB][TAB][TAB]acute respiratory distress syndrome
A.L.L.[TAB]eɪ ɛ l ɛ l[TAB][TAB]ALL
atrioventricular-nodal-reentrant-tachycardia[TAB][TAB]ay-tree-o-ven-trick-u-lar-node-al-re-entr-ant-tack-ih-card-ia[TAB]
```
You can enter columns in any order. The following examples show other valid structures for the custom vocabulary input file.
```
Phrase[TAB]SoundsLike[TAB]IPA[TAB]DisplayAs
acute-respiratory-distress-syndrome[TAB][TAB][TAB]acute respiratory distress syndrome
A.L.L.[TAB][TAB]eɪ ɛ l ɛ l[TAB]ALL
atrioventricular-nodal-reentrant-tachycardia[TAB]ay-tree-o-ven-trick-u-lar-node-al-re-entr-ant-tack-ih-card-ia[TAB][TAB]
```
```
DisplayAs[TAB]SoundsLike[TAB]IPA[TAB]Phrase
acute respiratory distress syndrome[TAB][TAB][TAB]acute-respiratory-distress-syndrome
ALL[TAB][TAB]eɪ ɛ l ɛ l[TAB]A.L.L.
[TAB]ay-tree-o-ven-trick-u-lar-node-al-re-entr-ant-tack-ih-card-ia[TAB][TAB]atrioventricular-nodal-reentrant-tachycardia
```
For reading ease, the following tables show the preceding examples more clearly in html format. They are meant only to illustrate the examples.
| Phrase | IPA | SoundsLike | DisplayAs |
| --- | --- | --- | --- |
| acute-respiratory-distress-syndrome | | | acute respiratory distress syndrome |
| A.L.L. | eɪ ɛ l ɛ l | | ALL |
| atrioventricular-nodal-reentrant-tachycardia | | ay-tree-o-ven-trick-u-lar-node-al-re-entr-ant-tack-ih-card-ia | |
| Phrase | SoundsLike | IPA | DisplayAs |
| --- | --- | --- | --- |
| acute-respiratory-distress-syndrome | | | acute respiratory distress syndrome |
| atrioventricular-nodal-reentrant-tachycardia | ay-tree-o-ven-trick-u-lar-node-al-re-entr-ant-tack-ih-card-ia | | |
| A.L.L. | | eɪ ɛ l ɛ l | ALL |
| DisplayAs | SoundsLike | IPA | Phrase |
| --- | --- | --- | --- |
| acute respiratory distress syndrome | | | acute-respiratory-distress-syndrome |
| ALL | | eɪ ɛ l ɛ l | A.L.L. |
| | ay-tree-o-ven-trick-u-lar-node-al-re-entr-ant-tack-ih-card-ia | | atrioventricular-nodal-reentrant-tachycardia |
# Using a text file to create a medical custom vocabulary
To create a custom vocabulary, you must have prepared a text file that contains a collection a words or phrases. Amazon Transcribe Medical uses this text file to create a custom vocabulary that you can use to improve the transcription accuracy of those words or phrases. You can create a custom vocabulary using the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_CreateMedicalVocabulary.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_CreateMedicalVocabulary.html) API or the Amazon Transcribe Medical console.
## AWS Management Console
To use the AWS Management Console to create a custom vocabulary, you provide the Amazon S3 URI of the text file containing your words or phrases.
1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/transcribe/).
1. In the navigation pane, under Amazon Transcribe Medical, choose **Custom vocabulary**.
1. For **Name**, under **Vocabulary settings**, choose a name for your custom vocabulary.
1. Specify the location of your audio file or video file in Amazon S3:
+ For **Vocabulary input file location on S3** under **Vocabulary settings**, specify the Amazon S3 URI that identifies the text file you will use to create your custom vocabulary.
+ For **Vocabulary input file location in S3**, choose **Browse S3** to browse for the text file and choose it.
1. Choose **Create vocabulary**.
You can see the processing status of your custom vocabulary in the AWS Management Console.
## API
**To create a medical custom vocabulary (API)**
+ For the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartTranscriptionJob.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartTranscriptionJob.html) API, specify the following.
1. For `LanguageCode`, specify `en-US`.
1. For `VocabularyFileUri`, specify the Amazon S3 location of the text file that you use to define your custom vocabulary.
1. For `VocabularyName`, specify a name for your custom vocabulary. The name you specify must be unique within your AWS account.
To see the processing status of your custom vocabulary, use the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_GetMedicalVocabulary.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_GetMedicalVocabulary.html) API.
The following is an example request using the AWS SDK for Python (Boto3) to create a custom vocabulary.
```
from __future__ import print_function
import time
import boto3
transcribe = boto3.client('transcribe', 'us-west-2')
vocab_name = "my-first-vocabulary"
response = transcribe.create_medical_vocabulary(
VocabularyName = job_name,
VocabularyFileUri = 's3://amzn-s3-demo-bucket/my-vocabularies/my-vocabulary-table.txt'
LanguageCode = 'en-US',
)
while True:
status = transcribe.get_medical_vocabulary(VocabularyName = vocab_name)
if status['VocabularyState'] in ['READY', 'FAILED']:
break
print("Not ready yet...")
time.sleep(5)
print(status)
```
## AWS CLI
**To enable speaker partitioning in a batch transcription job (AWS CLI)**
+ Run the following code.
```
aws transcribe create-medical-vocabulary \
--vocabulary-name my-first-vocabulary \
--vocabulary-file-uri s3://amzn-s3-demo-bucket/my-vocabularies/my-vocabulary-file.txt \
--language-code en-US
```
# Transcribing an audio file using a medical custom vocabulary
Use the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartMedicalTranscriptionJob.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartMedicalTranscriptionJob.html) or the AWS Management Console to start a transcription job that uses a custom vocabulary to improve transcription accuracy.
## AWS Management Console
1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/transcribe/).
1. In the navigation pane, under Amazon Transcribe Medical, choose **Transcription jobs**.
1. Choose **Create job**.
1. On the **Specify job details** page, provide information about your transcription job.
1. Choose **Next**.
1. Under **Customization**, enable **Custom vocabulary**.
1. Under **Vocabulary selection**, choose a custom vocabulary.
1. Choose **Create**.
## API
**To enable speaker partitioning in an audio file using a batch transcription job (API)**
+ For the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartMedicalTranscriptionJob.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_StartMedicalTranscriptionJob.html) API, specify the following.
1. For `MedicalTranscriptionJobName`, specify a name that is unique in your AWS account.
1. For `LanguageCode`, specify the language code that corresponds to the language spoken in your audio file and the language of your vocabulary filter.
1. For the `MediaFileUri` parameter of the `Media` object, specify the name of the audio file that you want to transcribe.
1. For `Specialty`, specify the medical specialty of the clinician speaking in the audio file.
1. For `Type`, specify whether the audio file is a conversation or a dictation.
1. For `OutputBucketName`, specify the Amazon S3 bucket to store the transcription results.
1. For the `Settings` object, specify the following.
1. `VocabularyName` – the name of your custom vocabulary.
The following request uses the AWS SDK for Python (Boto3) to start a batch transcription job with a custom vocabulary.
```
from __future__ import print_function
import time
import boto3
transcribe = boto3.client('transcribe', 'us-west-2')
job_name = "my-first-med-transcription-job"
job_uri = "s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac"
transcribe.start_medical_transcription_job(
MedicalTranscriptionJobName = job_name,
Media = {
'MediaFileUri': job_uri
},
OutputBucketName = 'amzn-s3-demo-bucket',
OutputKey = 'my-output-files/',
LanguageCode = 'en-US',
Specialty = 'PRIMARYCARE',
Type = 'CONVERSATION',
Settings = {
'VocabularyName': 'example-med-custom-vocab'
}
)
while True:
status = transcribe.get_medical_transcription_job(MedicalTranscriptionJobName = job_name)
if status['MedicalTranscriptionJob']['TranscriptionJobStatus'] in ['COMPLETED', 'FAILED']:
break
print("Not ready yet...")
time.sleep(5)
print(status)
```
# Transcribing a real-time stream using a medical custom vocabulary
To improve transcription accuracy in a real-time stream, you can use a custom vocabulary using either HTTP/2 or WebSocket streams. To start an HTTP/2 request, use the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartMedicalStreamTranscription.html) API. You can use a custom vocabulary in real-time using either the AWS Management Console, the [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartMedicalStreamTranscription.html) API, or by using the WebSocket protocol.
## Transcribing a dictation that is spoken into your Microphone (AWS Management Console)
To use the AWS Management Console to transcribe streaming audio of a medical dictation, choose the option to transcribe a medical dictation, start the stream, and begin speaking into the microphone.
**To transcribe streaming audio of a medical dictation (AWS Management Console)**
1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/transcribe/).
1. In the navigation pane, under Amazon Transcribe Medical, choose **Real-time transcription**.
1. For **Medical specialty**, choose the medical specialty of the clinician speaking in the stream.
1. For **Audio input type**, choose either **Conversation** or **Dictation**.
1. For **Additional settings**, choose **Custom vocabulary**.
1. For **Vocabulary selection**, choose the custom vocabulary.
1. Choose **Start streaming**.
1. Speak into the microphone.
## Enabling speaker partitioning in an HTTP/2 stream
The following is the syntax for the parameters of an HTTP/2 request.
```
POST /medical-stream-transcription HTTP/2
host: transcribestreaming.us-west-2.amazonaws.com
authorization: Generated value
x-amz-target: com.amazonaws.transcribe.Transcribe.StartMedicalStreamTranscription
x-amz-content-sha256: STREAMING-MED-AWS4-HMAC-SHA256-EVENTS
x-amz-date: 20220208T235959Z
x-amzn-transcribe-session-id: my-first-http2-med-stream
x-amzn-transcribe-language-code: en-US
x-amzn-transcribe-media-encoding: flac
x-amzn-transcribe-sample-rate: 16000
x-amzn-transcribe-vocabulary-name: my-first-med-vocab
x-amzn-transcribe-specialty: PRIMARYCARE
x-amzn-transcribe-type: CONVERSATION
x-amzn-transcribe-show-speaker-label: true
Content-type: application/vnd.amazon.eventstream
transfer-encoding: chunked
```
Parameter descriptions:
+ **host**: Update the AWS Region ('us-west-2' in the preceding example) with the AWS Region you are calling. For a list of valid AWS Regions, see [AWS Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#transcribe_region).
+ **authorization**: This is a generated field. To learn more about creating a signature, see [Signing AWS requests with Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html).
+ **x-amz-target**: Don't alter this field; use the content shown in the preceding example.
+ **x-amz-content-sha256**: This is a generated field. To learn more about calculating a signature, see [Signing AWS requests with Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html).
+ **x-amz-date**: The date and time the signature is created. The format is YYYYMMDDTHHMMSSZ, where YYYY=year, MM=month, DD=day, HH=hour, MM=minute, SS=seconds, and 'T' and 'Z' are fixed characters. For more information, refer to [Handling Dates in Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4-date-handling.html).
+ **x-amzn-transcribe-session-id**: The name for your streaming session.
+ **x-amzn-transcribe-language-code**: The encoding used for your input audio. Refer to [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_streaming_StartMedicalStreamTranscription.html) or [Supported languages and language-specific features](supported-languages.md) for a list of valid values.
+ **x-amzn-transcribe-media-encoding**: The encoding used for your input audio. Valid values are `pcm`, `ogg-opus`, and `flac`.
+ **x-amzn-transcribe-sample-rate**: The sample rate of the input audio (in Hertz). Amazon Transcribe supports a range from 8,000 Hz to 48,000 Hz. Low-quality audio, such as telephone audio, is typically around 8,000 Hz. High-quality audio typically ranges from 16,000 Hz to 48,000 Hz. Note that the sample rate you specify **must** match that of your audio.
+ **x-amzn-transcribe-vocabulary-name**: The name of the vocabulary you want to use with your transcription.
+ **x-amzn-transcribe-specialty**: The medical specialty being transcribed.
+ **x-amzn-transcribe-type**: Choose whether this is a dictation or a conversation.
+ **x-amzn-transcribe-show-speaker-label**: To enable diarization, this value must be `true`.
+ **content-type**: Don't alter this field; use the content shown in the preceding example.
## Enabling speaker partitioning in a WebSocket request
To partition speakers in WebSocket streams with the API, use the following format to create a pre-signed URI to start a WebSocket request and set `vocabulary-name` to the name of the custom vocabulary.
```
GET wss://transcribestreaming.us-west-2.amazonaws.com:8443/medical-stream-transcription-websocket
?language-code=en-US
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20220208%2Fus-west-2%2Ftranscribe%2Faws4_request
&X-Amz-Date=20220208T235959Z
&X-Amz-Expires=300
&X-Amz-Security-Token=security-token
&X-Amz-Signature=Signature Version 4 signature
&X-Amz-SignedHeaders=host
&media-encoding=flac
&sample-rate=16000
&session-id=sessionId
&specialty=medicalSpecialty
&type=CONVERSATION
&vocabulary-name=vocabularyName
&show-speaker-label=boolean
```
# Character set for Amazon Transcribe Medical
To use custom vocabularies in Amazon Transcribe Medical, use the following character set.
## English character set
For English custom vocabularies, you can use the following characters in the `Phrase` and `SoundsLike` columns:
+ a - z
+ A - Z
+ ' (apostrophe)
+ - (hyphen)
+ . (period)
You can use the following International Phonetic Alphabet (IPA) characters in the `IPA` column of the vocabulary input file.
| Character | Code | Character | Code |
| --- | --- | --- | --- |
| aʊ | 0061 028A | w | 0077 |
| aɪ | 0061 026A | z | 007A |
| b | 0062 | æ | 00E6 |
| d | 0064 | ð | 00F0 |
| eɪ | 0065 026A | ŋ | 014B |
| f | 0066 | ɑ | 0251 |
| g | 0067 | ɔ | 0254 |
| h | 0068 | ɔɪ | 0254 026A |
| i | 0069 | ə | 0259 |
| j | 006A | ɛ | 025B |
| k | 006B | ɝ | 025D |
| l | 006C | ɡ | 0261 |
| l̩ | 006C 0329 | ɪ | 026A |
| m | 006D | ɹ | 0279 |
| n | 006E | ʃ | 0283 |
| n̩ | 006E 0329 | ʊ | 028A |
| oʊ | 006F 028A | ʌ | 028C |
| p | 0070 | ʍ | 028D |
| s | 0073 | ʒ | 0292 |
| t | 0074 | ʤ | 02A4 |
| u | 0075 | ʧ | 02A7 |
| v | 0076 | θ | 03B8 |