ffmpeg-normalize 1.34.0__py3-none-any.whl → 1.36.0__py3-none-any.whl

ffmpeg_normalize/__main__.py

@@ -13,6 +13,7 @@ from typing import NoReturn
 from ._errors import FFmpegNormalizeError
 from ._ffmpeg_normalize import NORMALIZATION_TYPES, FFmpegNormalize
 from ._logger import setup_cli_logger
+from ._presets import PresetManager
 
 # Import version from package
 import importlib.metadata
@@ -50,7 +51,7 @@ def create_parser() -> argparse.ArgumentParser:
 
             Author: Werner Robitza
             License: MIT
-            Homepage / Issues: https://github.com/slhck/ffmpeg-normalize
+            Website / Issues: https://github.com/slhck/ffmpeg-normalize
             """
         ),
     )
@@ -90,7 +91,7 @@ def create_parser() -> argparse.ArgumentParser:
             name specified.
         """
         ),
-        default="normalized",
+        default=FFmpegNormalize.DEFAULTS["output_folder"],
     )
 
     group_general = parser.add_argument_group("General Options")
@@ -124,6 +125,28 @@ def create_parser() -> argparse.ArgumentParser:
         version=f"%(prog)s v{__version__}",
         help="Print version and exit",
     )
+    group_general.add_argument(
+        "--preset",
+        type=str,
+        help=textwrap.dedent(
+            """\
+        Load options from a preset file.
+
+        Preset files are JSON files located in the presets directory.
+        The directory location depends on your OS:
+        - Linux/macOS: ~/.config/ffmpeg-normalize/presets/
+        - Windows: %%APPDATA%%/ffmpeg-normalize/presets/
+
+        Use --list-presets to see available presets.
+        CLI options specified on the command line take precedence over preset values.
+        """
+        ),
+    )
+    group_general.add_argument(
+        "--list-presets",
+        action="store_true",
+        help="List all available presets and exit",
+    )
 
     group_normalization = parser.add_argument_group("Normalization")
     group_normalization.add_argument(
@@ -144,15 +167,15 @@ def create_parser() -> argparse.ArgumentParser:
         Peak normalization brings the signal to the specified peak level.
         """
         ),
-        default="ebu",
+        default=FFmpegNormalize.DEFAULTS["normalization_type"],
     )
     group_normalization.add_argument(
         "-t",
         "--target-level",
         type=float,
         help=textwrap.dedent(
-            """\
-        Normalization target level in dB/LUFS (default: -23).
+            f"""\
+        Normalization target level in dB/LUFS (default: {FFmpegNormalize.DEFAULTS["target_level"]}).
 
         For EBU normalization, it corresponds to Integrated Loudness Target
         in LUFS. The range is -70.0 - -5.0.
@@ -160,7 +183,7 @@ def create_parser() -> argparse.ArgumentParser:
         Otherwise, the range is -99 to 0.
         """
         ),
-        default=-23.0,
+        default=FFmpegNormalize.DEFAULTS["target_level"],
     )
     group_normalization.add_argument(
         "-p",
@@ -179,6 +202,24 @@ def create_parser() -> argparse.ArgumentParser:
         """
         ),
     )
+    group_normalization.add_argument(
+        "--batch",
+        action="store_true",
+        help=textwrap.dedent(
+            """\
+        Preserve relative loudness between files (album mode).
+
+        When operating on a group of unrelated files, you usually want all of them at the same
+        level. However, a group of music files all from the same album is generally meant to be
+        listened to at the relative volumes they were recorded at. In batch mode, all the specified
+        files are considered to be part of a single album and their relative volumes are preserved.
+        This is done by averaging the loudness of all the files, computing a single adjustment from
+        that, and applying a relative adjustment to all the files.
+
+        Batch mode works with all normalization types (EBU, RMS, peak).
+        """
+        ),
+    )
 
     # group_normalization.add_argument(
     #     '--threshold',
@@ -197,12 +238,12 @@ def create_parser() -> argparse.ArgumentParser:
         "--loudness-range-target",
         type=float,
         help=textwrap.dedent(
-            """\
-        EBU Loudness Range Target in LUFS (default: 7.0).
+            f"""\
+        EBU Loudness Range Target in LUFS (default: {FFmpegNormalize.DEFAULTS["loudness_range_target"]}).
         Range is 1.0 - 50.0.
         """
         ),
