Getting Started

In this guide, you’ll learn how to analyze audio using Deepgram’s intelligence features: Summarization, Topic Detection, Intent Recognition, and Sentiment Analysis. The code examples use Deepgram’s SDKs.

What is Audio Intelligence?

Deepgram’s Audio Intelligence API lets users send an audio source to Deepgram, and Deepgram will perform one of four types of analysis on the content of the audio after it has been transcribed. Read about each feature in its individual feature guides:

• Summarization
• Topic Detection
• Intent Recognition
• Sentiment Analysis

API Playground

First, quickly explore Deepgram Audio Intelligence in our API Playground.

Make the Request

A request made using one of the audio intelligence features will follow the same form for each of the features; therefore, this guide will walk you through how to make one request, and you can use the feature(s) of your choice depending on which feature you want to use (Summarization, Topic Detection, Intent Recognition, or Sentiment Analysis).

Choose Your Audio Source

An audio source can be sent to Deepgram as an audio file or as a url of a hosted audio file. These are referred to as a local file request or a remote file request (which is a hosted url such as https://YOUR_FILE_URL.txt).

Local File Request

This example shows how to analyze a local audio file as your audio source.

1
const { createClient } = require("@deepgram/sdk");
2
const fs = require("fs");
3
4
const transcribeFile = async () => {
5
  // STEP 1: Create a Deepgram client using the API key
6
  const deepgram = createClient(process.env.DEEPGRAM_API_KEY);
7
8
  // STEP 2: Call the transcribeFile method with the audio payload and options
9
  const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
10
    fs.readFileSync("callcenter.wav"),
11
    // STEP 3: Configure Deepgram options for audio analysis
12
    {
13
      model: "nova-3",
14
      sentiment: true,
15
      // intents: true,
16
      // summarize: "v2",
17
      // topics: true,
18
    }
19
  );
20
21
  if (error) throw error;
22
  // STEP 4: Print the results
23
  if (!error) console.dir(result, { depth: null });
24
};
25
26
transcribeFile();

Remote File Request

This example shows how to analyze a remote audio file (a URL that hosts your audio file).

1
const { createClient } = require("@deepgram/sdk");
2
3
const transcribeUrl = async () => {
4
  // STEP 1: Create a Deepgram client using the API key
5
  const deepgram = createClient(process.env.DEEPGRAM_API_KEY);
6
7
  // STEP 2: Call the transcribeUrl method with the audio payload and options
8
  const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
9
    {
10
      url: "https://dpgr.am/spacewalk.wav",
11
    },
12
    // STEP 3: Configure Deepgram options for audio analysis
13
    {
14
      model: "nova-3",
15
      sentiment: true,
16
      // intents: true,
17
      // summarize: "v2",
18
      // topics: true,
19
    }
20
  );
21
22
  if (error) throw error;
23
  // STEP 4: Print the results
24
  if (!error) console.dir(result, { depth: null });
25
};
26
27
transcribeUrl();

Start the Application

Run your application from the terminal.

$
# Run your application using the file you created in the previous step
>
# Example: node index.js
>
node index.js

See Results

Your results will appear in your shell.

Analyze the Response

When the file is finished processing (often after only a few seconds), you’ll receive a JSON response. (Note that some sections are omitted in order to demonstrate relevant properties.)

1
{
2
  "metadata": {
3
    ...
4
    "summary_info": {
5
      "model_uuid": "67875a7f-c9c4-48a0-aa55-5bdb8a91c34a",
6
      "input_tokens": 133,
7
      "output_tokens": 57
8
    }
9
  },
10
  "results": {
11
    "channels": [
12
      {
13
        "alternatives": [
14
          {
15
            "transcript": "Parker Scarves. How may I help you? I bought a scarf online for my wife, and it turns out they shipped the wrong color. Oh, I am so sorry, sir. I got it for her birthday, which is tonight, and now I I'm not a hundred percent sure what I need to do.",
16
            "confidence": 0.99902344,
17
            "words": [
18
              {
19
                "word": "parker",
20
                "start": 1.04,
21
                "end": 1.52,
22
                "confidence": 0.94628906,
23
              },
24
              ...
25
            ]
26
          }
27
        ]
28
      }
29
    ],
30
    "summary": {
31
      "result": "success",
32
      "short": "The customer called to complain about a scarf he ordered online for his wife's birthday. He explains that he bought the wrong color and now he is unsure what to do. The agent asks for the item number and color of the scarf he wants to purchase and offers to help."
33
    }
34
  }
35
}

Following are explanations of each of the example responses. Be sure to click the tabs in the code block above to view the example response for each text analysis feature.

All Audio Intelligence Features

Because Deepgram transcribes the audio before conducting the analysis, you will always see properties related to the transcription response, such as the following.

In the results object, we see:

• transcript: the transcript for the audio segment being processed.
• confidence: a floating point value between 0 and 1 that indicates overall transcript reliability. Larger values indicate higher confidence.
• words: an object containing each word in the transcript, along with its start time and end time (in seconds) from the beginning of the audio stream, and a confidence value.

Summarization

In the metadata object, we see:

• summary_info: information about the model used and the input/output tokens. Summarization pricing is based on the number of input and output tokens. Read more at deepgram.com/pricing.
• summary: the short property in this object gives you the summary of the audio you requested to be analyzed.

Topic Detection

In the metadata object, we see:

• topics_info: information about the model used and the input/output tokens. Topic Detection pricing is based on the number of input and output tokens. Read more at deepgram.com/pricing.

In the results object, we see:

• topics(object): contains the data about Topic Detection.

• segments: each segment object contains a span of text taken from the transcript; this text segment is analyzed for its topic.

• topics(array): a list of topic objects, each containing the topic and a confidence_score.

  • topic: Deepgram analyzes the segmented transcript to identify the main topic of each.
  • confidence_score: a floating point value between 0 and 1 indicating the overall reliability of the analysis.

Intent Recognition

In the metadata object, we see:

• intents_info: information about the model used and the input/output tokens. Intent Recognition pricing is based on the number of input and output tokens. Read more at deepgram.com/pricing.

In the results object, we see:

• intents(object): contains the data about Intent Recognition.

• segments: each segment object contains a span of text taken from the transcript; this text segment is analyzed for its intent.

• intents(array): a list of intent objects, each containing the intent and a confidence_score.

  • intent: Deepgram analyzes the segmented transcript to identify the intent of each.
  • confidence_score: a floating point value between 0 and 1 indicating the overall reliability of the analysis.

Sentiment Analysis

In the metadata object, we see:

• sentiment_info: information about the model used and the input/output tokens. Sentiment Analysis pricing is based on the number of input and output tokens. Read more at deepgram.com/pricing.

In the results object, we see:

• sentiments(object): contains the data about Sentiment Analysis.
• segments: each segment object contains a span of text taken from the transcript; these segments of text show when the sentiment shifts throughout the text, and each one is analyzed for its sentiment.
• sentiment can be positive, negative, or neutral.
• sentiment_score: a floating point value between -1 and 1 representing the sentiment of the associated span of text, with -1 being the most negative sentiment, and 1 being the most positive sentiment.
• average: the average sentiment for the entire transcript.

Limits

Language

At this time, audio analysis features only work for English language transcriptions.

Token Limit

The input token limit is 150K tokens. When that limit is exceeded, a 400 error will be thrown

1
{
2
  "err_code": "TOKEN_LIMIT_EXCEEDED",
3
  "err_msg": "Text input currently supports up to 150K tokens. Please revise your text input to fit within the defined token limit. For more information, please visit our API documentation.",
4
  "request_id": "XXXX"
5
}