Boundary and failure

This tool handles videos other people made. That makes “what leaves this machine” as important as the feature list.

So the boundary is written down explicitly, where you can read it without reading the code.

What leaves, and what doesn’t

• The video itself is never uploaded anywhere. The only thing that leaves is audio, and only when captions are missing — re-encoded to mono 16 kHz at that.
• It never logs into any platform account. No session cookies, no posting, no subscriptions. Public things, fetched the public way.
• Keys never cross providers. One provider’s key never travels to another’s endpoint.
• Keys are never written to logs, output, or files. The path by which they could leak simply isn’t built.
• Nothing persists outside the working directory and the config file. The working directory gets cleaned up at the end.

The list looks long, but holding one rule makes the rest follow — send outside only the minimum required. Had the design been “upload the whole video and let a service analyse it,” all five lines above would be meaningless.

Setup is checked every time, and stays quiet when it passes

Every invocation checks that the required tools are installed. When they all are, it says nothing and gets on with it.

There’s one reason to check up front. Dying halfway through, without the tool, is the worst outcome. The video is already downloaded and the frames extracted, and if it stops at transcription, that time and disk are simply gone. Thirty seconds of checking, and not starting, is far cheaper.

And when the check fails it doesn’t just error — it prints the install commands. If a person has to leave and go searching at that point, that session usually doesn’t come back. “What’s missing” and “how to get it” have to be on the same screen.

When it can’t, it says it can’t

There’s one rule in failure handling: no retry loops.

• Login-required videos — say so and stop. No working around it.
• Region-locked — same. No hunting for another route.
• Download failure — show the underlying tool’s error verbatim. Don’t summarise or smooth it.

Handle those three as “that failed, try another way” and the tool changes character. A tool that only sees what was made accessible and a tool that gets past access controls are different things, and I only meant to build the first.

The reason errors aren’t smoothed is the same. The original message contains why it failed; compress it into “could not fetch the video” and what to do next disappears with it.

The long-video warning goes into the result

Past ten minutes a warning fires about sparse sampling. That warning doesn’t just go to a log — it’s repeated in the answer.

A sparsely sampled result and a densely sampled one have different reliability, and both are written with the same confidence. So attaching how densely it was actually sampled is the minimum honesty this tool can manage.

Same reason a missing transcript is recorded as “none.” It’s the thing this site keeps coming back to: an omission you don’t write down doesn’t become undone — it becomes invisible.