Chapters
Learn how to use Speechmatics' Chapters.Speechmatics enables you to identify distinct, continuous chapters in your audio. With just a single API call, you can quickly transcribe and extract the timings, title and summary for each chapter.
If you're new to Speechmatics, please see our guide on Transcribing a File. Once you are set up, include the following config to enable Chapters:
{
"type": "transcription",
"transcription_config": {
"language": "en"
},
"auto_chapters_config": {}
}
Example
Python client example to return Chapters for a batch 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://asr.api.speechmatics.com/v2",
auth_token=API_KEY,
)
# Define transcription parameters
conf = {
"type": "transcription",
"transcription_config": {"language": LANGUAGE},
"auto_chapters_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")
chapters = transcript["chapters"]
for chapter in chapters:
print(
f"({chapter['start_time']} - {chapter['end_time']}) {chapter['title']}\n{chapter['summary']}\n\n"
)
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
Chapters' results are only available in the JSON output.
Each chapter generated will contain a start and end time of the chapter, an auto-generated title and a short summary of the chapter. Chapters are non-overlapping and exhaustive i.e. the chapters cover the entire audio file from start to end.
chapters object[]
An array of objects that represent summarized chapters of the transcript
The auto-generated title for the chapter
An auto-generated paragraph-style, short summary of the chapter
The start time of the chapter in the audio file
The end time of the chapter in the audio file
{
"job": { ... },
"metadata": {
"created_at": "2023-07-17T15:01:48.412714Z",
"type": "transcription",
"transcription_config": {
"language": "en",
"diarization": "speaker"
},
"auto_chapters_config": {}
...
},
"chapters": [
{
"end_time": 6.3,
"start_time": 0.0,
"summary": "The speaker begins by mentioning the 1961 summit between President Kennedy and Soviet Premier Khrushchev, noting that in hindsight it appeared to be a failure. However, the speaker says that summits like this often have long-term impacts that are not immediately clear.",
"title": "The 1961 Kennedy-Khrushchev Summit"
},
{
"end_time": 13.23,
"start_time": 6.3,
"summary": "The speaker then notes that the 1961 Kennedy-Khrushchev summit contributed to the later Cuban Missile Crisis, further illustrating the complex impacts summits can have.",
"title": "The Cuban Missile Crisis"
},
{
"end_time": 18.78,
"start_time": 13.23,
"summary": "The speaker argues that it is difficult to quickly assess the impact of summits like the recent one. The speaker says we will not be able to make definitive judgments about the impacts of this summit right away.",
"title": "Assessing the Impact of Summits"
},
{
"end_time": 25.53,
"start_time": 18.78,
"summary": "The speaker abruptly shifts topics to discuss a Supreme Court decision upholding Ohio's law to purge voter rolls, which are some of the strictest voter roll purge laws in the country.",
"title": "Supreme Court Decision on Ohio Voter Rolls"
},
],
"format": "2.9",
"job": { ... },
"metadata": {
"created_at": "2023-07-17T15:01:48.412714Z",
"type": "transcription",
"transcription_config": {
"language": "en",
"diarization": "speaker"
},
"auto_chapters_config": {}
...
},
"results": [...],
}
Considerations
- Chapters works best for longer-form content. A minimum of 10 minutes of transcribed speech is recommended for best results
- Chapters works best with Speaker or Channel Diarization enabled
- Punctuation plays a significant role in the quality of the Chapters. It is therefore recommended to avoid disabling any end of sentence punctuation or reducing the punctuation sensitivity
Error Responses
Unsupported Language
If Chapters is requested for an unsupported language, the transcription process will complete. However, no Chapters will be returned, and an error message will be included in the final JSON output.
Chapters is supported for all of Speechmatics' languages except Irish, Maltese, Urdu, Bengali and Swahili.
{
"job": { ... },
"metadata": {
"created_at": "2023-05-26T15:01:48.412714Z",
"type": "transcription",
"transcription_config": {
"language": "xx"
},
"auto_chapters_config": {},
"auto_chapters_errors": [
{"type": "unsupported_language", "message": "Auto chapters not supported for xx."}
],
...
},
"results": [...]
}
Chapters Failed
If Chapters fails, the transcription process will complete but the Chapters 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"
},
"auto_chapters_config": {},
"auto_chapters_errors": [
{"type": "auto_chapters_failed", "message": "Auto Chapters failed."}
],
...
},
"results": [...]
}