You've got a two-hour architecture review sitting in your Downloads folder. Last month, mine was a 94-minute mess where three engineers talked over each other to debug a stuck Kafka consumer. I needed that in text. Not because I enjoy typing, but because text is searchable, diff-able, and way easier to share than a raw MP3. Manual transcription burns hours you don't have. Automated tools get you 90% there, but the last 10% is what separates a usable transcript from word salad.
For developers, text wins over audio every time. You can't grep a WAV file. You can't copy a function name from a podcast without listening to fifteen minutes of chatter. Once audio is text, you can index it, run diffs, feed it to an LLM, or generate subtitles. A single recording turns into searchable meeting notes, blog drafts, or captioned tutorials. It also makes content accessible to screen readers and non-native speakers.
Before you upload anything, pick your approach. There are three realistic options.
Automated APIs or local models. Tools like OpenAI Whisper running locally, or cloud speech APIs. Fast, cheap, and fine for clear audio with minimal crosstalk.
Manual transcription. You listen, you type. Still the best choice for courtroom-level accuracy or audio recorded in a crowded hallway.
Hybrid. Automated first, then a quick editorial pass. This is the default for technical content and the workflow I'll break down below.
If your recording is a screen share, a meeting, or a solo voice memo, go automated. If two people shouted over each other in a cafe, manual might be faster than fixing chaos.
Garbage in, garbage out. Models struggle with low bitrate, stereo separation, and background hum. Normalize your file before you process it.
Most tools accept MP3, WAV, M4A, MP4, and OGG. For speech recognition, mono WAV at 16 kHz is the safest bet. Use ffmpeg to clean things up:
ffmpeg -i input.mp4 -ar 16000 -ac 1 -c:a pcm_s16le cleaned.wav
ffmpeg -i cleaned.wav -af "silenceremove=start_periods=1:start_duration=0.5:start_threshold=-50dB" final.wav
Check your levels. If the waveform looks like a flat line or a brick wall, fix it before you waste a transcription run. I learned this the hard way after Whisper produced five minutes of hallucinated text from a track that was only audible in the left stereo channel. Mono fixes that.
You have two practical paths. Run Whisper locally if you care about privacy and cost. Hit an API if you want zero setup.
Local Python with Whisper:
import whisper
model = whisper.load_model("base") # or "small", "medium", "large"
result = model.transcribe("final.wav")
print(result["text"])
Cloud API route:
from openai import OpenAI
client = OpenAI()
audio_file = open("final.wav", "rb")
transcript = client.audio.transcriptions.create(
model="whisper-1",
file=audio_file,
response_format="json"
)
print(transcript.text)
A thirty-minute file usually finishes in under a minute locally on a modern laptop. Cloud is roughly real-time or faster.
I used to run base
for everything. Then I watched it turn "Kubernetes deployment" into "coorneddies deployment" during a mumbled standup. For anything with proper nouns, CLI commands, or made-up product names, medium
or large
is worth the extra seconds.
Don't just dump the text string. The JSON output contains segments with start and end times. You will need those for subtitles or for referencing specific moments.
segments = result["segments"] # or transcript.segments depending on your client
for seg in segments:
start = seg["start"]
end = seg["end"]
text = seg["text"].strip()
print(f"[{start:.2f}s -> {end:.2f}s] {text}")
Store this as an intermediate JSON file. It is much easier to format later than re-running inference.
Raw transcripts are messy. Fillers, repeated words, and homophone errors creep in. Here is an actual snippet from that Kafka call:
[14:23] okay so um if you look at the um the logs it looks like the uh consumer group is like stuck and you know the lag is just um growing
My first thought was a regex to nuke every "um", "uh", "like", and "you know". I tried it. Then I ran it on a different transcript about Postgres and watched "you know, use a LIKE clause" turn into "use a clause". Not great.
Now I keep cleanup conservative. I only strip obvious stumbles, and I leave sentence words alone. Here is what actually runs:
import re
def clean_chunk(text):
text = re.sub(r'\s*\b(uh|um)\b[,.;:]?\s*', ' ', text, flags=re.IGNORECASE)
text = re.sub(r'\s+', ' ', text)
text = re.sub(r'\s+([.,;!?])', r'\1', text)
return text.strip()
for seg in segments:
seg["text"] = clean_chunk(seg["text"])
You will still need to eyeball technical terms. Whisper loves to hallucinate "main" as "mane" or turn "kubectl" into "cube cuddle" if the speaker trails off. A quick grep for your known terms catches the worst offenders.
If you are building subtitles, export SRT or VTT. If you are building notes, Markdown with timestamps works better.
Markdown formatter:
def to_markdown(segments, title="Meeting Notes"):
lines = [f"# {title}\n"]
for seg in segments:
t = seg["start"]
lines.append(f"**[{t//60:02.0f}:{t%60:02.0f}]** {seg['text']}")
return "\n\n".join(lines)
Speaker labels are harder. Whisper does basic speaker diarization in newer versions, but it is not perfect. For two-person interviews, you can often infer the speaker from context. For group meetings, consider a dedicated diarization tool like pyannote.audio, then merge the outputs.
I tried pyannote on a five-person standup once. It worked, but the dependency chain was heavier than the transcript itself. For 1:1s, I skip it. For all-hands, I bite the bullet.
Match the format to the destination.
Markdown for blog posts or documentation.
SRT or VTT for video subtitles.
Plain text for LLM context windows.
with open("output.txt", "w") as f:
f.write("\n".join([s["text"] for s in segments]))
One recording should have multiple lives. Turn a tech talk transcript into a docs page, a Twitter thread, and a set of searchable meeting notes without re-listening to the whole thing.
Even large models hallucinate on jargon, acronyms, and numbers. Expect to spend five to ten minutes editing per thirty minutes of clean audio. Budget more if speakers overlap or if the content is heavy on CLI commands and made-up product names.
If your API supports it, pass a prompt with domain context. For Whisper, the initial_prompt
parameter lets you seed terms like "Next.js, Redis, and kubectl" so the model knows the vocabulary ahead of time.
During that Kafka review, seeding "consumer lag, partition, and rebalance" stopped Whisper from inventing "consumer leg" and "reborn". Small prompt, big difference.
Before you publish or archive:
Transcription is not magic. It is just another data transformation. Prep your audio, run inference, clean the output, and ship it. Your future self will thank you when you can grep last month's architecture decision in under a second.