1"""Audio/video -> text with Groq's Whisper API: ffmpeg prepares speech-quality chunks, Groq transcribes them."""
2from __future__ import annotations
3
4import difflib
5import json
6import math
7import os
8import re
9import subprocess
10import time
11
12import httpx
13
14GROQ_URL = 'https://api.groq.com/openai/v1/audio/transcriptions'
15MODELS = {'accurate': 'whisper-large-v3', 'fast': 'whisper-large-v3-turbo'}
16CHUNK_SECONDS = 600
17MAX_RETRIES = 6
18
19
20class TranscriptionError(Exception):
21 pass
22
23
24def probe_duration(path: str) -> float:
25 """Duration of the first audio stream in seconds; raises if the file has no audio."""
26 out = subprocess.run(['ffprobe', '-v', 'error', '-select_streams', 'a:0', '-show_entries', 'stream=duration:format=duration',
27 '-of', 'json', path], capture_output=True, text=True, timeout=120)
28 try:
29 info = json.loads(out.stdout or '{}')
30 except json.JSONDecodeError:
31 info = {}
32 if not info.get('streams'):
33 raise TranscriptionError('no audio track found (not an audio/video file, damaged or unsupported)')
34 for value in (info['streams'][0].get('duration'), info.get('format', {}).get('duration')):
35 try:
36 if value and float(value) > 0:
37 return float(value)
38 except ValueError:
39 pass
40 raise TranscriptionError('cannot read the audio duration')
41
42
43def make_chunks(path: str, outdir: str, duration: float) -> list[tuple[str, float]]:
44 """Speech-quality mono MP3 chunks (16 kHz, 32 kbit/s). Returns (chunk path, start offset)."""
45 chunks = []
46 for i in range(math.ceil(duration / CHUNK_SECONDS)):
47 start = i * CHUNK_SECONDS
48 dest = os.path.join(outdir, f'chunk-{i:04d}.mp3')
49 length = min(CHUNK_SECONDS, duration - start)
50 res = subprocess.run(['ffmpeg', '-v', 'error', '-y', '-ss', str(start), '-t', f'{length:.3f}', '-i', path,
51 '-vn', '-ac', '1', '-ar', '16000', '-b:a', '32k', dest],
52 capture_output=True, text=True, timeout=900)
53 if res.returncode != 0 or not os.path.exists(dest):
54 raise TranscriptionError(f'cannot decode the audio: {res.stderr.strip()[:200]}')
55 if os.path.getsize(dest) > 1000:
56 chunks.append((dest, float(start)))
57 if not chunks:
58 raise TranscriptionError('the audio track is empty')
59 return chunks
60
61
62def transcribe_chunk(client: httpx.Client, path: str, *, model: str, language: str | None, prompt: str | None) -> dict:
63 data = {'model': model, 'response_format': 'verbose_json', 'temperature': '0'}
64 if language:
65 data['language'] = language
66 if prompt:
67 data['prompt'] = prompt[:1200]
68 headers = {}
69 if os.environ.get('GROQ_API_KEY'):
70 headers['Authorization'] = 'Bearer ' + os.environ['GROQ_API_KEY']
71 for attempt in range(MAX_RETRIES):
72 with open(path, 'rb') as f:
73 r = client.post(GROQ_URL, data=data, files={'file': (os.path.basename(path), f, 'audio/mpeg')},
74 headers=headers)
75 if r.status_code == 200:
76 return r.json()
77 if r.status_code in (429, 500, 502, 503, 504) and attempt < MAX_RETRIES - 1:
78 wait = _retry_after(r.headers) or min(60, 5 * 2 ** attempt)
79 if wait > 300:
80 raise TranscriptionError('the speech service is at its usage limit right now; try again later')
81 time.sleep(wait)
82 continue
83 if r.status_code in (401, 403):
84 raise TranscriptionError('speech service authorisation failed (Actor configuration problem)')
85 raise TranscriptionError(f'speech service error HTTP {r.status_code}: {r.text[:200]}')
86 raise TranscriptionError('the speech service did not respond, try again later')
87
88
89def _retry_after(headers) -> float | None:
90 value = headers.get('retry-after')
91 try:
92 return float(value) if value else None
93 except ValueError:
94 return None
95
96
97def _silence(seg: dict) -> bool:
98 """Whisper's own rule for music or silence it filled with made-up words ("Thank you", "We'll be right back")."""
99 return float(seg.get('no_speech_prob') or 0) > 0.6 and float(seg.get('avg_logprob') or 0) < -1
100
101
102
103
104_STOCK = [
105 "thank you", "thanks for watching", "thank you for watching", "we'll be right back", "we will be right back",
106 "please subscribe", "subscribe to my channel", "like and subscribe", "see you next time", "see you in the next video",
107 "bye", "you", "music", "applause", "subtitles by the amara.org community", "transcribed by", "subtitles by",
108 "дякую за перегляд", "дякую", "підписуйтесь на канал", "продовження буде", "субтитри", "редактор субтитрів",
109 "спасибо", "спасибо за просмотр", "продолжение следует", "подписывайтесь на канал", "субтитры", "редактор субтитров",
110 "untertitel", "untertitel im auftrag des zdf", "sous-titres", "sous-titrage", "merci", "gracias", "subtítulos",
111]
112_STOCK_RE = re.compile(r'^(?:(?:' + '|'.join(re.escape(p) for p in sorted(_STOCK, key=len, reverse=True))
113 + r')[\s.,!?…]*)+$', re.IGNORECASE)
114
115
116def _made_up(seg: dict, text: str) -> bool:
117 """A stock phrase where the audio shows no clear speech, or one stretched over a long stretch of audio."""
118 plain = re.sub(r'[\[\]()♪*#~-]', ' ', text).strip()
119 if not plain:
120 return True
121 length = float(seg.get('end') or 0) - float(seg.get('start') or 0)
122 if length > 20 and len(plain) < length:
123 return True
124 if not _STOCK_RE.match(plain):
125 return False
126 return (float(seg.get('no_speech_prob') or 0) > 0.3 or float(seg.get('avg_logprob') or 0) < -0.7
127 or length > 3 + len(plain) / 4)
128
129
130
131
132
133GLOSSARY = {
134 'en': 'Kyiv, Lviv, Kharkiv, Odesa, Dnipro, Zaporizhzhia, Vinnytsia, Mykolaiv, Kherson, Chernihiv, Poltava, '
135 'Ivano-Frankivsk, Ternopil, Lutsk, Rivne, Uzhhorod, Chernivtsi, Zhytomyr, Sumy, Cherkasy, Kryvyi Rih, Mariupol.',
136 'uk': 'Київ, Львів, Харків, Одеса, Дніпро, Запоріжжя, Вінниця, Миколаїв, Херсон, Чернігів, Полтава, '
137 'Івано-Франківськ, Тернопіль, Луцьк, Рівне, Ужгород, Чернівці, Житомир, Суми, Черкаси, Кривий Ріг, Маріуполь.',
138 'ru': 'Киев, Львов, Харьков, Одесса, Днепр, Запорожье, Винница, Николаев, Херсон, Чернигов, Полтава, '
139 'Ивано-Франковск, Тернополь, Луцк, Ровно, Ужгород, Черновцы, Житомир, Сумы, Черкассы, Кривой Рог, Мариуполь.',
140}
141
142
143def _prompt(vocabulary: str | None, language: str | None) -> str:
144 """The user's own vocabulary first, then the place names for the spoken language (none when it is detected)."""
145 names = GLOSSARY.get(language, '') if language else ''
146 return ' '.join(p for p in ((vocabulary or '').strip()[:400], names) if p)
147
148
149def _prompt_words(prompt: str) -> set[str]:
150 return {w for w in re.findall(r'\w+', prompt.lower()) if len(w) >= 3}
151
152
153_LATIN_SCRIPT = {'english', 'german', 'french', 'spanish', 'portuguese', 'italian', 'polish', 'dutch', 'turkish', 'czech',
154 'romanian', 'swedish', 'indonesian', 'vietnamese', 'danish', 'norwegian', 'finnish', 'hungarian',
155 'slovak', 'croatian', 'lithuanian', 'latvian', 'estonian', 'malay', 'tagalog', 'swahili'}
156
157
158def _echoed(res: dict, words: set[str]) -> bool:
159 """Whisper sometimes writes out its prompt instead of the speech ("Київ, Львів, Харків..." over an English
160 recording, with the names misspelled). Signs: a segment or most of the chunk made of prompt words, or text in
161 Cyrillic where Whisper itself detected a Latin-script language."""
162 if not words:
163 return False
164 text = ' '.join(s.get('text') or '' for s in res.get('segments') or [])
165 letters = re.findall(r'[^\W\d_]', text)
166 cyrillic = sum(1 for c in letters if '\u0400' <= c <= '\u04ff')
167 if (res.get('language') or '').lower() in _LATIN_SCRIPT and letters and cyrillic > 0.5 * len(letters):
168 return True
169
170 def hits(part):
171 found = re.findall(r'\w+', part.lower())
172 return len(found), sum(1 for w in found if w in words or difflib.get_close_matches(w, words, 1, 0.7))
173 total = hit = 0
174 for s in res.get('segments') or []:
175 n, h = hits(s.get('text') or '')
176 if n >= 4 and h >= 0.5 * n:
177 return True
178 items = [p.strip() for p in re.split(r'[,.;]', s.get('text') or '') if p.strip()]
179 if (len(items) >= 6 and all(len(p.split()) <= 2 and p[0].isupper() for p in items)
180 and h >= 0.3 * n):
181 return True
182 total, hit = total + n, hit + h
183 return total >= 3 and hit >= 0.5 * total
184
185
186_ISO = {'english': 'en', 'ukrainian': 'uk', 'russian': 'ru', 'german': 'de', 'french': 'fr', 'spanish': 'es',
187 'portuguese': 'pt', 'italian': 'it', 'polish': 'pl', 'dutch': 'nl', 'turkish': 'tr', 'czech': 'cs',
188 'romanian': 'ro', 'swedish': 'sv', 'arabic': 'ar', 'hindi': 'hi', 'indonesian': 'id', 'vietnamese': 'vi',
189 'chinese': 'zh', 'japanese': 'ja', 'korean': 'ko'}
190GAP_SECONDS = 5.0
191MIN_SPEECH = 2.0
192MAX_GAPS = 30
193
194
195def _sound_seconds(path: str, start: float, length: float) -> float:
196 """Seconds of sound (not silence) in a stretch of the file, by ffmpeg's silencedetect."""
197 res = subprocess.run(['ffmpeg', '-v', 'info', '-nostats', '-ss', f'{start:.3f}', '-t', f'{length:.3f}', '-i', path,
198 '-vn', '-af', 'silencedetect=noise=-35dB:d=0.6', '-f', 'null', '-'],
199 capture_output=True, text=True, timeout=300)
200 silent, opened = 0.0, None
201 for line in res.stderr.splitlines():
202 m = re.search(r'silence_start: (-?[\d.]+)', line)
203 if m:
204 opened = max(0.0, float(m.group(1)))
205 m = re.search(r'silence_duration: ([\d.]+)', line)
206 if m:
207 silent, opened = silent + float(m.group(1)), None
208 if opened is not None:
209 silent += max(0.0, length - opened)
210 return max(0.0, length - silent)
211
212
213def _candidates(segments: list[dict], duration: float) -> list[tuple[float, float, int | None]]:
214 """(start, end, index of the near-empty segment or None for a gap between segments) where speech may be missing."""
215 out, prev_end = [], 0.0
216 for i, s in enumerate(segments):
217 if s['start'] - prev_end >= GAP_SECONDS:
218 out.append((prev_end, s['start'], None))
219 length = s['end'] - s['start']
220 if length >= GAP_SECONDS and len(s['text']) < 2 * length:
221 out.append((s['start'], s['end'], i))
222 prev_end = max(prev_end, s['end'])
223 if duration - prev_end >= GAP_SECONDS:
224 out.append((prev_end, duration, None))
225 return out
226
227
228def _fill_gaps(client, path: str, workdir: str, segments: list[dict], duration: float, *, model: str,
229 language: str | None) -> tuple[list[dict], list[dict]]:
230 """Re-recognises stretches where Whisper wrote nothing or one word over seconds of sound (it sometimes skips a
231 sentence or two). Returns the segments with the found speech put in, and the list of such places."""
232 gaps, replace, add = [], set(), []
233 for n, (start, end, idx) in enumerate(_candidates(segments, duration)):
234 if n >= MAX_GAPS or _sound_seconds(path, start, end - start) < MIN_SPEECH:
235 continue
236 cut = os.path.join(workdir, f'gap-{n:03d}.mp3')
237 lo, hi = start, min(duration, end + 0.3)
238 r = subprocess.run(['ffmpeg', '-v', 'error', '-y', '-ss', f'{lo:.3f}', '-t', f'{hi - lo:.3f}', '-i', path,
239 '-vn', '-ac', '1', '-ar', '16000', '-b:a', '32k', cut], capture_output=True, timeout=300)
240 if r.returncode != 0 or not os.path.exists(cut):
241 continue
242 res = transcribe_chunk(client, cut, model=model, language=language, prompt=None)
243 found = []
244 for s in res.get('segments') or []:
245 text = (s.get('text') or '').strip()
246 if (text and not _silence(s) and not _made_up(s, text) and float(s.get('no_speech_prob') or 0) < 0.5
247 and float(s.get('avg_logprob') or 0) > -1.0):
248 found.append({'start': round(lo + float(s['start']), 2), 'end': round(min(lo + float(s['end']), hi), 2),
249 'text': text})
250 old = segments[idx]['text'] if idx is not None else ''
251 new = ' '.join(s['text'] for s in found)
252 if len(new) >= max(20, 3 * len(old)):
253 gaps.append({'start': round(start, 2), 'end': round(end, 2), 'status': 'filled', 'text': new})
254 add += found
255 if idx is not None:
256 replace.add(idx)
257 else:
258 gaps.append({'start': round(start, 2), 'end': round(end, 2), 'status': 'unclear', 'text': old})
259 if add:
260 segments = sorted([s for i, s in enumerate(segments) if i not in replace] + add, key=lambda s: s['start'])
261 return segments, gaps
262
263
264def transcribe(path: str, workdir: str, *, quality: str = 'accurate', language: str | None = None,
265 prompt: str | None = None, max_minutes: int | None = None, media_seconds: float | None = None) -> dict:
266 """Returns {'text', 'segments', 'language', 'duration', 'minutes', 'truncated', 'model', 'gaps'}. media_seconds: the video's own
267 length from the site; audio past it (a longer music track) is not transcribed."""
268 duration = probe_duration(path)
269 if media_seconds and media_seconds > 0:
270 duration = min(duration, media_seconds + 1)
271 truncated = False
272 if max_minutes is not None and duration > max_minutes * 60:
273 duration, truncated = max_minutes * 60.0, True
274 model = MODELS.get(quality, MODELS['accurate'])
275 segments, texts, detected = [], [], None
276 prompt = _prompt(prompt, language)
277 words = _prompt_words(prompt)
278 with httpx.Client(timeout=httpx.Timeout(300, connect=30)) as client:
279 for chunk, offset in make_chunks(path, workdir, duration):
280 tail = texts[-1][-200:] if texts else ''
281 res = transcribe_chunk(client, chunk, model=model, language=language,
282 prompt=(prompt + ' ' + tail).strip())
283 if _echoed(res, words):
284 res = transcribe_chunk(client, chunk, model=model, language=language, prompt=tail or None)
285 detected = detected or res.get('language')
286 texts.append((res.get('text') or '').strip())
287 for s in res.get('segments') or []:
288 text = (s.get('text') or '').strip()
289 if _silence(s) or _made_up(s, text):
290 continue
291 if segments and segments[-1]['text'] == text and offset + float(s['start']) - segments[-1]['end'] < 2:
292 continue
293 if text and offset + float(s['start']) < duration:
294 segments.append({'start': round(offset + float(s['start']), 2),
295 'end': round(min(offset + float(s['end']), duration), 2), 'text': text})
296 segments, gaps = _fill_gaps(client, path, workdir, segments, duration, model=model,
297 language=language or _ISO.get((detected or '').lower()))
298
299 texts = [' '.join(s['text'] for s in segments)] if segments else []
300 return {'text': '\n'.join(t for t in texts if t), 'segments': segments, 'language': detected,
301 'duration': round(duration, 2), 'minutes': max(1, math.ceil(duration / 60)), 'truncated': truncated,
302 'model': model, 'gaps': gaps}
303
304
305def _ts(seconds: float, sep: str) -> str:
306 ms = int(round(seconds * 1000))
307 h, ms = divmod(ms, 3_600_000)
308 m, ms = divmod(ms, 60_000)
309 s, ms = divmod(ms, 1000)
310 return f'{h:02d}:{m:02d}:{s:02d}{sep}{ms:03d}'
311
312
313def to_srt(segments: list[dict]) -> str:
314 return '\n'.join(f"{i}\n{_ts(s['start'], ',')} --> {_ts(s['end'], ',')}\n{s['text']}\n"
315 for i, s in enumerate(segments, 1))
316
317
318def to_vtt(segments: list[dict]) -> str:
319 return 'WEBVTT\n\n' + '\n'.join(f"{_ts(s['start'], '.')} --> {_ts(s['end'], '.')}\n{s['text']}\n" for s in segments)