# Sentiment analysis

Learn about the sentiment analysis offering for the Speechmatics Batch API

Speechmatics enables you to understand the sentiment of what was spoken in your audio. With just a single API call, you can quickly transcribe and extract the sentiment, either positive, negative or neutral to quickly detect areas of conversation to analyse further.

If you're new to Speechmatics, please see our guide on [Transcribing a File](/speech-to-text/batch/quickstart.md). Once you are set up, include the following config to enable Sentiment:

```
{
  "type": "transcription",
  "transcription_config": {
    "model": "enhanced",
    "language": "en"
  },
  "sentiment_analysis_config": {}
}
```

## Example[​](#example "Direct link to Example")

Python client example to return transcription with sentiment analysis for an audio file.

```
from speechmatics.models import ConnectionSettings
from speechmatics.batch_client import BatchClient
from httpx import HTTPStatusError

API_KEY = "YOUR_API_KEY"
PATH_TO_FILE = "example.wav"
LANGUAGE = "en"  # Transcription language

settings = ConnectionSettings(
    url="https://eu1.asr.api.speechmatics.com/v2",
    auth_token=API_KEY,
)

# Define transcription parameters
conf = {
    "type": "transcription",
    "transcription_config": {"language": LANGUAGE, "model": "enhanced"},
    "sentiment_analysis_config": {},
}

# Open the client using a context manager
with BatchClient(settings) as client:
    try:
        job_id = client.submit_job(
            audio=PATH_TO_FILE,
            transcription_config=conf,
        )
        print(f"job {job_id} submitted successfully, waiting for transcript")

        # Note that in production, you should set up notifications instead of polling.
        # Notifications are described here: https://docs.speechmatics.com/speech-to-text/batch/notifications
        transcript = client.wait_for_completion(job_id, transcription_format="json-v2")
        sentiment = transcript["sentiment_analysis"]
        sentiment_summary = sentiment["summary"]
        sentiment_segments = sentiment["segments"]

        print(sentiment_summary["overall"])
        for segment in sentiment_segments:
            print(
                f" {segment['text']} ({segment['sentiment']})"
            )  # print the sentiment for each segment
    except HTTPStatusError as e:
        if e.response.status_code == 401:
            print("Invalid API key - Check your API_KEY at the top of the code!")
        elif e.response.status_code == 400:
            print(e.response.json()["detail"])
        else:
            raise e
```

## Understanding the response[​](#understanding-the-response "Direct link to Understanding the response")

Sentiment results are only available in the JSON output.

Segments of the transcript are labeled with either positive, negative or neutral and a confidence score. This score indicates the model's certainty regarding the assigned sentiment prediction.

`SentimentAnalysisResult`In the API reference: [Get the transcript for a transcription job](/api-ref/batch/get-the-transcript-for-a-transcription-job.md)

* `sentiment_analysis`

  `object`

  optional

  * Holds the detailed sentiment analysis information.

    ▾Hide 2 properties

  * `segments`

    `SentimentSegment[]`

    optional

  * An array of objects that represent a segment of text and its associated sentiment.

    ▾Hide 7 properties

  * `sentiment_analysis.segments[].``text`

    `string`

    optional

  * Represents the transcript of the analyzed segment

  * `sentiment_analysis.segments[].``sentiment`

    `string`

    optional

  * The assigned sentiment to the segment, which can be positive, neutral or negative

  * `sentiment_analysis.segments[].``start_time`

    `number<float>`

    optional

  * The timestamp corresponding to the beginning of the transcription segment

  * `sentiment_analysis.segments[].``end_time`

    `number<float>`

    optional

  * The timestamp corresponding to the end of the transcription segment

  * `sentiment_analysis.segments[].``speaker`

    `string`

    optional

  * The speaker label for the segment, if speaker diarization is enabled

  * `sentiment_analysis.segments[].``channel`

    `string`

    optional

  * The channel label for the segment, if channel diarization is enabled

  * `sentiment_analysis.segments[].``confidence`

    `number<float>`

    optional

  * A confidence score in the range of 0-1, indicating the model's certainty in the predicted sentiment,

  * `summary`

    `SentimentSummary`

    optional

  * Holds overall sentiment information, as well as detailed per-speaker and per-channel sentiment data.

    ▾Hide 3 properties

  * `sentiment_analysis.summary.``overall`

    `SentimentSummaryDetail`

    optional

  * Holds the count of sentiment information grouped by positive, neutral and negative.

    ▾Hide 3 properties

  * `sentiment_analysis.summary.overall.``positive_count`

    `integer`

    optional

  * `sentiment_analysis.summary.overall.``negative_count`

    `integer`

    optional

  * `sentiment_analysis.summary.overall.``neutral_count`

    `integer`

    optional

  * `sentiment_analysis.summary.``speakers`

    `SentimentSpeakerSummary[]`

    optional

  * An array of objects that represent sentiment data for a specific speaker.

    ▾Hide 4 properties

  * `sentiment_analysis.summary.speakers[].``speaker`

    `string`

    optional

  * `sentiment_analysis.summary.speakers[].``positive_count`

    `integer`

    optional

  * `sentiment_analysis.summary.speakers[].``negative_count`

    `integer`

    optional

  * `sentiment_analysis.summary.speakers[].``neutral_count`

    `integer`

    optional

  * `sentiment_analysis.summary.``channels`

    `SentimentChannelSummary[]`

    optional

  * An array of objects that represent sentiment data for a specific channel.

    ▾Hide 4 properties

  * `sentiment_analysis.summary.channels[].``channel`

    `string`

    optional

  * `sentiment_analysis.summary.channels[].``positive_count`

    `integer`

    optional

  * `sentiment_analysis.summary.channels[].``negative_count`

    `integer`

    optional

  * `sentiment_analysis.summary.channels[].``neutral_count`

    `integer`

    optional

