fix(audio_sink): fail fast when the merged-output ffmpeg encode fails

open_audio_sink() ran the merged-output ffmpeg with stderr=DEVNULL and never
checked the return code, so a failed encode silently produced a truncated file
(no moov atom) that then broke the metadata-embed step with a misleading
'exit 254'. This was observed live on a real PDF->M4B job.

Now:
- ffmpeg stderr is written to <out>.ffmpeg.log (diagnosable after the fact).
- a non-zero exit raises RuntimeError with the stderr tail and removes the
  truncated output, instead of silently closing.

Regression tests:
- a non-zero ffmpeg exit raises (not silently closes).
- ffmpeg stderr is redirected to a real file handle (not DEVNULL).

Verified: 19/19 tests in tests/test_domain_audio_sink.py pass (Python 3.11).
Also verified end-to-end on the build host: the instrumentation is what surfaced
the real embed-step ffmpeg output (all chapters mapped, moov moved) confirming a
full, chaptered 72.9 MB M4B.

Closes the diagnostic gap from homelab issue #110.
This commit is contained in:
Hari Krishna Gaddipati committed 2026-10-11 18:25:52 -05:00
1 parent 315840309f
commit 2ea1941838
2 files changed
+78 -2

No files matched your search

+26 -2
View File
@@ -114,8 +114,14 @@ def open_audio_sink(
if extra_ffmpeg_args:
cmd[2:2] = extra_ffmpeg_args
# Capture ffmpeg's stderr (previously DEVNULL) so a failed encode is
# diagnosable instead of silently producing a truncated file. The log path
# lives next to the output so it can be inspected after the fact.
stderr_path = path.with_suffix(path.suffix + ".ffmpeg.log")
stderr_file = open(stderr_path, "wb")
process = subprocess.Popen(
cmd, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
cmd, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=stderr_file
)
def _write_compressed(data: np.ndarray) -> None:
@@ -126,6 +132,24 @@ def open_audio_sink(
def _close_compressed() -> None:
if process.stdin and not process.stdin.closed:
process.stdin.close()
process.wait()
returncode = process.wait()
stderr_file.close()
if returncode != 0:
# Surface the real ffmpeg failure instead of letting a truncated
# file cascade into the metadata-embed step with a misleading error.
tail = ""
try:
with open(stderr_path, "r", errors="replace") as fh:
tail = "".join(fh.readlines()[-25:])
except OSError:
pass
try:
path.unlink(missing_ok=True)
except OSError:
pass
raise RuntimeError(
f"audio-sink ffmpeg failed (exit {returncode}) for {path}. "
f"stderr tail:\n{tail}"
)
return AudioSink(write=_write_compressed, close=_close_compressed)
+52
View File
@@ -187,3 +187,55 @@ class TestOpenAudioSinkCompressed:
meta = {"title": "Test", "artist": "Author"}
open_audio_sink(tmp_path / "meta.opus", "opus", metadata=meta)
mock_build.assert_called_once_with(tmp_path / "meta.opus", "opus", metadata=meta)
@patch("abogen.domain.audio_sink._ensure_ffmpeg")
@patch("abogen.domain.audio_sink.build_ffmpeg_command")
@patch("abogen.domain.audio_sink.subprocess.Popen")
def test_failed_ffmpeg_encode_raises_instead_of_silently_closing(
self, mock_popen, mock_build, mock_ensure, tmp_path: Path
):
"""A non-zero ffmpeg exit must raise, not silently close (which left a
truncated file that then broke the metadata-embed step downstream)."""
mock_build.return_value = ["ffmpeg", "-y", "-i", "pipe:0", "out.mp3"]
proc = MagicMock()
proc.stdin = MagicMock()
proc.stdin.closed = False
proc.wait.return_value = 1 # ffmpeg failed
mock_popen.return_value = proc
out = tmp_path / "fail.mp3"
sink = open_audio_sink(out, "mp3")
sink.write(np.zeros(100, dtype="float32"))
try:
sink.close()
raised = False
except RuntimeError as exc:
raised = True
assert "exit 1" in str(exc)
assert raised, "close() should raise when ffmpeg exits non-zero"
@patch("abogen.domain.audio_sink._ensure_ffmpeg")
@patch("abogen.domain.audio_sink.build_ffmpeg_command")
@patch("abogen.domain.audio_sink.subprocess.Popen")
def test_ffmpeg_stderr_captured_to_log_file(
self, mock_popen, mock_build, mock_ensure, tmp_path: Path
):
"""ffmpeg stderr is redirected to <out>.ffmpeg.log (no longer DEVNULL)
so a failed encode is diagnosable after the fact."""
mock_build.return_value = ["ffmpeg", "-y", "-i", "pipe:0", "out.mp3"]
proc = MagicMock()
proc.stdin = MagicMock()
proc.stdin.closed = False
proc.wait.return_value = 0
mock_popen.return_value = proc
out = tmp_path / "log.mp3"
sink = open_audio_sink(out, "mp3")
sink.write(np.zeros(100, dtype="float32"))
sink.close()
# Popen must have been given a real stderr file handle (not DEVNULL).
stderr_arg = mock_popen.call_args.kwargs.get("stderr")
assert stderr_arg is not None
assert stderr_arg is not subprocess.DEVNULL