-        default=7.0,
+        default=FFmpegNormalize.DEFAULTS["loudness_range_target"],
     )
 
     group_ebu.add_argument(
@@ -231,26 +272,26 @@ def create_parser() -> argparse.ArgumentParser:
         "--true-peak",
         type=float,
         help=textwrap.dedent(
-            """\
-        EBU Maximum True Peak in dBTP (default: -2.0).
+            f"""\
+        EBU Maximum True Peak in dBTP (default: {FFmpegNormalize.DEFAULTS["true_peak"]}).
         Range is -9.0 - +0.0.
         """
         ),
-        default=-2.0,
+        default=FFmpegNormalize.DEFAULTS["true_peak"],
     )
 
     group_ebu.add_argument(
         "--offset",
         type=float,
         help=textwrap.dedent(
-            """\
-        EBU Offset Gain (default: 0.0).
+            f"""\
+        EBU Offset Gain (default: {FFmpegNormalize.DEFAULTS["offset"]}).
         The gain is applied before the true-peak limiter in the first pass only.
         The offset for the second pass will be automatically determined based on the first pass statistics.
         Range is -99.0 - +99.0.
         """
         ),
-        default=0.0,
+        default=FFmpegNormalize.DEFAULTS["offset"],
     )
 
     group_ebu.add_argument(
@@ -453,7 +494,7 @@ def create_parser() -> argparse.ArgumentParser:
         Will attempt to copy video codec by default.
         """
         ),
-        default="copy",
+        default=FFmpegNormalize.DEFAULTS["video_codec"],
     )
     group_vcodec.add_argument(
         "-sn",
@@ -547,7 +588,7 @@ def create_parser() -> argparse.ArgumentParser:
         specified. (Default: `mkv`)
         """
         ),
-        default="mkv",
+        default=FFmpegNormalize.DEFAULTS["extension"],
     )
     return parser
 
@@ -563,6 +604,28 @@ def main() -> None:
             _logger.error(message)
         sys.exit(1)
 
+    # Handle --list-presets
+    preset_manager = PresetManager()
+    if cli_args.list_presets:
+        presets = preset_manager.get_available_presets()
+        if presets:
+            print("Available presets:")
+            for preset in presets:
+                print(f"  - {preset}")
+        else:
+            print(f"No presets found in {preset_manager.presets_dir}")
+        sys.exit(0)
+
+    # Load and apply preset if specified
+    if cli_args.preset:
+        try:
+            preset_data = preset_manager.load_preset(cli_args.preset)
+            _logger.debug(f"Loaded preset '{cli_args.preset}': {preset_data}")
+            preset_manager.merge_preset_with_args(preset_data, cli_args)
+            _logger.info(f"Applied preset '{cli_args.preset}'")
+        except (FileNotFoundError, json.JSONDecodeError, ValueError) as e:
+            error(str(e))
+
     def _split_options(opts: str) -> list[str]:
         """
         Parse extra options (input or output) into a list.
@@ -636,6 +699,7 @@ def main() -> None:
         dry_run=cli_args.dry_run,
         progress=cli_args.progress,
         replaygain=cli_args.replaygain,
+        batch=cli_args.batch,
         audio_streams=audio_streams,
         audio_default_only=cli_args.audio_default_only,
         keep_other_audio=cli_args.keep_other_audio,

ffmpeg_normalize/_ffmpeg_normalize.py

@@ -84,6 +84,7 @@ class FFmpegNormalize:
         debug (bool, optional): Debug. Defaults to False.
         progress (bool, optional): Progress. Defaults to False.
         replaygain (bool, optional): Write ReplayGain tags without normalizing. Defaults to False.
+        batch (bool, optional): Preserve relative loudness between files (album mode). Defaults to False.
         audio_streams (list[int] | None, optional): List of audio stream indices to normalize. Defaults to None (all streams).
         audio_default_only (bool, optional): Only normalize audio streams with default disposition. Defaults to False.
         keep_other_audio (bool, optional): Keep non-selected audio streams in output (copy without normalization). Defaults to False.
@@ -92,6 +93,48 @@ class FFmpegNormalize:
         FFmpegNormalizeError: If the ffmpeg executable is not found or does not support the loudnorm filter.
     """
 
