# Topics

Learn how to use Speechmatics' Topics.

Speechmatics enables you to detect topics from your audio. With just a single API call, you can quickly transcribe and identify key topics with the corresponding segments of audio, allowing you to tag conversations or identify trends and patterns.

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 Topics:

```
{
  "type": "transcription",
  "transcription_config": {
    "model": "enhanced",
    "language": "en"
  },
  // You can also configure the list of topics you wish to detect. See below for more detail.
  "topic_detection_config": {} 
}
```

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

Python client example to detect topics in a file for Batch with the default parameters.

```
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"},
    # You can also configure the list of topics you wish to detect. See below for more detail.
    "topic_detection_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/batch-transcription/notifications
        transcript = client.wait_for_completion(job_id, transcription_format="json-v2")
        topics_detected = transcript["topics"]
        topic_segments = topics_detected["segments"]
        topic_summary = topics_detected["summary"]["overall"]

        # print the overall count for each topic
        print(topic_summary)

        # print the text and the corresponding topic(s) and timings for each segment
        for segment in topic_segments:
            print(
                f"({segment['start_time']} - {segment['end_time']}): {segment['text']} ({[t['topic'] for t in segment['topics']]})"
            )
    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
```

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

The topics detected are only present in the JSON output.

```
{
  "job": { ... },
  "metadata": {
    "created_at": "2023-05-26T15:01:48.412714Z",
    "type": "transcription",
    "transcription_config": {
      "language": "en"
    },
    "topic_detection_config": {}
    ...
  },
  "results": [...],
  "topics": {
    "segments": [
        {
          "text": "The National Park Service on Twitter says it expects the closures to remain in effect ...",
          "start_time": 0.80,
          "end_time": 1.72,
          "topics": [{"topic": "Events & Attractions"}],
        },
        {
          "text": "Lawmakers in Canada have voted to regulate online streaming content ...",
          "start_time": 2.06,
          "end_time": 3.40,
          "topics": [{"topic": "News & Politics"}, {"topic": "Technology & Computing"}],
        }
    ],
    "summary": {
      "overall": {
        "Business & Finance": 1,
        "Education": 0,
        "Entertainment": 0,
        "Events & Attractions": 0,
        "Food & Drink": 0,
        "News & Politics": 1,
        "Science": 0,
        "Sports": 0,
        "Technology & Computing": 1,
        "Travel": 0
      }
    }
  }
}
```

## Setting list of topics[​](#setting-list-of-topics "Direct link to Setting list of topics")

If you have a specific list of topics you wish to detect, you can provide this information through the `topics` parameter:

```
{
  "type": "transcription",
  "transcription_config": {
    "model": "enhanced",
    "language": "en"
  },
  "topic_detection_config": {
    "topics": ["pricing", "deployment", "languages"]
  }
}
```

If you don't have a specific list of topics, the Topics feature will attempt to detect these default topics in the audio:

* Business & Finance
* Education
* Entertainment
* Events & Attractions
* Food & Drink
* News & Politics
* Science
* Sports
* Technology & Computing
* Travel

A maximum of 10 topics can be provided. If more than 10 topics are provided in the `topics` list, the transcription will complete. However, no Topics will be returned, and an [error message](#too-many-topics) will be included in the final JSON output.

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

### News segment[​](#news-segment "Direct link to News segment")

Topics detected in a BBC News segment

**Default Topics**

| Topic(s)                       | Segment                                                                                                                                                                                                                                                                                                                            | Start Time (s) | End Time (s) |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------ |
| News & Politics                | President Biden and the South Korean President Yoon Sung Yell have reaffirmed their commitment to extended deterrence in the face of the growing nuclear threat from North Korea. The two leaders have agreed to give South Korea a greater voice in how the US would respond to any nuclear incident.                             | 2.57           | 21.35        |
| News & Politics                | President Zelensky says he's discussed ways to reach a fair and sustainable peace. In his first direct phone call with the Chinese leader Xi Jinping, since Russia invaded Ukraine. Mr. Zelensky stressed Ukraine would not accept any loss of territory.                                                                          | 21.92          | 37.76        |
| News & Politics                | Renewed fighting near Khartoum is threatening the three day ceasefire in Sudan. People in the capital are struggling to get food and water. Thousands are continuing to leave.                                                                                                                                                     | 38.33          | 49.16        |
| News & Politics                | The UN's envoy to Haiti has told a meeting of the Security Council that gang violence is expanding at an alarming rate in areas previously considered safe.                                                                                                                                                                        | 49.73          | 60.02        |
| Entertainment, News & Politics | The Walt Disney Corporation has sued the Republican governor of Florida, Ron DeSantis, seeking to overturn state efforts to exert control over its theme park. The entertainment giant says it's facing government retaliation after it criticized a Florida law that banned lessons and sexuality and gender identity in schools. | 61.1           | 82.13        |

**Custom Topics (War, Weather)**

| Topic(s) | Segment                                                                                                                                                                           | Start Time (s) | End Time (s) |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------ |
| War      | President Biden and the South Korean President Yoon Sung Yell have reaffirmed their commitment to extended deterrence in the face of the growing nuclear threat from North Korea. | 2.57           | 13.7         |
| War      | In his first direct phone call with the Chinese leader Xi Jinping, since Russia invaded Ukraine. Mr. Zelensky stressed Ukraine would not accept any loss of territory.            | 26.99          | 37.76        |
| War      | Renewed fighting near Khartoum is threatening the three day ceasefire in Sudan.                                                                                                   | 38.33          | 43.25        |
| Weather  | The European Union says in 2022, Southern Europe experienced the highest number of days on record with very strong heat stress.                                                   | 107.48         | 117.56       |

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

* Topics is only supported for English
* Topics supports a custom list of up to 10 topics
* Topics utilizes a large language model (LLM). This occasionally may lead to inaccuracies in the topics detected and the corresponding segments of audio and you may receive different segments when running the same file multiple times

## Error responses[​](#error-responses "Direct link to Error responses")

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

Topics is currently only supported for English. In the event that Topics is requested for an unsupported language, the transcription process will complete. However, the Topics will not be performed, 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"
    },
    "topic_detection_config": {},
    "topic_detection_errors": [
      {"type": "unsupported_language", "message": "Topic Detection not supported for cy."}
    ],
    ...
  },
  "results": [...]
}
```

### Too many topics[​](#too-many-topics "Direct link to Too many topics")

In the event that more than 10 topics are requested for Topics, the transcription process will complete. However, the Topics 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"
    },
    "topic_detection_config": {
      "topics": ["topic1", "topic2", "topic3", "topic4", "topic5", "topic6", "topic7", "topic8", "topic9", "topic10", "topic11"]
    },
    "topic_detection_errors": [
      {"type": "unsupported_list_of_topics", "message": "List of topics cannot exceed 10 topics."}
    ],
    ...
  },
  "results": [...]
}
```

### Topics failed[​](#topics-failed "Direct link to Topics failed")

In the event that Topics fails, the transcription process will complete but the Topics 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"
    },
    "topic_detection_config": {},
    "topic_detection_errors": [
      {"type": "topic_detection_failed", "message": "Topic Detection failed."}
    ],
    ...
  },
  "results": [...]
}
```

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

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