Skip to content

fix: clear actionable error when ffmpeg/ffprobe is missing#182

Open
seonghobae wants to merge 1 commit into
mainfrom
feat/ffmpeg-error-ux
Open

fix: clear actionable error when ffmpeg/ffprobe is missing#182
seonghobae wants to merge 1 commit into
mainfrom
feat/ffmpeg-error-ux

Conversation

@seonghobae

Copy link
Copy Markdown
Contributor

Problem

When ffmpeg/ffprobe is not installed or not on PATH, probe_media and detect_silence_intervals let subprocess.run raise a bare FileNotFoundError:

FileNotFoundError: [Errno 2] No such file or directory: 'ffprobe'

That is a raw traceback with zero guidance. Because probe_media runs first in the conversion pipeline, this is the error users actually hit when ffmpeg isn't installed — long before reaching _execute_plan, which was already guarded. "ffmpeg not installed" is one of the most common user failures, so a clear message is genuine value.

Fix

  • Add a shared _run_media_tool() helper that runs an ffmpeg/ffprobe command and maps a missing binary to a MediaShrinkerError that names the tool and how to install it (brew install ffmpeg / sudo apt install ffmpeg).
  • Route all three ffmpeg/ffprobe invocation sites (probe_media, detect_silence_intervals, _execute_plan) through it. This also unifies and improves _execute_plan's previously terse ffmpeg not found: <path> message.
  • Nonzero-exit / stderr handling stays at each call site; only the tool-invocation FileNotFoundError path changes. No parsing, bitrate, or output-validation logic touched.

Tests

TDD: added two tests asserting a clear MediaShrinkerError (naming the binary + "Install ffmpeg") when subprocess.run raises FileNotFoundError for missing ffprobe (probe_media) and missing ffmpeg (detect_silence_intervals). Both fail on the old raw-FileNotFoundError behavior.

Gates

  • coverage report --include=media_shrinker.py: 100%
  • interrogate media_shrinker.py: 100%
  • Full suite: no new failures (only the 5 pre-existing macOS os.listxattr errors remain)

🤖 Generated with Claude Code

When ffmpeg or ffprobe is not installed or not on PATH, probe_media and
detect_silence_intervals let subprocess.run raise a bare FileNotFoundError
("No such file or directory: 'ffprobe'"), dumping a traceback that gives the
user no idea what went wrong. probe_media runs first in the pipeline, so this
raw error is what users actually hit — before the already-guarded _execute_plan.

Introduce a shared _run_media_tool() helper that maps a missing binary to a
MediaShrinkerError naming the tool and how to install it (brew/apt), and route
all three ffmpeg/ffprobe invocation sites through it. This also unifies and
improves _execute_plan's previously terse "ffmpeg not found: <path>" message.

Nonzero-exit / stderr handling stays at each call site; only the
tool-invocation FileNotFoundError path changes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJRVbDrp1vGYkJgNHMGPpG
@seonghobae seonghobae enabled auto-merge (squash) July 6, 2026 14:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant