Chapters
Transcription:BatchDeployments:SaaSRequests for Chapters from all Speechmatics end-points are currently processed using a GDPR-compliant environment in the USA.
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": {}
}
Quick start
Python client example to return Chapters for a batch file.
1from speechmatics.models import ConnectionSettings
2from speechmatics.batch_client import BatchClient
3from httpx import HTTPStatusError
4
5API_KEY = "YOUR_API_KEY"
6PATH_TO_FILE = "example.wav"
7LANGUAGE = "en" # Transcription language
8
9settings = ConnectionSettings(
10 url="https://asr.api.speechmatics.com/v2",
11 auth_token=API_KEY,
12)
13
14# Define transcription parameters
15conf = {
16 "type": "transcription",
17 "transcription_config": {
18 "language": LANGUAGE
19 },
20 "auto_chapters_config": {}
21}
22
23# Open the client using a context manager
24with BatchClient(settings) as client:
25 try:
26 job_id = client.submit_job(
27 audio=PATH_TO_FILE,
28 transcription_config=conf,
29 )
30 print(f'job {job_id} submitted successfully, waiting for transcript')
31
32 # Note that in production, you should set up notifications instead of polling.
33 # Notifications are described here: https://docs.speechmatics.com/features-other/notifications
34 transcript = client.wait_for_completion(job_id, transcription_format='json-v2')
35 chapters = transcript["chapters"]
36 for chapter in chapters:
37 print(f'({chapter["start_time"]} - {chapter["end_time"]}) {chapter["title"]}\n{chapter["summary"]}\n\n')
38
39 except HTTPStatusError as e:
40 if e.response.status_code == 401:
41 print('Invalid API key - Check your API_KEY at the top of the code!')
42 elif e.response.status_code == 400:
43 print(e.response.json()['detail'])
44 else:
45 raise e
46Understanding 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.
chaptersprovides a list of transcript segments, each with the following keys:- start_time: this represents the starting time of the chapter in the audio file.
- end_time: this represents the ending time of the chapter in the audio file.
- title: the auto-generated title for the chapter.
- summary: an auto-generated paragraph-style, short summary of the chapter.
Please refer to our API reference for full details about the Chapters API content.
{
"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 is only supported for English.
- 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 Marks or reducing the Punctuation Sensitivity.
Error Responses
Unsupported Language
Currently Chapters is only supported for English.
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.
{
"job": { ... },
"metadata": {
"created_at": "2023-05-26T15:01:48.412714Z",
"type": "transcription",
"transcription_config": {
"language": "cy"
},
"auto_chapters_config": {},
"auto_chapters_errors": [
{"type": "unsupported_language", "message": "Auto chapters not supported for cy."}
],
...
},
"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": [...]
}