fix(exporters): stop crying wolf when mutagen lacks a writable chapter API

Resolves #195.

_apply_m4b_chapters_mutagen() caught ImportError and always logged
"mutagen is not installed". That is misleading: mutagen IS installed
(>=1.47 is a hard requirement), but current releases expose no writable
MP4 chapter API - MP4Chapter (singular) does not exist, so the import
can never succeed. The scary warning implied the output was unchaptered,
when in fact ffmpeg has already written the chpl/chap chapter atoms
(and a timed-text chapter track) earlier in embed_m4b_metadata.

Distinguish the two failure modes:
- mutagen genuinely missing -> keep the warning (unchanged).
- mutagen present but no writable chapter API (the expected case) ->
  demote to a debug log with an accurate explanation that the chapters
  are already in place via ffmpeg.

No behavioral change to the output: the method still returns False in
both cases; only the log level/message of the expected path changes.
This commit is contained in:
Hari Krishna Gaddipati committed 2026-10-11 10:01:16 -05:00
1 parent 08e2ee8b85
commit 3fe3ac7501
1 file changed
+25 -2
+25 -2
View File
@@ -226,8 +226,31 @@ class ExportService:
from fractions import Fraction
from mutagen.mp4 import MP4, MP4Chapter
except ImportError:
if log_callback:
log_callback("Unable to write MP4 chapter atoms because mutagen is not installed.", "warning")
# Distinguish a genuinely missing mutagen from a present mutagen
# that simply lacks a writable MP4 chapter API. The latter is the
# expected case: current mutagen releases (>=1.47) only expose a
# read-only Chapter/MP4Chapters API and have no MP4Chapter symbol,
# so this import can never succeed. That is not a real error -
# ffmpeg has already written the chpl/chap chapter atoms (and a
# timed-text chapter track) earlier in embed_m4b_metadata, so the
# output is fully chaptered either way.
try:
import mutagen # noqa: F401
except ImportError:
if log_callback:
log_callback(
"Unable to write MP4 chapter atoms because mutagen is not installed.",
"warning",
)
else:
if log_callback:
log_callback(
"Skipping the mutagen chapter pass: installed mutagen "
f"({getattr(mutagen, 'version_string', 'unknown')}) exposes no "
"writable MP4 chapter API. Chapters were already written by "
"ffmpeg, so the output is fully chaptered.",
"debug",
)
return False
try: