Create Custom Length Subtitles

While our SRT/VTT endpoints do allow you to customize the maximum number of characters per caption using the chars_per_caption URL parameter in your API requests, there are some use-cases that require a custom number of words in each subtitle.

In this guide, we will demonstrate how to construct these subtitles yourself in Python!

Quickstart

1 import assemblyai as aai
2 
3 aai.settings.api_key = "YOUR-API-KEY"
4 
5 config = aai.TranscriptionConfig(speech_models=["universal-3-pro", "universal-2"])
6 transcriber = aai.Transcriber()
7 
8 transcript = transcriber.transcribe("./my-audio.mp3", config)
9 
10 def second_to_timecode(x: float) -> str:
11     hour, x = divmod(x, 3600)
12     minute, x = divmod(x, 60)
13     second, x = divmod(x, 1)
14     millisecond = int(x * 1000.)
15 
16     return '%.2d:%.2d:%.2d,%.3d' % (hour, minute, second, millisecond)
17 
18 def generate_subtitles_by_word_count(transcript, words_per_line):
19   output = []
20   subtitle_index = 1  # Start subtitle index at 1
21   word_count = 0
22   current_words = []
23 
24   for sentence in transcript.get_sentences():
25     for word in sentence.words:
26       current_words.append(word)
27       word_count += 1
28       if word_count >= words_per_line or word == sentence.words[-1]:
29         start_time = second_to_timecode(current_words[0].start / 1000)
30         end_time = second_to_timecode(current_words[-1].end / 1000)
31         subtitle_text = " ".join([word.text for word in current_words])
32         output.append(str(subtitle_index))
33         output.append("%s --> %s" % (start_time, end_time))
34         output.append(subtitle_text)
35         output.append("")
36         current_words = []  # Reset for the next subtitle
37         word_count = 0  # Reset word count
38         subtitle_index += 1
39 
40   return output
41 
42 subs = generate_subtitles_by_word_count(transcript, 6)
43 with open(f"{transcript.id}.srt", 'w') as o:
44     final = '\n'.join(subs)
45     o.write(final)
46 
47 print("SRT file generated.")

Step-by-Step Instructions

$ pip install -U assemblyai

Create a main.py file and import the assemblyai package and set the API key.

1 import assemblyai as aai
2 
3 aai.settings.api_key = "YOUR-API-KEY"

Create a Transcriber object.

1 config = aai.TranscriptionConfig(speech_models=["universal-3-pro", "universal-2"])
2 transcriber = aai.Transcriber()

Use the Transcriber object’s transcribe method and pass in the audio file’s path as a parameter. The transcribe method saves the results of the transcription to the Transcriber object’s transcript attribute.

1 transcript = transcriber.transcribe("./my-audio.mp3", config)

Alternatively, you can pass in the URL of the publicly accessible audio file on the internet.

1 transcript = transcriber.transcribe("https://storage.googleapis.com/aai-docs-samples/espn.m4a", config)

Define a function that converts seconds to timecodes

1 def second_to_timecode(x: float) -> str:
2     hour, x = divmod(x, 3600)
3     minute, x = divmod(x, 60)
4     second, x = divmod(x, 1)
5     millisecond = int(x * 1000.)
6 
7     return '%.2d:%.2d:%.2d,%.3d' % (hour, minute, second, millisecond)

Define a function that iterates through the transcripts object to construct a list according to the number of words per subtitle

1 def generate_subtitles_by_word_count(transcript, words_per_line):
2   output = []
3   subtitle_index = 1  # Start subtitle index at 1
4   word_count = 0
5   current_words = []
6 
7   for sentence in transcript.get_sentences():
8     for word in sentence.words:
9       current_words.append(word)
10       word_count += 1
11       if word_count >= words_per_line or word == sentence.words[-1]:
12         start_time = second_to_timecode(current_words[0].start / 1000)
13         end_time = second_to_timecode(current_words[-1].end / 1000)
14         subtitle_text = " ".join([word.text for word in current_words])
15         output.append(str(subtitle_index))
16         output.append("%s --> %s" % (start_time, end_time))
17         output.append(subtitle_text)
18         output.append("")
19         current_words = []  # Reset for the next subtitle
20         word_count = 0  # Reset word count
21         subtitle_index += 1
22 
23   return output

Generate your subtitle file

1 subs = generate_subtitles_by_word_count(transcript, 6)
2 with open(f"{transcript.id}.srt", 'w') as o:
3     final = '\n'.join(subs)
4     o.write(final)
5 
6 print("SRT file generated.")

Run your script.

$ python main.py

1	import assemblyai as aai
2
3	aai.settings.api_key = "YOUR-API-KEY"
4
5	config = aai.TranscriptionConfig(speech_models=["universal-3-pro", "universal-2"])
6	transcriber = aai.Transcriber()
7
8	transcript = transcriber.transcribe("./my-audio.mp3", config)
9
10	def second_to_timecode(x: float) -> str:
11	hour, x = divmod(x, 3600)
12	minute, x = divmod(x, 60)
13	second, x = divmod(x, 1)
14	millisecond = int(x * 1000.)
15
16	return '%.2d:%.2d:%.2d,%.3d' % (hour, minute, second, millisecond)
17
18	def generate_subtitles_by_word_count(transcript, words_per_line):
19	output = []
20	subtitle_index = 1 # Start subtitle index at 1
21	word_count = 0
22	current_words = []
23
24	for sentence in transcript.get_sentences():
25	for word in sentence.words:
26	current_words.append(word)
27	word_count += 1
28	if word_count >= words_per_line or word == sentence.words[-1]:
29	start_time = second_to_timecode(current_words[0].start / 1000)
30	end_time = second_to_timecode(current_words[-1].end / 1000)
31	subtitle_text = " ".join([word.text for word in current_words])
32	output.append(str(subtitle_index))
33	output.append("%s --> %s" % (start_time, end_time))
34	output.append(subtitle_text)
35	output.append("")
36	current_words = [] # Reset for the next subtitle
37	word_count = 0 # Reset word count
38	subtitle_index += 1
39
40	return output
41
42	subs = generate_subtitles_by_word_count(transcript, 6)
43	with open(f"{transcript.id}.srt", 'w') as o:
44	final = '\n'.join(subs)
45	o.write(final)
46
47	print("SRT file generated.")