```
{
  "job": { ... },
  "metadata": {
    "created_at": "2023-07-17T15:01:48.412714Z",
    "type": "transcription",
    "transcription_config": {
      "language": "en",
      "diarization": "speaker"
    },
    "sentiment_analysis_config": {}
    ...
  },
  "results": [...],
  "sentiment_analysis": {
    "segments": [
      {
        "confidence": 0.88,
        "end_time": 7.94,
        "sentiment": "positive",
        "speaker": "S1",
        "start_time": 3.0,
        "text": "We're delighted that you've decided to try our speech to text software to get going."
      },
      {
        "confidence": 0.76,
        "end_time": 12.18,
        "sentiment": "neutral",
        "speaker": "S1",
        "start_time": 7.95,
        "text": "Just create an API key and submit a transcription request to our API."
      }
    ],
    "summary": {
      "overall": {
        "negative_count": 0,
        "neutral_count": 1,
        "positive_count": 1
      },
      "speakers": [
        {
          "speaker": "S1",
          "negative_count": 0,
          "neutral_count": 1,
          "positive_count": 1
        }
      ]
    }
  }
}
```

## Considerations[​](#considerations "Direct link to Considerations")

* Sentiment is only supported for English
* Typically, segments equate to full sentences. However, in cases of short utterances composed of 1-2 words, these can be combined with a neighboring sentence to form a segment
* Punctuation plays a significant role in the accuracy of the Sentiment. It is therefore recommended to avoid disabling any end of sentence [punctuation](/speech-to-text/formatting.md#punctuation) or reducing the [punctuation sensitivity](/speech-to-text/formatting.md#punctuation) to ensure the best possible results
* Speaker or channel labels will only be available if [Diarization](/speech-to-text/features/diarization.md) is enabled. By default when Diarization is not enabled "speaker":"UU" is returned to indicate that speakers of each segment are unknown
* Speaker Change is not supported in combination with Sentiment

# Error responses

Learn about the sentiment analysis offering for the Speechmatics Batch API

### Unsupported language[​](#unsupported-language "Direct link to Unsupported language")

Currently Sentiment is only supported for English.

If Sentiment is requested for an unsupported language, the transcription process will complete. However, the Sentiment will not be returned, and an error message will be included in the final JSON output.

```
{
  "job": { ... },
  "metadata": {
    "created_at": "2023-05-26T15:01:48.412714Z",
    "type": "transcription",
    "transcription_config": {
      "language": "cy"
    },
    "sentiment_analysis_config": {},
    "sentiment_analysis_errors": [
      {"type": "unsupported_language", "message": "Sentiment analysis not supported for cy."}
    ],
    ...
  },
  "results": [...]
}
```

### Sentiment failed[​](#sentiment-failed "Direct link to Sentiment failed")

If Sentiment fails, the transcription process will complete but the Sentiment will not be returned, and an error message will be included in the final JSON output.

```
{
  "job": { ... },
  "metadata": {
    "created_at": "2023-05-26T15:01:48.412714Z",
    "type": "transcription",
    "transcription_config": {
      "language": "en"
    },
    "sentiment_analysis_config": {},
    "sentiment_analysis_errors": [
      {"type": "sentiment_analysis_failed", "message": "Sentiment Analysis failed."}
    ],
    ...
  },
  "results": [...]
}
```

## Next steps[​](#next-steps "Direct link to Next steps")

Learn how to use sentiment analysis from examples in the [Speechmatics Academy](https://github.com/speechmatics/speechmatics-academy/tree/main/basics/04-audio-intelligence).
