filler-removal

name	filler-removal
description	Remove filler words and disfluencies (um, uh, like, you know, basically) from a talking-head video so it sounds like they were never said. Use whenever the user wants to clean up speech, cut filler/hesitations, tighten a voiceover, or remove "um"s and "uh"s. Covers verbatim transcription, precise cutting rules, and the iterate-until-clean preview loop.

Filler-word removal

Goal: cut filler words so the result sounds natural — no clipped consonants, no abrupt audio jumps, no real speech lost. This is an iterative process; do not stop at the first pass.

Step 0 (CRITICAL): get a verbatim transcript

mlx-whisper silently cleans disfluencies by default — it drops most "um/uh" from the transcript, so there's nothing to cut. This was the root cause of a past failure where fillers survived the edit.

transcribe is now verbatim by default: it seeds the decoder with a short hesitation prompt (Um, uh, er, hmm...) and condition_on_previous_text=False, so um/uh are kept. Just run:

uv run video-agent transcribe video.mp4 --words -o words.txt   # start_sec  end_sec  word

Do not pass --clean here — that restores whisper's filler-dropping behavior, the opposite of what you want.

The seed prompt is deliberately narrow (only short hesitations) to avoid over-transcribing real words like "like"/"so". If the user reports fillers that still aren't in the list, listen to the audio span directly to confirm what was actually said before concluding nothing is there.

Step 0.5 (CRITICAL): cross-check word boundaries against silence

Whisper word timestamps are jittery and unreliable for the actual cut — they can be off by 0.3–0.7s, and re-running transcription gives different positions for the same word. Cutting on the raw word timestamp landed a real edit in the wrong place (the filler survived; a chunk of silence got removed instead). Always verify the boundary before cutting: