Skip to content

Fix stdin/stdout handling, stop FFmpeg gracefully and add new options (v7.0.0) - #41

Merged
CrypticSignal merged 4 commits into
mainfrom
claude/affectionate-turing-w7ztbv
Nov 8, 2026
Merged

CrypticSignal merged 4 commits into
mainfrom
claude/affectionate-turing-w7ztbv

Conversation

@CrypticSignal

Copy link
Copy Markdown
Owner

Summary

This PR fixes two bugs, makes Ctrl+C stop FFmpeg gracefully, adds a few options and tightens CI. It bumps the version to 7.0.0 because some changes are breaking (listed below).

Bug fixes

  • FFmpeg was reading the Python program's standard input. FFmpeg inherited stdin and read it for keyboard commands. Data piped into a script that used this package was consumed by FFmpeg, and FFmpeg also changed the terminal's settings. FFmpeg now gets its own stdin pipe, unless its input is standard input (-i - / pipe:).
  • Writing the output to stdout didn't work. Progress was read from -progress pipe:1, so output such as -f mpegts - got mixed with the progress lines. On Linux and macOS, progress is now read from a separate pipe (os.pipe() + pass_fds, -progress pipe:<fd>), and the progress bar is shown on stderr in that case. On Windows this raises FfmpegCommandError, because Windows can't pass extra file descriptors.

Graceful Ctrl+C

FFmpeg now gets q on its stdin, which makes it finish writing the output file before it exits. If it hasn't exited within 5 seconds, the old behaviour takes over: SIGTERM then SIGKILL on POSIX, terminate() on Windows. This means an interrupted MP4 is still playable, on Windows too.

Robustness

  • FFprobe is looked for next to the FFmpeg executable (e.g. /opt/ffmpeg/bin/ffprobe) before PATH.
  • FFprobe now has a 30-second timeout, so an unresponsive URL no longer hangs the program.
  • The constructor only validates the command. FFprobe and the overwrite prompt now run in run().

API

  • New parameters: quiet, progress_callback(secs, duration_or_None, size_mb) and delete_log_on_success. delete_log_on_success only deletes regular files, so os.devnull is never deleted.
  • If progress_callback raises an exception, FFmpeg is stopped and the exception is passed on to the caller.
  • FfmpegProcessError now has returncode and log_file attributes.
  • Warnings are logged with the better_ffmpeg_progress logger instead of printed.
  • tqdm is now optional (better-ffmpeg-progress[tqdm]). Rich and tqdm are imported only when they're used.

Tooling

  • Python 3.11 or newer is now required, since 3.9 and 3.10 are end-of-life. CI tests 3.11 to 3.14, and pyproject.toml lists those versions in its classifiers.
  • CI now runs strict mypy and the ruff I, UP and B rules. The 9 mypy errors found earlier are fixed. A dev extra installs the lint and type-check tools.

Breaking changes

  • Python 3.11 or newer is required.
  • use_tqdm=True needs the [tqdm] extra. Without it, FfmpegCommandError is raised.
  • The existing-output checks (overwrite=False, -n) and the overwrite prompt now raise or run in run(), not in the constructor.
  • Warnings now go to the better_ffmpeg_progress logger (shown on stderr by default) instead of print().

Testing

  • 69 tests pass locally (48 before this PR), with ruff, ruff format and strict mypy clean in a fresh virtualenv.
  • New tests cover:
    • stdin is left alone (run in a subprocess with piped input)
    • output to stdout (checks the Matroska header on fd 1 and the progress bar on stderr)
    • the progress callback, including when the callback raises an exception
    • quiet
    • the error attributes
    • delete_log_on_success
    • tqdm not installed
    • finding FFprobe next to FFmpeg
    • the FFprobe timeout
    • classifying outputs as stdout or not
  • The stdin and stdout tests fail on main and pass with this PR.
  • Manual check: interrupting an MP4 encode after 2 seconds left a valid 2.56-second file.
  • Not tested here: Windows. The Windows code paths, such as sending q to FFmpeg and rejecting stdout output, have only been reviewed.

Generated by Claude Code

… (v7.0.0)

Fixes:
- FFmpeg no longer reads the Python program's standard input. It gets its
  own stdin pipe unless its input is standard input.
- Ctrl+C sends "q" to FFmpeg so it finishes writing the output file, and
  falls back to SIGTERM/SIGKILL (or terminate() on Windows) after 5 seconds.
- On POSIX, progress is read from a separate pipe, so the output can be
  written to standard output (e.g. "-f mpegts -"). The progress bar then
  goes to stderr. Writing to stdout raises FfmpegCommandError on Windows.

Robustness:
- FFprobe is looked for next to the FFmpeg executable before PATH, and is
  given 30 seconds to finish.
- The constructor only validates. FFprobe and the overwrite prompt run in
  run().

API:
- New quiet, progress_callback and delete_log_on_success parameters.
- FfmpegProcessError has returncode and log_file attributes.
- Warnings are logged with the better_ffmpeg_progress logger.
- tqdm is now an optional extra: better-ffmpeg-progress[tqdm].

Tooling:
- Require Python 3.11+, test 3.11-3.14 and add version classifiers.
- Add strict mypy and the ruff I, UP and B rules to CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaLfZ47UiCjK2T6R76WJCq
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaLfZ47UiCjK2T6R76WJCq
On Windows, redirected standard output usually uses cp1252, so printing
the check mark crashed after FFmpeg succeeded. Fall back to "OK".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaLfZ47UiCjK2T6R76WJCq
Text-mode stderr translates newlines to CRLF on Windows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XaLfZ47UiCjK2T6R76WJCq
@CrypticSignal
CrypticSignal merged commit 1840951 into main Nov 8, 2026
9 checks passed
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.

2 participants