Punctuation in fractional seconds

SRT:  00:00:01,240
VTT:  00:00:01.240

SRT uses a comma before the milliseconds; WebVTT uses a dot. Everything else in the timestamp — two-digit hours, minutes and seconds, exactly three digits of milliseconds — is the same.

This one character is the most common reason a subtitle track silently does not appear. A .vtt file with commas is not merely unusual, it is invalid: the parser reads 00:00:01,240 as text rather than as a cue timestamp, and a player is under no obligation to tell you that it skipped it. You get a track that loads, shows nothing, and logs nothing. Conversely, an .srt file with dots will be rejected by players that validate strictly.

WebVTT adds one more flexibility that SRT does not have: the hours field may be omitted, so 01:24.000 is a legal VTT timestamp meaning one minute twenty-four seconds. SRT always wants all three components. If you are generating VTT by hand, this is a nice shortcut; if you are writing a converter, it is a case you must handle on input and normalise on output.

Cue numbering

Every SRT cue starts with an index:

1
00:00:01,240 --> 00:00:04,760
The first line of dialogue goes here.

2
00:00:04,900 --> 00:00:08,100
And the second cue starts after a blank line.

WebVTT does not use sequence numbers. The block may optionally carry an identifier before the timestamp — a string, not a counter — and it is used for referencing the cue from a script or from CSS, not for ordering. Writing 1, 2, 3 in a VTT file is tolerated by lenient parsers because such a line is a valid identifier, and that tolerance is a trap: the file works in the browser you tested it in and falls apart in the one you did not.

The practical consequence for conversion is that VTT → SRT has to invent numbering, and SRT → VTT has to remove it. A converter that just swaps commas for dots and leaves the numbers in place produces a file that mostly works and occasionally shows a stray digit on screen. (If you are converting, that is one of the things our free SRT ↔ VTT converter handles.)

The WEBVTT header is mandatory

A WebVTT file must begin with the line:

WEBVTT

followed by a blank line before the first cue. A UTF-8 byte-order mark in front of it is allowed; anything else is not. Some players accept a file without the header, which is how people ship broken VTT for months without noticing.

After the header you may add header metadata — key/value lines such as Kind: captions or Language: en. Those are legal before the first blank line and nowhere else. Copy them into an SRT file and they become the first subtitle the viewer sees.

Service blocks are not subtitles

WebVTT has three block types that carry no dialogue at all:

• NOTE — a comment block. Everything until the next blank line is ignored by the player. Purely for humans.
• STYLE — CSS that applies to the cues that follow. This is how WebVTT does styling; SRT has no styling mechanism beyond crude <b>/<i> tags.
• REGION — a named screen area that cues can be positioned into.

These are the reason a naive converter produces a video with a CSS rule burned across the bottom of the frame. When a NOTE or STYLE block is copied into SRT, it stops being a comment and becomes text, because SRT has no concept of either one. Converting VTT → SRT has to delete those blocks, not translate them.

The same applies to cue settings, which sit on the timestamp line itself:

00:00:01.240 --> 00:00:04.760 align:middle line:90%

align, line, position, size and vertical are WebVTT positioning instructions. SRT cannot express any of them. If your conversion keeps the tail of the timestamp line, every cue shows align:middle line:90% on screen next to the dialogue. The only correct behaviour for SRT output is to drop them — the text keeps its content and loses its positioning, which is the best that the format allows.

Timecode shift: the fix for a re-cut video

Subtitles almost never break because of punctuation; they break because the video changed. You added a three-second logo at the front, or removed an intro, and now every cue is late or early by a constant offset.

It is worth understanding that a shift is a single constant applied to every timestamp in the file. Subtracting 3.5 seconds from all cues is not the same as moving the first cue: if the audio was re-cut in the middle as well, no constant will save you, and you need to re-transcribe. But for a uniform intro/outro change — by far the common case — one offset is exactly right.

Two details that matter in practice:

• Negative results. If you shift a file 30 seconds earlier and a cue starts at 12 seconds, the arithmetic gives a negative timestamp. Clamping to 00:00:00,000 is the sane behaviour; a converter that writes -00:00:18 produces a file that no player will load.
• Finding the offset. Do not guess. Pick a sentence you can hear clearly, note the timecode it should have, note the timecode it has, and use the difference. Our converter applies one offset, positive or negative, to all cues at once.

The 42-characters-per-line norm

Readability guidelines for subtitles are old and convergent: up to 42 characters per line, at most two lines per cue. The number comes from broadcast practice — it is roughly what a viewer can read at a glance without stopping to parse the line, and it keeps the text inside the safe area on a 16:9 frame.

Two lines is not a stylistic choice either. A three-line cue covers a meaningful part of the picture, and the third line is very often not read at all.

In practice this is the difference between subtitles and a transcript pasted onto video. A mechanical conversion from JSON with per-word timings, or from a paragraph-based SRT, produces lines that are 90 characters long and get clipped at the frame edge. Both our converter and our transcription service wrap at 42 characters by default — the converter has the limit as a configurable option, and the SRT that the transcription service produces is already wrapped to it.

Smaller things that still break files

• Empty cues. A block with a timestamp, a blank line and no text is legal, and useless: it flashes an empty caption and, in some converters, shifts the numbering downstream. Converting should drop them and renumber the rest.
• Encoding. Both formats are text and both are expected to be UTF-8. A Windows-1251 SRT that displayed fine in VLC becomes a screen of replacement characters in a browser player.
• Line endings. CRLF and LF are both accepted in practice, but mixing them inside one file is a reliable way to make one parser in a chain unhappy; a converter should preserve what the source used.
• Overlapping cues. SRT has no mechanism for two cues on screen at once in a defined order. Merging an SRT with a second one usually produces overlapping blocks that the player resolves in whatever order the file happens to be in.

Which format to use

• SRT when the consumer is a person's software: desktop players, video editors, broadcast tooling, most offline workflows. It is the lowest common denominator and almost nothing refuses it.
• VTT when the consumer is a web page: HTML5 <track> elements, browser players, most online video platforms. You also get styling and positioning if you need them.

So the workflow that holds up is: generate SRT once from the audio with word-level timings, keep the JSON for anything that needs a re-cut, convert to VTT for the web version, and shift the timecodes rather than regenerating when the edit only touches the beginning or the end.

If you want to see the differences rather than read about them, our converter runs entirely in the browser — the file is never uploaded, the page keeps working offline once it has loaded, and both the SRT and VTT sides of the equation are visible in the same text box:

• Subtitle converter: SRT ↔ VTT, timecode shift, 42-character wrap
• Speech-to-text: get SRT, plain text and word-level JSON from audio or video
• HTTP API for batch processing

The constraints I set for myself up front:

• one VPS, no external queues or brokers;
• no dependencies beyond the system ffmpeg/ffprobe — so that an update means replacing one file and restarting a systemd unit;
• recognition and synthesis go straight to Yandex SpeechKit v3, with no middleware;
• user files are not kept longer than a day;
• cost has to be predictable: the service must not run at a loss because someone else's script uploads hour-long recordings all night.

What came out is a single Python 3.12 file of roughly 2,200 lines: http.server with threads, sqlite3 as the job queue, urllib for everything external, ffmpeg for conversion. Below is what turned out to be non-obvious in this construction. Not a tutorial — a field notes collection of the places it bites.

Why the standard library was enough

The stock ThreadingHTTPServer cannot cap the number of concurrent connections: on a slow client it happily spawns thread after thread until file descriptors run out. I needed my own subclass — with a pool of 32 connection slots and a 120-second request read timeout. Everything else is ordinary routing: file upload via multipart, a JSON API for job status, result delivery, and the payment provider's webhook.

The queue is hand-rolled too, and it is surprisingly boring: a jobs table in SQLite, two worker threads, the statuses queued → processing → done|error, and a stage field holding a human-readable string like "converting" or "recognizing". Here sqlite3 works as an ordinary job log rather than a high-load database: one row written per job, one row read per status poll.

What that bought in practice: deploying the service is scp of one file plus systemctl restart. No pip install, no migrations, no "your library version is wrong".

The public REST API is documented at bowhard.ru/api, and since I am not the only one who wanted to drive this from a script, there are small clients for Python and Node — that is how the transcription and text-to-speech services at bowhard.ru/rasshifrovka and bowhard.ru/ozvuchka are consumed from automation.

Recognition: asynchronous, because the file is long

SpeechKit can do synchronous recognition, but that is for short utterances. An hour-long recording means recognizeFileAsync: send a job, get an operationId, poll the status until it is done. Poll every two seconds, with a three-hour deadline. Going below two seconds is pointless — the operation cannot have finished anyway, and you are just hammering the API for nothing.

The input to SpeechKit comes in two flavours, and the choice between them is not cosmetic:

• content — audio as base64 inside the request body. Fine for small files, but base64 inflates the size by about a third, and holding an encoded hour-long recording in memory is not a great idea;
• uri — a link to an object in S3-compatible storage. We adopted a rule: files from 8 MB up go to Object Storage, anything smaller goes as base64. The threshold was picked from process memory: 8 MB in base64 is roughly an 11 MB string, which is perfectly safe for two workers.

The result of getRecognition is not JSON but a stream of JSON lines, one object per line — that is the first non-obvious thing. It contains both the plain recognized words and a finalRefinement.normalizedText.alternatives block. The words are needed for timings, but they carry no punctuation and no capital letters. The finished text with punctuation lives in the text field of that same normalizedText block. So we take the text from there, the timings from the word array, and splice the two into a single result.

Subtitles are assembled from that same result. SRT is a format that forgives a lot except two things: over-long lines and overlapping timecodes. We break the line by words, never letting it exceed 42 characters, and wrap only at a word boundary. A subtitle block looks like this:

• the block number line — 12;
• the time line — 00:01:04,320 --> 00:01:07,880, with milliseconds separated by a comma, as the format requires;
• one or two lines of text, split by words and no longer than 42 characters each — and we decided not to touch that part.

The timecodes come straight from the words, so the subtitles end up denser than when you slice by sentences, and they do not drift on fast speech. The user gets three files: the text, the .srt, and a json with the words and their timings — the last one is for anyone who wants word highlighting in a player.

Text-to-speech: 240 characters that nearly broke everything

Synthesis in v3 is called through the utteranceSynthesis method, and it has a limit on text length that the documentation says approximately nothing about. It emerged empirically: 250 characters pass, 500 come back as a refusal reading "Too long text". And the refusal does not always arrive straight away: sometimes it looks like a dropped connection, and had I not been logging the response body, I would have hunted for the cause for a long time.

The fix is to cut the text into chunks of 240 characters, and to do it on sentence boundaries rather than by a character counter. It is inaudible, and the price is computed from the source character count, so the splitting does not affect the cost at all.

Then comes the pleasant part: MP3 is a sequence of independent frames, so the synthesized chunks are joined by plain byte concatenation, with no re-encoding and no ffmpeg. But if you cut the text crudely, mid-sentence, you can hear an unnatural pause at the seam — which is why the splitting happens at periods, question marks and exclamation marks.

Two more things about synthesis. First: the v1 API costs roughly twice as much as v3 for the same result, so you should go straight to v3. Second: the speed parameter is accepted in the range 0.5–2.0, and anything outside it has to be clamped on your side, otherwise you get an error in the middle of a long text. SpeechKit has fifteen voices — from the neutral "Alena" to the conversational "Zakhar" — and for internal recordings the difference between them is far more noticeable than for advertising ones.

The queue, the ceilings, and the money fuse

The nastiest class of bug in a service like this is not a crash but quietly burning money. So the ceilings are set at every level:

• no more than three jobs in flight per visitor;
• no more than 600 MB of uploads per day from one address;
• no more than 10 link imports per hour;
• the job directory cannot exceed 6 GB — past that, new jobs are refused until cleanup runs;
• and the main fuse: a daily cost ceiling. If the total recognition cost for the day exceeds a configured threshold, the service stops accepting new jobs and says so plainly, instead of running at a loss until morning.

A separate trap in the same area is balance accounting. Transcription is measured in minutes of audio, text-to-speech in characters. It is natural to keep both in one credits table, but if you compute usage as one combined sum you get nonsense: minutes get eaten by synthesis, characters by transcription, and the balance goes negative out of nowhere. Usage has to be counted separately per kind of work, and the interface has to show two independent balances. In the code this story survives as a comment — as a reminder.

Link import: SSRF is not only about the URL

A "paste a link to a file" feature saves the user time and creates a whole class of risk. Ours is narrowed to two providers: public Yandex Disk files (via cloud-api.yandex.net) and Dropbox. The list of trusted hosts is an allowlist, not a denylist, and the check is repeated after redirects: a provider may send you to another domain, and that is fine, but only if that domain is on the list too.

Timeouts are split as well: 30 seconds for the provider's response and 600 seconds for the download itself, otherwise the service turns into a free relay for other people's slow files. Plus a per-address attempt counter. A dedicated self-test command exercises these scenarios: selftest_links, selftest_sign, selftest_net — three buttons that ask "check that the outside world is still what we think it is".

Payments: we do not trust the webhook

Payment goes through YooKassa, and there is exactly one rule here that must not be broken: a webhook is not confirmation of a payment. It is only a reason to re-check. The scheme is this: the payment is created in the database up front with a "created" status; on notification the service makes a separate GET /payments/{id} request to the payment provider's API, looks at the real status, and only then credits the balance.

The crediting itself must happen exactly once, because webhooks repeat. Instead of "read the flag, write the credit", a conditional update is used: UPDATE payments SET paid_at = ? WHERE id = ? AND paid_at IS NULL, and the credit is granted only if that statement actually changed a row. This is cheaper and more reliable than any lock in the application: the race between two simultaneous webhooks is settled by the database.

Storage: signing SigV4 by hand

Files from 8 MB up go to S3-compatible Object Storage. I did not want to pull in an SDK for four operations (PUT, GET, DELETE, HEAD), so the AWS SigV4 signature is assembled by hand on urllib — and that turned out to be the most capricious part of the whole project.

Two traps, both diagnosed equally unpleasantly — just a 403 with no explanation:

1. x-amz-content-sha256 has to appear both in the canonical headers and in the SignedHeaders list. The header is sent, the hash is computed, and the signature still does not match, because it is missing from the list being signed.
2. Sub-resources such as ?lifecycle are written in the canonical request as lifecycle= — with an empty value. Leave them as they are and you get SignatureDoesNotMatch on a request that looks externally flawless.

Once the signature is assembled, though, everything else is trivial: put the object — hand SpeechKit the link — delete the object after cleanup. Job files live for 24 hours: that promise is written on the service page, which means the background cleanup has to honour it literally rather than "eventually". Statistics records are kept for 90 days — enough to understand load and compute cost.

What I would do differently

The SpeechKit client should have been extracted into a separate module from week one: right now the recognition, synthesis and queue logic all live in one file, and that is convenient exactly until the moment you want to run synthesis from a separate script. Second — progress for long operations: today it shows the stage and a speed estimate based on already-processed jobs, but an honest completion fraction for an hour-long recording would be more useful. Third — move the free-tier limits into config rather than code: those are the ones you want to change more often than anything else.

Otherwise the construction "one file, stdlib, SQLite and system ffmpeg" has held up better than I expected: the service handles recordings up to four hours, recognizing an hour-long file takes less time than the recording itself lasts, and updating it requires neither a build nor dependencies.

If you want to drive this from an automation platform rather than from code, there are ready-made n8n workflow templates for both transcription and synthesis. And if you build something similar, the most expensive time will go not into SpeechKit but into the S3 signature and the balance accounting — start with those.