feat: improved warning messages for dynamic reversion, fixes #314

Author: slhck

src/ffmpeg_normalize/_media_file.py

@@ -880,17 +880,50 @@ def _second_pass(self) -> Iterator[float]:
                     "This can happen when normalization is skipped (e.g., with --lower-only)."
                 )
 
-        # warn if self.media_file.ffmpeg_normalize.dynamic == False and any of the second pass stats contain "normalization_type" == "dynamic"
+        # warn if dynamic == False and any of the second pass stats contain "normalization_type" == "dynamic"
         if self.ffmpeg_normalize.dynamic is False:
             for audio_stream in self.streams["audio"].values():
                 pass2_stats = audio_stream.get_stats()["ebu_pass2"]
                 if pass2_stats is None:
                     continue
                 if pass2_stats["normalization_type"] == "dynamic":
+                    pass1_stats = audio_stream.get_stats()["ebu_pass1"]
+
+                    reason = ""
+                    if pass1_stats is not None:
+                        linear_gain = (
+                            self.ffmpeg_normalize.target_level - pass1_stats["input_i"]
+                        )
+                        estimated_tp = pass1_stats["input_tp"] + linear_gain
+                        if estimated_tp > self.ffmpeg_normalize.true_peak:
+                            min_tp = estimated_tp
+                            max_target = (
+                                self.ffmpeg_normalize.true_peak
+                                - pass1_stats["input_tp"]
+                                + pass1_stats["input_i"]
+                            )
+                            reason = (
+                                f" Reason: the input true peak ({pass1_stats['input_tp']:.2f} dBTP) is too high — "
+                                f"after linear gain of {linear_gain:.2f} dB, "
+                                f"the estimated true peak would be {estimated_tp:.2f} dBTP, "
+                                f"exceeding the target of {self.ffmpeg_normalize.true_peak} dBTP. "
+                                f"To avoid this, raise --true-peak (-tp) to at least {min_tp:.1f}, "
+                                f"or lower the target level (-t) to at most {max_target:.1f}."
+                            )
+                        elif (
+                            pass1_stats["input_lra"]
+                            > self.ffmpeg_normalize.loudness_range_target
+                        ):
+                            reason = (
+                                f" Reason: the input loudness range ({pass1_stats['input_lra']:.2f} LU) "
+                                f"exceeds the target ({self.ffmpeg_normalize.loudness_range_target:.2f} LU). "
+                                "Consider raising the target loudness range or using "
+                                "--keep-loudness-range-target / --keep-lra-above-loudness-range-target."
+                            )
+
                     _logger.warning(
-                        f"{self.input_file}: You specified linear normalization, but the loudnorm filter reverted to dynamic normalization. "
-                        "This may lead to unexpected results. "
-                        "Consider your input settings, e.g. choose a lower target level or higher target loudness range."
+                        f"{self.input_file}: You specified linear normalization, but the loudnorm filter "
+                        f"reverted to dynamic normalization.{reason}"
                     )
 
         _logger.debug("Normalization finished")

src/ffmpeg_normalize/_streams.py

@@ -557,6 +557,30 @@ def get_second_pass_opts_ebu(self, batch_reference: float | None = None) -> str:
 
         stats = self.loudness_statistics["ebu_pass1"]
 
+        # Check if the true peak constraint will force dynamic mode.
+        # In linear mode, a uniform gain of (target - input_i) is applied.
+        # If that would leave the true peak above the TP limit, loudnorm
+        # cannot satisfy both constraints linearly and will fall back to
+        # dynamic processing.
+        if not will_use_dynamic_mode:
+            linear_gain = target_level - stats["input_i"]
+            estimated_tp = stats["input_tp"] + linear_gain
+            if estimated_tp > self.media_file.ffmpeg_normalize.true_peak:
+                min_tp = estimated_tp
+                max_target = (
+                    self.media_file.ffmpeg_normalize.true_peak
+                    - stats["input_tp"]
+                    + stats["input_i"]
+                )
+                _logger.warning(
+                    f"{self.media_file.input_file}: Linear normalization would result in an estimated true peak of "
+                    f"{estimated_tp:.2f} dBTP (input true peak {stats['input_tp']:.2f} dBTP + gain of {linear_gain:.2f} dB), "
+                    f"which exceeds the target true peak of {self.media_file.ffmpeg_normalize.true_peak} dBTP. "
+                    "The loudnorm filter will likely use dynamic mode instead. "
+                    f"To avoid this, raise --true-peak (-tp) to at least {min_tp:.1f}, "
+                    f"or lower the target level (-t) to at most {max_target:.1f}."
+                )
+
         # Adjust target level for batch mode to preserve relative loudness
         if batch_reference is not None:
             input_i = float(stats["input_i"])