Find and Replace

Enable Feature

To enable Find and Replace, use the following parameter in the querystring:

replace=TERM_OR_PHRASE_TO_FIND:REPLACEMENT_TERM_OR_PHRASE

The find term should be always be lowercase and the replacement term can be any case.

📘

The suggested maximum number of terms for Find and Replace is 200. Above 200 terms, please contact us to learn about custom model training.

To transcribe audio from a file on your computer, run the following curl command in a terminal or your favorite API client.

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?replace=TERM_OR_PHRASE_TO_FIND:REPLACEMENT_TERM_OR_PHRASE'

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Replace a Single Term

To replace a single term, send one instance of the replace parameter in the query string when calling the API:

replace=monika:monica

replace=monika:Monica

Replace Multiple Terms

You can replace multiple terms individually:

replace=monika:monica&replace=hailee:hailey

replace=monika:monica&replace=Hailee:Hailey

Replace a Phrase

You can replace a phrase. URL-encode the phrase when submitting it.

replace=monika%20jon:monica%20john

replace=monika%20jon:Monica%20John

Remove a Term or Phrase

You can remove a term or phrase by not submitting a replacement.

replace=monika

Capitalization

You can selectively replace capitalized words by capitalizing the word-to-be-replaced.

This is particularly useful for proper nouns and named entities. Deepgram's transcription will make an educated guess when spelling unfamiliar named entities. In some cases, the capitalization of words or proper nouns may be incorrect so you can use capitalization to correct any inconsistencies. For example:

replace=ZenDesk:Zendesk

Backwards Compatibility

Prior to support for capitalization, replace=zendesk=Zendesk would replace all instances of the letters zendesk (ignoring capitalization) with Zendesk. To maintain backwards compatibility, the behavior is the same when the word-to-be-replaced is composed of entirely lowercase letters.

When submitting replacements for the same word with different capitalization, the capitalized version of the word takes precedence. For example, if you submit replace=It:The%20monster&replace=it:the%20monster, It will be replaced with The monster and it will be replaced with the monster because the replacement for It takes precedence over it. However, if you submit only replace=it:the%20monster, both it and It will be replaced with the monster to maintain backwards compatibility.

Analyze Response

For this example, we use a WAV audio file that contains an interview about speech analytics. If you would like to follow along, you can download it.

We want to replace the term "kpis" in this audio file with the full term "Key Performance Indicators".

In our terminal, we run the following curl command:

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"url":"https://developers.deepgram.com/data/audio/interview_speech-analytics.wav"}' \
  --url 'https://api.deepgram.com/v1/listen?replace=kpis:Key%20Performance%20Indicators'

ℹ️

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

When the file is finished processing, you’ll receive a JSON response. Let's look more closely at the words object within the alternatives object within this response. Notice that the audio contains an occurrence of the word "kpis":

...
{
  "alternatives": [
  {
    "words": [
        ...
        {
          "word":"kpis",
          "start":14.20957,
          "end":14.70957,
          "confidence":0.9946289
        },
        ...
      ]
     ...
    }
  ]
}

However, this has been replaced with "Key Performance Indicators".

{
  "alternatives": [
    { 
      "words": [
        ...
        {
          "word": "Key",
          "start": 14.20957,
          "end": 14.355842,
          "confidence": 0.99620026
        },
        {
          "word": "Performance",
          "start": 14.355842,
          "end": 14.502113,
          "confidence": 0.99620026
        },
        {
          "word": "Indicators",
          "start": 14.502114,
          "end": 14.648386,
          "confidence": 0.99620026
        },
        ...
      ]
     ...
    }
  ]
}

ℹ️

Use the API reference or the API Playground to view the detailed response.

In this part of the response, notice:

• the replacement word Key retains the same start value as the original word kpis.
• the replacement words have different end values than the original word kpis. This is because we replaced one word with three words, so the total time was divided roughly evenly between the words. If we were replacing one word with one word, the start and end times would be the same.

Use Cases

Examples of use cases for Find and Replace include:

• Audio that includes terminology that is sufficiently technical to not be transcribed accurately, but which needs to be found and corrected in the transcript.
• Audio that includes names that could be spelled in multiple ways. For example, the name "Aaron" appears in the transcript, but should be spelled "Erin" instead.