+    # Default parameter values - single source of truth for all defaults
+    # Note: output_folder is a CLI-level option and not passed to FFmpegNormalize.__init__
+    DEFAULTS = {
+        "normalization_type": "ebu",
+        "target_level": -23.0,
+        "print_stats": False,
+        "loudness_range_target": 7.0,
+        "keep_loudness_range_target": False,
+        "keep_lra_above_loudness_range_target": False,
+        "true_peak": -2.0,
+        "offset": 0.0,
+        "lower_only": False,
+        "auto_lower_loudness_target": False,
+        "dual_mono": False,
+        "dynamic": False,
+        "audio_codec": "pcm_s16le",
+        "audio_bitrate": None,
+        "sample_rate": None,
+        "audio_channels": None,
+        "keep_original_audio": False,
+        "pre_filter": None,
+        "post_filter": None,
+        "video_codec": "copy",
+        "video_disable": False,
+        "subtitle_disable": False,
+        "metadata_disable": False,
+        "chapters_disable": False,
+        "extra_input_options": None,
+        "extra_output_options": None,
+        "output_format": None,
+        "output_folder": "normalized",
+        "extension": "mkv",
+        "dry_run": False,
+        "debug": False,
+        "progress": False,
+        "replaygain": False,
+        "batch": False,
+        "audio_streams": None,
+        "audio_default_only": False,
+        "keep_other_audio": False,
+    }
+
     def __init__(
         self,
         normalization_type: Literal["ebu", "rms", "peak"] = "ebu",
@@ -127,6 +170,7 @@ class FFmpegNormalize:
         debug: bool = False,
         progress: bool = False,
         replaygain: bool = False,
+        batch: bool = False,
         audio_streams: list[int] | None = None,
         audio_default_only: bool = False,
         keep_other_audio: bool = False,
@@ -212,6 +256,7 @@ class FFmpegNormalize:
         self.debug = debug
         self.progress = progress
         self.replaygain = replaygain
+        self.batch = batch
 
         # Stream selection options
         self.audio_streams = audio_streams
@@ -272,29 +317,172 @@ class FFmpegNormalize:
         self.media_files.append(MediaFile(self, input_file, output_file))
         self.file_count += 1
 
+    def _calculate_batch_reference(self) -> float | None:
+        """
+        Calculate the batch reference loudness by averaging measurements across all files.
+
+        Returns:
+            float | None: The batch reference loudness value, or None if no measurements found.
+
+        Note:
+            TODO: Add option to specify different averaging methods (duration-weighted,
+            use quietest/loudest track, etc.)
+        """
+        measurements: list[float] = []
+
+        for media_file in self.media_files:
+            # Access audio streams from the streams dict
+            audio_streams = media_file.streams.get("audio", {})
+            for stream in audio_streams.values():
+                if self.normalization_type == "ebu":
+                    # Get EBU integrated loudness from first pass
+                    ebu_stats = stream.loudness_statistics.get("ebu_pass1")
+                    if ebu_stats and "input_i" in ebu_stats:
+                        measurements.append(float(ebu_stats["input_i"]))
+                elif self.normalization_type == "rms":
+                    # Get RMS mean value
+                    mean = stream.loudness_statistics.get("mean")
+                    if mean is not None:
+                        measurements.append(float(mean))
+                elif self.normalization_type == "peak":
+                    # Get peak max value
+                    max_val = stream.loudness_statistics.get("max")
+                    if max_val is not None:
+                        measurements.append(float(max_val))
+
+        if not measurements:
+            _logger.warning(
+                "No loudness measurements found for batch reference calculation. "
+                "Batch mode will not be applied."
+            )
+            return None
+
+        # Simple average of all measurements
+        batch_reference = sum(measurements) / len(measurements)
+        _logger.debug(f"Batch mode: Measurements for batch reference: {measurements}")
+        _logger.info(
+            f"Batch mode: Calculated reference loudness = {batch_reference:.2f} "
+            f"({self.normalization_type.upper()}, averaged from {len(measurements)} stream(s))"
+        )
+
+        return batch_reference
+
     def run_normalization(self) -> None:
         """
-        Run the normalization procedures
+        Run the normalization procedures.
+
+        In batch mode, all files are analyzed first (first pass), then a batch reference
+        loudness is calculated, and finally all files are normalized (second pass) with
+        adjustments relative to the batch reference to preserve relative loudness.
+
+        In non-batch mode, each file is processed completely (both passes) before
+        moving to the next file.
         """
-        for index, media_file in enumerate(
-            tqdm(self.media_files, desc="File", disable=not self.progress, position=0)
-        ):
+        if self.batch:
+            # Batch mode: analyze all files first, then normalize with relative adjustments
             _logger.info(
-                f"Normalizing file {media_file} ({index + 1} of {self.file_count})"
+                f"Batch mode enabled: processing {self.file_count} file(s) while preserving relative loudness"
             )
 
-            try:
-                media_file.run_normalization()
-            except Exception as e:
-                if len(self.media_files) > 1:
-                    # simply warn and do not die
-                    _logger.error(
-                        f"Error processing input file {media_file}, will "
-                        f"continue batch-processing. Error was: {e}"
-                    )
-                else:
-                    # raise the error so the program will exit
-                    raise e
+            # Recommend RMS/Peak for album normalization instead of EBU
+            if self.normalization_type == "ebu":
+                _logger.warning(
+                    "Using EBU R128 normalization with --batch. For true album normalization where "
+                    "all tracks are shifted by the same amount, consider using --normalization-type rms "
+                    "or --normalization-type peak instead. EBU normalization applies different processing "
+                    "to each track based on its loudness characteristics, which may alter relative levels "
+                    "slightly due to psychoacoustic adjustments."
+                )
+
+            # Warn if using dynamic EBU mode with batch
+            if self.dynamic and self.normalization_type == "ebu":
+                _logger.warning(
+                    "ffmpeg uses dynamic EBU normalization. This may change relative "
+                    "loudness within a file. Use linear mode for true album normalization, or "
+                    "switch to --normalization-type peak or --normalization-type rms instead. "
+                    "To force linear mode, use --keep-lra-above-loudness-range-target or "
+                    "--keep-loudness-range-target."
+                )
+
+            # Phase 1: Run first pass on all files to collect measurements
+            _logger.info("Phase 1: Analyzing all files...")
+            for index, media_file in enumerate(
+                tqdm(
+                    self.media_files,
+                    desc="Analysis",
+                    disable=not self.progress,
+                    position=0,
+                )
+            ):
+                _logger.info(
+                    f"Analyzing file {media_file} ({index + 1} of {self.file_count})"
+                )
+
+                try:
+                    # Only run first pass if not in dynamic EBU mode
+                    if not (self.dynamic and self.normalization_type == "ebu"):
+                        media_file._first_pass()
+                    else:
+                        _logger.debug(
+                            "Dynamic EBU mode: First pass skipped for this file."
+                        )
+                except Exception as e:
+                    if len(self.media_files) > 1:
+                        _logger.error(
+                            f"Error analyzing input file {media_file}, will "
+                            f"continue batch-processing. Error was: {e}"
+                        )
+                    else:
+                        raise e
+
+            # Phase 2: Calculate batch reference loudness
+            batch_reference = self._calculate_batch_reference()
+
+            # Phase 3: Run second pass on all files with batch reference
+            _logger.info("Phase 2: Normalizing all files...")
+            for index, media_file in enumerate(
+                tqdm(
+                    self.media_files,
+                    desc="Normalization",
+                    disable=not self.progress,
+                    position=0,
+                )
+            ):
+                _logger.info(
+                    f"Normalizing file {media_file} ({index + 1} of {self.file_count})"
+                )
+
+                try:
+                    media_file.run_normalization(batch_reference=batch_reference)
+                except Exception as e:
+                    if len(self.media_files) > 1:
+                        _logger.error(
+                            f"Error processing input file {media_file}, will "
+                            f"continue batch-processing. Error was: {e}"
+                        )
+                    else:
+                        raise e
+        else:
+            # Non-batch mode: process each file completely before moving to the next
+            for index, media_file in enumerate(
+                tqdm(
+                    self.media_files, desc="File", disable=not self.progress, position=0
+                )
+            ):
+                _logger.info(
+                    f"Normalizing file {media_file} ({index + 1} of {self.file_count})"
+                )
+
+                try:
+                    media_file.run_normalization()
+                except Exception as e:
+                    if len(self.media_files) > 1:
+                        _logger.error(
+                            f"Error processing input file {media_file}, will "
+                            f"continue batch-processing. Error was: {e}"
+                        )
+                    else:
+                        raise e
 
         if self.print_stats:
             json.dump(

ffmpeg_normalize/_media_file.py

@@ -86,6 +86,7 @@ class MediaFile:
             self.output_ext = current_ext
         self.streams: StreamDict = {"audio": {}, "video": {}, "subtitle": {}}
         self.temp_file: Union[str, None] = None
+        self.batch_reference: float | None = None
 
         self.parse_streams()
 
@@ -265,21 +266,35 @@ class MediaFile:
             # Normalize all streams (default behavior)
             return all_audio_streams
 
-    def run_normalization(self) -> None:
+    def run_normalization(self, batch_reference: float | None = None) -> None:
         """
         Run the normalization process for this file.
+
+        Args:
+            batch_reference (float | None, optional): Reference loudness for batch mode.
+                If provided, the first pass is skipped (assumed already done) and this
+                reference is used to calculate relative adjustments. Defaults to None.
         """
         _logger.debug(f"Running normalization for {self.input_file}")
 
-        # run the first pass to get loudness stats, unless in dynamic EBU mode
-        if not (
-            self.ffmpeg_normalize.dynamic
-            and self.ffmpeg_normalize.normalization_type == "ebu"
-        ):
-            self._first_pass()
+        # Store batch reference for use in second pass
+        self.batch_reference = batch_reference
+
+        # run the first pass to get loudness stats, unless in dynamic EBU mode or batch mode
+        # (in batch mode, first pass is already done in FFmpegNormalize.run_normalization)
+        if batch_reference is None:
+            if not (
+                self.ffmpeg_normalize.dynamic
+                and self.ffmpeg_normalize.normalization_type == "ebu"
+            ):
+                self._first_pass()
+            else:
+                _logger.debug(
+                    "Dynamic EBU mode: First pass will not run, as it is not needed."
+                )
         else:
             _logger.debug(
-                "Dynamic EBU mode: First pass will not run, as it is not needed."
+                f"Batch mode: Skipping first pass (already completed), using batch reference = {batch_reference:.2f}"
             )
 
         # for second pass, create a temp file
@@ -529,9 +544,13 @@ class MediaFile:
                 normalization_filter = "acopy"
             else:
                 if self.ffmpeg_normalize.normalization_type == "ebu":
-                    normalization_filter = audio_stream.get_second_pass_opts_ebu()
+                    normalization_filter = audio_stream.get_second_pass_opts_ebu(
+                        batch_reference=self.batch_reference
+                    )
                 else:
-                    normalization_filter = audio_stream.get_second_pass_opts_peakrms()
+                    normalization_filter = audio_stream.get_second_pass_opts_peakrms(
+                        batch_reference=self.batch_reference
+                    )
 
             input_label = f"[0:{audio_stream.stream_id}]"
             output_label = f"[norm{audio_stream.stream_id}]"

ffmpeg_normalize/_presets.py

@@ -0,0 +1,256 @@
+"""Preset management for ffmpeg-normalize."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+from ._ffmpeg_normalize import FFmpegNormalize
+
+_logger = logging.getLogger(__name__)
+
+
+def get_config_dir() -> Path:
+    """Get the platform-specific config directory for ffmpeg-normalize.
+
+    Returns:
+        Path: Configuration directory for presets
+
+    On Linux/macOS:
+        - XDG_CONFIG_HOME/ffmpeg-normalize (if XDG_CONFIG_HOME is set)
+        - ~/.config/ffmpeg-normalize (otherwise)
+
+    On Windows:
+        - %APPDATA%/ffmpeg-normalize
+    """
+    if os.name == "nt":  # Windows
+        appdata = os.getenv("APPDATA")
+        if appdata:
+            config_dir = Path(appdata) / "ffmpeg-normalize"
+        else:
+            config_dir = Path.home() / "AppData" / "Roaming" / "ffmpeg-normalize"
+    else:  # Linux/macOS
+        xdg_config = os.getenv("XDG_CONFIG_HOME")
+        if xdg_config:
+            config_dir = Path(xdg_config) / "ffmpeg-normalize"
+        else:
+            config_dir = Path.home() / ".config" / "ffmpeg-normalize"
+
+    return config_dir
+
+
+def get_presets_dir() -> Path:
+    """Get the presets directory.
+
+    Returns:
+        Path: Directory containing preset files
+    """
+    return get_config_dir() / "presets"
+
+
+def get_default_presets_dir() -> Path:
+    """Get the package default presets directory.
+
+    Returns:
+        Path: Directory containing default preset files bundled with the package
+    """
+    # Get the directory where this module is located
+    module_dir = Path(__file__).parent
+    return module_dir / "data" / "presets"
+
+
+class PresetManager:
+    """Manages loading and merging of presets with CLI arguments."""
+
+    def __init__(self) -> None:
+        """Initialize the preset manager."""
+        self.presets_dir = get_presets_dir()
+        self.default_presets_dir = get_default_presets_dir()
+
+    def get_available_presets(self) -> list[str]:
+        """Get list of available preset names.
+
+        Includes both user-installed presets and default presets from the package.
+        User presets take precedence if they have the same name.
+
+        Returns:
+            list[str]: List of available preset names (without .json extension)
+        """
+        presets = set()
+
+        # Get presets from user config directory
+        if self.presets_dir.exists():
+            for file in self.presets_dir.glob("*.json"):
+                presets.add(file.stem)
+
+        # Get default presets from package
+        if self.default_presets_dir.exists():
+            for file in self.default_presets_dir.glob("*.json"):
+                presets.add(file.stem)
+
+        return sorted(presets)
+
+    def load_preset(self, preset_name: str) -> dict[str, Any]:
+        """Load a preset file by name.
+
+        Checks user config directory first, then falls back to package defaults.
+
+        Args:
+            preset_name: Name of the preset (without .json extension)
+
+        Returns:
+            dict[str, Any]: Preset configuration as a dictionary
+
+        Raises:
+            FileNotFoundError: If preset file doesn't exist
+            json.JSONDecodeError: If preset file is invalid JSON
+        """
+        # Try user config directory first
+        preset_path = self.presets_dir / f"{preset_name}.json"
+
+        # Fall back to package default presets
+        if not preset_path.exists():
+            preset_path = self.default_presets_dir / f"{preset_name}.json"
+
+        if not preset_path.exists():
+            raise FileNotFoundError(
+                f"Preset '{preset_name}' not found. "
+                f"Available presets: {', '.join(self.get_available_presets()) or 'none'}"
+            )
+
+        try:
+            with open(preset_path, "r") as f:
+                preset_data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise json.JSONDecodeError(
+                f"Invalid JSON in preset '{preset_name}': {e.msg}",
+                e.doc,
+                e.pos,
+            )
+
+        if not isinstance(preset_data, dict):
+            raise ValueError(
+                f"Preset must be a JSON object, got {type(preset_data).__name__}"
+            )
+
+        return preset_data
+
+    def merge_preset_with_args(
+        self, preset_data: dict[str, Any], cli_args: Any
+    ) -> None:
+        """Merge preset data with CLI arguments, giving precedence to CLI args.
+
+        Args:
+            preset_data: Dictionary of preset configuration
+            cli_args: Parsed CLI arguments (argparse Namespace object)
+
+        The CLI arguments take precedence over preset values. This function modifies
+        cli_args in place by setting attributes that were not explicitly provided
+        on the command line.
+        """
+        for key, value in preset_data.items():
+            # Convert hyphens to underscores to match argparse attribute names
+            attr_name = key.replace("-", "_")
+
+            # Check if this attribute exists in cli_args
+            if not hasattr(cli_args, attr_name):
+                _logger.warning(
+                    f"Preset option '{key}' is not a valid ffmpeg-normalize option. Skipping."
+                )
+                continue
+
+            # Get the current value
+            current_value = getattr(cli_args, attr_name)
+
+            # Check if this was explicitly set by the user
+            # For most types, we can infer this by checking against the defaults:
+            # - None values were not explicitly set
+            # - Empty lists were not explicitly set
+            # - False boolean flags were not explicitly set
+            # - Default numeric values (specific to each option) need special handling
+
+            should_apply = False
+
+            if isinstance(value, bool):
+                # For boolean flags, apply preset only if currently False (not set)
+                should_apply = not current_value
+            elif isinstance(current_value, list):
+                # For lists (like output), apply preset only if empty
+                should_apply = not current_value
+            elif current_value is None:
+                # For None values, always apply preset (not explicitly set)
+                should_apply = True
+            else:
+                # For other values (numbers, strings), check if they match known defaults
+                # This is conservative: only override if the value is a known default
+                if (
+                    attr_name in FFmpegNormalize.DEFAULTS
+                    and current_value == FFmpegNormalize.DEFAULTS[attr_name]
+                ):
+                    should_apply = True
+
+            if should_apply:
+                setattr(cli_args, attr_name, value)
+                _logger.debug(f"Applied preset option '{key}' = {value}")
+
+    def validate_preset(self, preset_name: str) -> tuple[bool, str]:
+        """Validate that a preset file exists and is valid.
+
+        Args:
+            preset_name: Name of the preset to validate
+
+        Returns:
+            tuple[bool, str]: (is_valid, message)
+        """
+        try:
+            self.load_preset(preset_name)
+            return True, f"Preset '{preset_name}' is valid"
+        except FileNotFoundError as e:
+            return False, str(e)
+        except (json.JSONDecodeError, ValueError) as e:
+            return False, f"Error loading preset '{preset_name}': {e}"
+
+    def install_default_presets(self, force: bool = False) -> tuple[bool, str]:
+        """Install default presets to user config directory.
+
+        Args:
+            force: If True, overwrite existing presets
+
+        Returns:
+            tuple[bool, str]: (success, message)
+        """
+        try:
+            # Create presets directory if it doesn't exist
+            self.presets_dir.mkdir(parents=True, exist_ok=True)
+
+            if not self.default_presets_dir.exists():
+                return (
+                    False,
+                    f"Default presets directory not found at {self.default_presets_dir}",
+                )
+
+            # Copy all default presets
+            installed = []
+            skipped = []
+
+            for preset_file in self.default_presets_dir.glob("*.json"):
+                dest_file = self.presets_dir / preset_file.name
+
+                if dest_file.exists() and not force:
+                    skipped.append(preset_file.name)
+                else:
+                    shutil.copy2(preset_file, dest_file)
+                    installed.append(preset_file.name)
+
+            message = f"Installed {len(installed)} preset(s) to {self.presets_dir}"
+            if skipped:
+                message += f" ({len(skipped)} skipped, use --force to overwrite)"
+
+            return True, message
+
+        except Exception as e:
+            return False, f"Error installing default presets: {e}"

ffmpeg_normalize/_streams.py

@@ -444,9 +444,14 @@ class AudioStream(MediaStream):
                         )
         return result
 
-    def get_second_pass_opts_ebu(self) -> str:
+    def get_second_pass_opts_ebu(self, batch_reference: float | None = None) -> str:
         """
         Return second pass loudnorm filter options string for ffmpeg
+
+        Args:
+            batch_reference (float | None, optional): Reference loudness for batch mode.
+                When provided, the target level is adjusted to preserve relative loudness.
+                Defaults to None.
         """
 
         # In dynamic mode, we can do everything in one pass, and we do not have first pass stats
@@ -552,6 +557,19 @@ class AudioStream(MediaStream):
 
         stats = self.loudness_statistics["ebu_pass1"]
 
+        # Adjust target level for batch mode to preserve relative loudness
+        if batch_reference is not None:
+            input_i = float(stats["input_i"])
+            # Formula: adjusted_target = target_level + (input_i - batch_reference)
+            # If track is quieter than average (input_i < batch_ref), offset is negative → quieter target
+            # If track is louder than average (input_i > batch_ref), offset is positive → louder target
+            adjusted_target = target_level + (input_i - batch_reference)
+            _logger.info(
+                f"Batch mode: Adjusting target from {target_level:.2f} to {adjusted_target:.2f} LUFS "
+                f"(input_i={input_i:.2f}, batch_ref={batch_reference:.2f}, offset={input_i - batch_reference:.2f})"
+            )
+            target_level = adjusted_target
+
         opts = {
             "i": target_level,
             "lra": self.media_file.ffmpeg_normalize.loudness_range_target,
@@ -576,11 +594,16 @@ class AudioStream(MediaStream):
 
         return "loudnorm=" + dict_to_filter_opts(opts)
 
-    def get_second_pass_opts_peakrms(self) -> str:
+    def get_second_pass_opts_peakrms(self, batch_reference: float | None = None) -> str:
         """
         Set the adjustment gain based on chosen option and mean/max volume,
         return the matching ffmpeg volume filter.
 
+        Args:
+            batch_reference (float | None, optional): Reference loudness for batch mode.
+                When provided, the target level is adjusted to preserve relative loudness.
+                Defaults to None.
+
         Returns:
             str: ffmpeg volume filter string
         """
@@ -595,6 +618,27 @@ class AudioStream(MediaStream):
         normalization_type = self.media_file.ffmpeg_normalize.normalization_type
         target_level = self.media_file.ffmpeg_normalize.target_level
 
+        # Adjust target level for batch mode to preserve relative loudness
+        if batch_reference is not None:
+            if normalization_type == "peak":
+                measured_level = float(self.loudness_statistics["max"])
+            elif normalization_type == "rms":
+                measured_level = float(self.loudness_statistics["mean"])
+            else:
+                raise FFmpegNormalizeError(
+                    "Can only set adjustment for peak and RMS normalization"
+                )
+
+            # Formula: adjusted_target = target_level + (measured_level - batch_reference)
+            # If track is quieter than average (measured < batch_ref), offset is negative → quieter target
+            # If track is louder than average (measured > batch_ref), offset is positive → louder target
+            adjusted_target = target_level + (measured_level - batch_reference)
+            _logger.info(
+                f"Batch mode: Adjusting target from {target_level:.2f} to {adjusted_target:.2f} dB "
+                f"(measured={measured_level:.2f}, batch_ref={batch_reference:.2f}, offset={measured_level - batch_reference:.2f})"
+            )
+            target_level = adjusted_target
+
         if normalization_type == "peak":
             adjustment = 0 + target_level - self.loudness_statistics["max"]
         elif normalization_type == "rms":

ffmpeg_normalize/data/presets/music.json

@@ -0,0 +1,6 @@
+{
+  "normalization-type": "rms",
+  "target-level": -20.0,
+  "batch": true,
+  "progress": true
+}

ffmpeg_normalize/data/presets/podcast.json

@@ -0,0 +1,7 @@
+{
+  "normalization-type": "ebu",
+  "target-level": -16.0,
+  "loudness-range-target": 7.0,
+  "true-peak": -2.0,
+  "progress": true
+}

ffmpeg_normalize/data/presets/streaming-video.json

@@ -0,0 +1,7 @@
+{
+  "normalization-type": "ebu",
+  "target-level": -14.0,
+  "loudness-range-target": 7.0,
+  "true-peak": -2.0,
+  "progress": true
+}

{ffmpeg_normalize-1.34.0.dist-info → ffmpeg_normalize-1.36.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ffmpeg-normalize
-Version: 1.34.0
+Version: 1.36.0
 Summary: Normalize audio via ffmpeg
 Keywords: ffmpeg,normalize,audio
 Author: Werner Robitza
@@ -46,12 +46,58 @@ This program normalizes media files to a certain loudness level using the EBU R1
 
 ## ✨ Features
 
-- EBU R128 loudness normalization (two-pass by default, with an option for one-pass dynamic normalization)
-- RMS-based normalization
-- Peak normalization
-- Video file support
-- Docker support
-- Python API
+- EBU R128 loudness normalization — Two-pass by default, with an option for one-pass dynamic normalization
+- RMS-based normalization — Adjust audio to a specific RMS level
+- Peak normalization — Adjust audio to a specific peak level
+- Selective audio stream normalization — Normalize specific audio streams or only default streams
+- Video file support — Process video files while preserving video streams
+- Docker support — Run via Docker container
+- Python API — Use programmatically in your Python projects
+- Shell completions — Available for bash, zsh, and fish
+- Album Batch normalization – Process files jointy, preserving relative loudness
+
+## 🆕 What's New
+
+- Version 1.36.0 introduces **presets** with `--preset`! Save and reuse your favorite normalization configurations for different use cases. Comes with three built-in presets: `podcast` (AES standard), `music` (RMS-based batch normalization), and `streaming-video` (video content). Create custom presets too!
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.mp3 --preset podcast
+    ```
+
+    applies the podcast preset (EBU R128, -16 LUFS) to your file. Learn more in the [presets guide](https://slhck.info/ffmpeg-normalize/usage/presets/).
+
+- Version 1.35.0 has **batch/album normalization** with `--batch`. It preserves relative loudness between files! Perfect for music albums where you want to shift all tracks by the same amount.
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize album/*.flac --batch -nt rms -t -20
+    ```
+
+    shifts the entire album so the average RMS is -20 dB, preserving the original relative loudness as mastered.
+
+- Version 1.34.0 brings **selective audio stream normalization**! You can now:
+
+  - Normalize specific audio streams with `-as/--audio-streams` (e.g., `-as 1,2` to normalize only streams 1 and 2)
+  - Normalize only default audio streams with `--audio-default-only` (useful for files with multiple language tracks)
+  - Keep other streams unchanged with `--keep-other-audio` (copy non-selected streams without normalization)
+
+    Example:
+
+    ```bash
+    ffmpeg-normalize input.mkv -as 1 --keep-other-audio
+    ```
+
+    normalizes stream 1 and copies all other audio streams unchanged.
+
+Other recent additions:
+
+- **Shell completions** (v1.31.0) — Tab completion for bash, zsh, and fish shells. See the [installation guide](https://slhck.info/ffmpeg-normalize/getting-started/installation/#shell-completions) for setup instructions.
+- **`--lower-only` option** — Prevent audio from increasing in loudness, only lower it if needed (works with all normalization types).
+
+See the [full changelog](https://github.com/slhck/ffmpeg-normalize/blob/master/CHANGELOG.md) for all updates.
 
 ## 🚀 Quick Start
 

ffmpeg_normalize-1.36.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+ffmpeg_normalize/__init__.py,sha256=l0arjiMMBNbiH3IH67gT6SdZjPGAVLAdorUx38dNtvE,508
+ffmpeg_normalize/__main__.py,sha256=4LgOHFwZS0lVcdYptNX4CCPDtG16yfMgUBjgom74FWg,25830
+ffmpeg_normalize/_cmd_utils.py,sha256=1JspVpguAPsq7DqvyvjUNzHhVv8J3X93xNOMwito_jY,5284
+ffmpeg_normalize/_errors.py,sha256=brTQ4osJ4fTA8wnyMPVVYfGwJ0wqeShRFydTEwi_VEY,48
+ffmpeg_normalize/_ffmpeg_normalize.py,sha256=jCiYhXeV3u8e7sJKOOnGYN5X7stcLv9eg_h_pR-1olM,21372
+ffmpeg_normalize/_logger.py,sha256=3Ap4Fxg7xGrzz7h4IGuNEf0KKstx0Rq_eLbHPrHzcrI,1841
+ffmpeg_normalize/_media_file.py,sha256=awznS5C8ph6Mjy5dzwT-ubBpB3MXwbO94QFcn7mBejY,32197
+ffmpeg_normalize/_presets.py,sha256=AffqFzAHvy0GxCuJl_qd3xknncPJUQx7OXbSfYAw2xg,8852
+ffmpeg_normalize/_streams.py,sha256=4Dnzuunhqz2qsOhlDv0dKML-lLjmPmUmM7M4dpn66Ow,24910
+ffmpeg_normalize/data/presets/music.json,sha256=rKtIKAD7jlMvnGRsx6QAyPHvrGu-Ecq4M5OcZgwNphA,96
+ffmpeg_normalize/data/presets/podcast.json,sha256=spMBZ_tbfU81NF6o7ZUMyQmQ7kPz3jJ1GKH-hcRmt4s,132
+ffmpeg_normalize/data/presets/streaming-video.json,sha256=Uy4QR0kSla4vXEqctZj26-8f_eS4SQxQWQ9zI_x5QBw,132
+ffmpeg_normalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ffmpeg_normalize-1.36.0.dist-info/licenses/LICENSE.md,sha256=ig-_YggmJGbPQC_gUgBNFa0_XMsuHTpocivFnlOF4tE,1082
+ffmpeg_normalize-1.36.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+ffmpeg_normalize-1.36.0.dist-info/entry_points.txt,sha256=1bdrW7-kJRc8tctjnGcfe_Fwx39z5JOm0yZnJHnmwl8,69
+ffmpeg_normalize-1.36.0.dist-info/METADATA,sha256=hXTuiFMbjXW1T2R9n9PPs8n9lF4i3JQfNbIUhPSbRpE,13933
+ffmpeg_normalize-1.36.0.dist-info/RECORD,,

ffmpeg_normalize-1.34.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-ffmpeg_normalize/__init__.py,sha256=l0arjiMMBNbiH3IH67gT6SdZjPGAVLAdorUx38dNtvE,508
-ffmpeg_normalize/__main__.py,sha256=pn5OePgr7-P5ajO3HxTMe4yQ1NR7wru5mGMHDklkbQI,22901
-ffmpeg_normalize/_cmd_utils.py,sha256=1JspVpguAPsq7DqvyvjUNzHhVv8J3X93xNOMwito_jY,5284
-ffmpeg_normalize/_errors.py,sha256=brTQ4osJ4fTA8wnyMPVVYfGwJ0wqeShRFydTEwi_VEY,48
-ffmpeg_normalize/_ffmpeg_normalize.py,sha256=ThIglofVOXxPMZcIrrYQ03HchlIOKmVSn41qILQNgg4,13193
-ffmpeg_normalize/_logger.py,sha256=3Ap4Fxg7xGrzz7h4IGuNEf0KKstx0Rq_eLbHPrHzcrI,1841
-ffmpeg_normalize/_media_file.py,sha256=Dz5vBDOelD1-GnlKX6830UbnlwvARFo3O_O-8Zyqlmw,31214
-ffmpeg_normalize/_streams.py,sha256=V5MnTjSnvQa6BNPSoFrUu0zg6mM-b9qaZE0ltGS2FV0,22329
-ffmpeg_normalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ffmpeg_normalize-1.34.0.dist-info/licenses/LICENSE.md,sha256=ig-_YggmJGbPQC_gUgBNFa0_XMsuHTpocivFnlOF4tE,1082
-ffmpeg_normalize-1.34.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-ffmpeg_normalize-1.34.0.dist-info/entry_points.txt,sha256=1bdrW7-kJRc8tctjnGcfe_Fwx39z5JOm0yZnJHnmwl8,69
-ffmpeg_normalize-1.34.0.dist-info/METADATA,sha256=yoBY7Ig4p2ijd91p1NcT96URVZKZPaDWb0A0XyysIQY,11425
-ffmpeg_normalize-1.34.0.dist-info/RECORD,,