audiolibrarian 0.17.0__py3-none-any.whl → 0.18.0__py3-none-any.whl

audiolibrarian/__init__.py

@@ -16,4 +16,4 @@
 #  You should have received a copy of the GNU General Public License along with audiolibrarian.
 #  If not, see <https://www.gnu.org/licenses/>.
 #
-__version__ = "0.17.0"
+__version__ = "0.18.0"

audiolibrarian/audiosource.py

@@ -27,8 +27,7 @@ from collections.abc import Callable  # noqa: TC003
 
 import discid
 
-from audiolibrarian import audiofile, records, sh, text
-from audiolibrarian.settings import SETTINGS
+from audiolibrarian import audiofile, config, records, sh, text
 
 log = logging.getLogger(__name__)
 
@@ -93,10 +92,10 @@ class AudioSource(abc.ABC):
 class CDAudioSource(AudioSource):
     """AudioSource from a compact disc."""
 
-    def __init__(self) -> None:
+    def __init__(self, settings: config.Settings) -> None:
         """Initialize a CDAudioSource."""
         super().__init__()
-        self._cd = discid.read(SETTINGS.discid_device, features=["mcn"])
+        self._cd = discid.read(settings.discid_device or None, features=["mcn"])
 
     def get_search_data(self) -> dict[str, str]:
         """Return a dictionary of search data useful for doing a MusicBrainz search."""

audiolibrarian/base.py

@@ -23,19 +23,25 @@ import argparse
 import logging
 import pathlib
 import shutil
-import subprocess
 import sys
 import warnings
 from collections.abc import Iterable
 from typing import Any, Final
 
 import colors
-import ffmpeg_normalize
 import filelock
 import yaml
 
-from audiolibrarian import audiofile, audiosource, musicbrainz, records, sh, text
-from audiolibrarian.settings import SETTINGS
+from audiolibrarian import (
+    audiofile,
+    audiosource,
+    config,
+    musicbrainz,
+    normalizer,
+    records,
+    sh,
+    text,
+)
 
 log = logging.getLogger(__name__)
 
@@ -49,8 +55,9 @@ class Base:
     command: str | None = None
     _manifest_file: Final[str] = "Manifest.yaml"
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize the base."""
+        self._settings = settings
         # Pull in stuff from args.
         search_keys = ("album", "artist", "mb_artist_id", "mb_release_id")
         self._provided_search_data = {k: v for k, v in vars(args).items() if k in search_keys}
@@ -60,8 +67,8 @@ class Base:
             self._disc_number, self._disc_count = 1, 1
 
         # Directories.
-        self._library_dir = SETTINGS.library_dir
-        self._work_dir = SETTINGS.work_dir
+        self._library_dir = self._settings.library_dir
+        self._work_dir = self._settings.work_dir
         self._flac_dir = self._work_dir / "flac"
         self._m4a_dir = self._work_dir / "m4a"
         self._mp3_dir = self._work_dir / "mp3"
@@ -70,7 +77,7 @@ class Base:
 
         self._lock = filelock.FileLock(str(self._work_dir) + ".lock")
 
-        self._normalizer = self._which_normalizer()
+        self._normalizer = normalizer.Normalizer.factory(self._settings.normalize)
 
         # Initialize stuff that will be defined later.
         self._audio_source: audiosource.AudioSource | None = None
@@ -143,7 +150,7 @@ class Base:
         search_data: dict[str, str] = (
             self._audio_source.get_search_data() if self._audio_source is not None else {}
         )
-        searcher = musicbrainz.Searcher(**search_data)  # type: ignore[arg-type]
+        searcher = musicbrainz.Searcher(settings=self._settings.musicbrainz, **search_data)  # type: ignore[arg-type]
         searcher.disc_number = str(self._disc_number)
         # Override with user-provided info.
         if value := self._provided_search_data.get("artist"):
@@ -269,35 +276,7 @@ class Base:
 
     def _normalize(self) -> None:
         """Normalize the wav files using the selected normalizer."""
-        if self._normalizer == "none":
-            return
-        print(f"Normalizing wav files using {self._normalizer}...")
-
-        if self._normalizer == "wavegain":
-            command = [
-                "wavegain",
-                f"--{SETTINGS.normalize.wavegain.preset}",
-                f"--gain={SETTINGS.normalize.wavegain.gain}",
-                "--apply",
-            ]
-            command.extend(str(f) for f in self._wav_filenames)
-            result = subprocess.run(command, capture_output=True, check=False)  # noqa: S603
-            for line in str(result.stderr).split(r"\n"):
-                line_trunc = line[:137] + "..." if len(line) > 140 else line  # noqa: PLR2004
-                log.info("WAVEGAIN: %s", line_trunc)
-            result.check_returncode()
-            return
-
-        normalizer = ffmpeg_normalize.FFmpegNormalize(
-            extension="wav",
-            keep_loudness_range_target=True,
-            target_level=SETTINGS.normalize.ffmpeg.target_level,
-        )
-        for wav_file in self._wav_filenames:
-            normalizer.add_media_file(str(wav_file), str(wav_file))
-        log.info("NORMALIZER: starting ffmpeg normalization...")
-        normalizer.run_normalization()
-        log.info("NORMALIZER: ffmpeg normalization completed successfully")
+        self._normalizer.normalize(set(self._wav_filenames))
 
     def _rename_wav(self) -> None:
         """Rename the wav files to a filename-sane representation of the track title."""
@@ -428,34 +407,6 @@ class Base:
             yaml.dump(manifest, manifest_file)
         print(f"Wrote {manifest_filename}")
 
-    @staticmethod
-    def _which_normalizer() -> str:
-        """Determine which normalizer to use based on settings and availability.
-
-        Returns:
-            str: The name of the normalizer to use ("wavegain", "ffmpeg" or "none")
-        """
-        normalizer = SETTINGS.normalize.normalizer
-        if normalizer == "none":
-            return "none"
-
-        wavegain_found = shutil.which("wavegain")
-        if normalizer in ("auto", "wavegain") and wavegain_found:
-            return "wavegain"
-
-        ffmpeg_found = shutil.which("ffmpeg")
-        if normalizer in ("auto", "ffmpeg") and ffmpeg_found:
-            return "ffmpeg"
-
-        if wavegain_found:
-            log.warning("ffmpeg not found, using wavegain for normalization")
-            return "wavegain"
-        if ffmpeg_found:
-            log.warning("wavegain not found, using ffmpeg for normalization")
-            return "ffmpeg"
-        log.warning("wavegain not found, ffmpeg not found, using no normalization")
-        return "none"
-
     @staticmethod
     def _find_audio_files(directories: list[str | pathlib.Path]) -> Iterable[audiofile.AudioFile]:
         """Yield audiofile objects found in the given directories."""

audiolibrarian/commands.py

@@ -22,7 +22,7 @@ import pathlib
 import re
 from typing import Any
 
-from audiolibrarian import __version__, audiofile, audiosource, base, genremanager
+from audiolibrarian import __version__, audiofile, audiosource, base, config, genremanager
 
 log = logging.getLogger(__name__)
 
@@ -39,6 +39,46 @@ class _Command:
         return True
 
 
+class Config(_Command, base.Base):
+    """AudioLibrarian tool for working with a config file.
+
+    This class performs all of its tasks on instantiation and provides no public members or
+    methods.
+    """
+
+    command = "config"
+    help = "work with the config file"
+    parser = argparse.ArgumentParser(description="Manage AudioLibrarian configuration")
+    parser.add_argument(
+        "--init",
+        "-i",
+        action="store_true",
+        help="initialize a new config file if it doesn't exist",
+    )
+
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
+        """Initialize a Config command handler."""
+        super().__init__(args, settings)
+
+        if args.init:
+            try:
+                config.init_config_file()
+            except FileExistsError as e:
+                msg = f"Config file already exists at {config.CONFIG_PATH}"
+                raise SystemExit(msg) from e
+            except Exception:
+                log.exception("Error creating config file")
+                raise
+            print(f"Created new config file at {config.CONFIG_PATH}")
+        else:
+            print(f"Config file location: {config.CONFIG_PATH}")
+            if config.CONFIG_PATH.exists():
+                print("\n=== Config file contents ===")
+                print(config.CONFIG_PATH.read_text(encoding="utf-8"))
+            else:
+                print("Config file does not exist. Use '--init' to create it.")
+
+
 class Convert(_Command, base.Base):
     """AudioLibrarian tool for converting and tagging audio files.
 
@@ -56,9 +96,9 @@ class Convert(_Command, base.Base):
     parser.add_argument("--disc", "-d", help="format: x/y: disc x of y for multi-disc release")
     parser.add_argument("filename", nargs="+", help="directory name or audio file name")
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize a Convert command handler."""
-        super().__init__(args)
+        super().__init__(args, settings)
         self._source_is_cd = False
         self._audio_source = audiosource.FilesAudioSource([pathlib.Path(x) for x in args.filename])
         self._get_tag_info()
@@ -88,9 +128,9 @@ class Genre(_Command):
     parser_action.add_argument("--tag", action="store_true", help="update tags")
     parser_action.add_argument("--update", action="store_true", help="update MusicBrainz")
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize a Genre command handler."""
-        genremanager.GenreManager(args)
+        genremanager.GenreManager(args=args, settings=settings.musicbrainz)
 
 
 class Manifest(_Command, base.Base):
@@ -111,9 +151,9 @@ class Manifest(_Command, base.Base):
     parser.add_argument("--disc", "-d", help="format: x/y: disc x of y for multi-disc release")
     parser.add_argument("filename", nargs="+", help="directory name or audio file name")
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize a Manifest command handler."""
-        super().__init__(args)
+        super().__init__(args, settings)
         self._source_is_cd = args.cd
         self._audio_source = audiosource.FilesAudioSource([pathlib.Path(x) for x in args.filename])
         source_filenames = self._audio_source.get_source_filenames()
@@ -139,9 +179,9 @@ class Reconvert(_Command, base.Base):
     parser = argparse.ArgumentParser()
     parser.add_argument("directories", nargs="+", help="source directories")
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize a Reconvert command handler."""
-        super().__init__(args)
+        super().__init__(args, settings)
         self._source_is_cd = False
         manifest_paths = self._find_manifests(args.directories)
         count = len(manifest_paths)
@@ -172,9 +212,9 @@ class Rename(_Command, base.Base):
     parser.add_argument("--dry-run", action="store_true", help="don't actually rename files")
     parser.add_argument("directories", nargs="+", help="audio file directories")
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize a Rename command handler."""
-        super().__init__(args)
+        super().__init__(args, settings)
         self._source_is_cd = False
         print("Finding audio files...")
         for audio_file in self._find_audio_files(args.directories):
@@ -233,11 +273,11 @@ class Rip(_Command, base.Base):
     parser.add_argument("--mb-release-id", help="MusicBrainz release ID")
     parser.add_argument("--disc", "-d", help="x/y: disc x of y; multi-disc release")
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize a Rip command handler."""
-        super().__init__(args)
+        super().__init__(args, settings)
         self._source_is_cd = True
-        self._audio_source = audiosource.CDAudioSource()
+        self._audio_source = audiosource.CDAudioSource(settings)
         self._get_tag_info()
         self._convert()
         self._write_manifest()
@@ -254,9 +294,10 @@ class Version(_Command):
     command = "version"
     help = "display the program version"
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.Settings) -> None:
         """Initialize a Version command handler."""
-        _ = args
+        _, _ = args, settings
+        del args, settings  # Unused.
         print(f"audiolibrarian {__version__}")
 
 
@@ -280,4 +321,4 @@ def _validate_disc_arg(args: argparse.Namespace) -> bool:
     return True
 
 
-COMMANDS: set[Any] = {Convert, Genre, Manifest, Reconvert, Rename, Rip, Version}
+COMMANDS: set[Any] = {Config, Convert, Genre, Manifest, Reconvert, Rename, Rip, Version}

audiolibrarian/{settings.py → config.py}

@@ -7,8 +7,8 @@ sources of configuration:
    - Prefix: "AUDIOLIBRARIAN__"
    - Nested fields: Use "__" as delimiter (e.g., AUDIOLIBRARIAN__MUSICBRAINZ__USERNAME)
 
-2. YAML Configuration File:
-   - Location: $XDG_CONFIG_HOME/audiolibrarian/config.yaml
+2. TOML Configuration File:
+   - Location: $XDG_CONFIG_HOME/audiolibrarian/config.toml
    - Supports nested structure for MusicBrainz settings
 
 3. Default Values:
@@ -39,37 +39,51 @@ Sensitive fields (like passwords) are handled using pydantic.SecretStr for secur
 #
 import logging
 import pathlib
-from typing import Literal
+from typing import Annotated, Final, Literal
 
 import pydantic
 import pydantic_settings
 import xdg_base_dirs
 
+CONFIG_PATH: Final[pathlib.Path] = (
+    xdg_base_dirs.xdg_config_home() / "audiolibrarian" / "config.toml"
+)
+
 logger = logging.getLogger(__name__)
 
+ExpandedPath = Annotated[
+    pathlib.Path,
+    pydantic.AfterValidator(lambda v: v.expanduser()),
+]
+
+
+class EmptySettings(pydantic.BaseModel):
+    """Empty settings."""
 
-class MusicBrainzSettings(pydantic_settings.BaseSettings):
+
+class MusicBrainzSettings(pydantic.BaseModel):
     """Configuration settings for MusicBrainz."""
 
     password: pydantic.SecretStr = pydantic.SecretStr("")
     username: str = ""
     rate_limit: pydantic.PositiveFloat = 1.5  # Seconds between requests.
+    work_dir: ExpandedPath = xdg_base_dirs.xdg_cache_home() / "audiolibrarian"
 
 
-class NormalizeFFmpegSettings(pydantic_settings.BaseSettings):
+class NormalizeFFmpegSettings(pydantic.BaseModel):
     """Configuration settings for ffmpeg normalization."""
 
     target_level: float = -13
 
 
-class NormalizeWavegainSettings(pydantic_settings.BaseSettings):
+class NormalizeWavegainSettings(pydantic.BaseModel):
     """Configuration settings for wavegain normalization."""
 
     gain: int = 5  # dB
     preset: Literal["album", "radio"] = "radio"
 
 
-class NormalizeSettings(pydantic_settings.BaseSettings):
+class NormalizeSettings(pydantic.BaseModel):
     """Configuration settings for audio normalization."""
 
     normalizer: Literal["auto", "wavegain", "ffmpeg", "none"] = "auto"
@@ -80,16 +94,16 @@ class NormalizeSettings(pydantic_settings.BaseSettings):
 class Settings(pydantic_settings.BaseSettings):
     """Configuration settings for AudioLibrarian."""
 
-    discid_device: str | None = None  # Use default device.
-    library_dir: pathlib.Path = pathlib.Path("library").resolve()
+    discid_device: str = ""  # Use default device.
+    library_dir: ExpandedPath = pathlib.Path("library").resolve()
     musicbrainz: MusicBrainzSettings = MusicBrainzSettings()
     normalize: NormalizeSettings = NormalizeSettings()
-    work_dir: pathlib.Path = xdg_base_dirs.xdg_cache_home() / "audiolibrarian"
+    work_dir: ExpandedPath = xdg_base_dirs.xdg_cache_home() / "audiolibrarian"
 
     model_config = pydantic_settings.SettingsConfigDict(
         env_nested_delimiter="__",
         env_prefix="AUDIOLIBRARIAN__",
-        yaml_file=str(xdg_base_dirs.xdg_config_home() / "audiolibrarian" / "config.yaml"),
+        toml_file=str(CONFIG_PATH),
         frozen=True,  # Make settings immutable.
     )
 
@@ -102,13 +116,37 @@ class Settings(pydantic_settings.BaseSettings):
         dotenv_settings: pydantic_settings.PydanticBaseSettingsSource,
         file_secret_settings: pydantic_settings.PydanticBaseSettingsSource,
     ) -> tuple[pydantic_settings.PydanticBaseSettingsSource, ...]:
+        """Customize settings sources."""
         del dotenv_settings, file_secret_settings  # Unused.
         return (
+            init_settings,  # Used for tests.
             env_settings,
-            pydantic_settings.YamlConfigSettingsSource(settings_cls),
-            init_settings,
+            pydantic_settings.TomlConfigSettingsSource(settings_cls),
         )
 
 
-SETTINGS = Settings()
-__all__ = ["SETTINGS"]
+def init_config_file() -> None:
+    """Initialize a new config file with default values.
+
+    The config file will be created at the location specified by CONFIG_PATH.
+    If the parent directory doesn't exist, it will be created.
+
+    Raises:
+        FileExistsError: If the config file already exists
+        OSError: If there's an error creating the file or directories
+        FileNotFoundError: If the template file cannot be found
+    """
+    if CONFIG_PATH.exists():
+        msg = f"Config file already exists at {CONFIG_PATH}"
+        logger.warning(msg)
+        raise FileExistsError(msg)
+
+    # Create the config directory if it doesn't exist
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    # Get the directory where this file is located
+    template_dir = pathlib.Path(__file__).parent / "templates"
+    template_file = template_dir / CONFIG_PATH.name
+
+    # Read the template and write to the config file
+    CONFIG_PATH.write_text(template_file.read_text(encoding="utf-8"), encoding="utf-8")

audiolibrarian/entrypoints/__init__.py

@@ -0,0 +1,17 @@
+"""Entrypoints for audiolibrarian."""
+#
+#  Copyright (c) 2000-2025 Stephen Jibson
+#
+#  This file is part of audiolibrarian.
+#
+#  Audiolibrarian is free software: you can redistribute it and/or modify it under the terms of the
+#  GNU General Public License as published by the Free Software Foundation, either version 3 of the
+#  License, or (at your option) any later version.
+#
+#  Audiolibrarian is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+#  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
+#  the GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along with audiolibrarian.
+#  If not, see <https://www.gnu.org/licenses/>.
+#

audiolibrarian/{cli.py → entrypoints/cli.py}

@@ -23,7 +23,7 @@ import subprocess
 import sys
 from typing import Final
 
-from audiolibrarian import commands
+from audiolibrarian import commands, config
 
 log = logging.getLogger("audiolibrarian")
 
@@ -57,7 +57,7 @@ class CommandLineInterface:
             if self._args.command == cmd.command:
                 if not cmd.validate_args(self._args):
                     sys.exit(2)
-                cmd(self._args)
+                cmd(self._args, config.Settings())
                 break
         if self._args.log_level == logging.DEBUG:
             print(pathlib.Path("/proc/self/status").read_text(encoding="utf-8"))

audiolibrarian/genremanager.py

@@ -29,8 +29,7 @@ import mutagen.flac
 import mutagen.id3
 import mutagen.mp4
 
-from audiolibrarian import musicbrainz, text
-from audiolibrarian.settings import SETTINGS
+from audiolibrarian import config, musicbrainz, text
 
 log = logging.getLogger(__name__)
 
@@ -38,10 +37,11 @@ log = logging.getLogger(__name__)
 class GenreManager:
     """Manage genres."""
 
-    def __init__(self, args: argparse.Namespace) -> None:
+    def __init__(self, args: argparse.Namespace, settings: config.MusicBrainzSettings) -> None:
         """Initialize a GenreManager instance."""
         self._args = args
-        self._mb = musicbrainz.MusicBrainzSession()
+        self._settings = settings
+        self._mb = musicbrainz.MusicBrainzSession(settings=settings)
         self._paths = self._get_all_paths()
         self._paths_by_artist = self._get_paths_by_artist()
         _u, _c = self._get_genres_by_artist()
@@ -149,7 +149,7 @@ class GenreManager:
         user: dict[str, str] = {}
         community: dict[str, dict[str, Any]] = {}
         user_modified = False
-        cache_file = SETTINGS.work_dir / "user-genres.pickle"
+        cache_file = self._settings.work_dir / "user-genres.pickle"
         if cache_file.exists():
             with cache_file.open(mode="rb") as cache_file_obj:
                 user = pickle.load(cache_file_obj)  # noqa: S301

audiolibrarian/musicbrainz.py

@@ -30,8 +30,7 @@ import requests
 from fuzzywuzzy import fuzz
 from requests import auth
 
-from audiolibrarian import __version__, records, text
-from audiolibrarian.settings import SETTINGS
+from audiolibrarian import __version__, config, records, text
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -48,11 +47,11 @@ class MusicBrainzSession:
     It can be for things that are not supported by the musicbrainzngs library.
     """
 
-    _api_rate = dt.timedelta(seconds=SETTINGS.musicbrainz.rate_limit)
     _last_api_call = dt.datetime.now(tz=dt.UTC)
 
-    def __init__(self) -> None:
+    def __init__(self, settings: config.MusicBrainzSettings) -> None:
         """Initialize a MusicBrainzSession."""
+        self._settings = settings
         self.__session: requests.Session | None = None
 
     def __del__(self) -> None:
@@ -65,8 +64,8 @@ class MusicBrainzSession:
         if self.__session is None:
             self.__session = requests.Session()
 
-            if (username := SETTINGS.musicbrainz.username) and (
-                password := SETTINGS.musicbrainz.password.get_secret_value()
+            if (username := self._settings.username) and (
+                password := self._settings.password.get_secret_value()
             ):
                 self._session.auth = auth.HTTPDigestAuth(username, password)
             self._session.headers.update(
@@ -108,14 +107,17 @@ class MusicBrainzSession:
             params["inc"] = "+".join(includes)
         return self._get(f"release-group/{release_group_id}", params=params)
 
-    @staticmethod
-    def sleep() -> None:
+    def sleep(self) -> None:
         """Sleep so we don't abuse the MusicBrainz API service.
 
         See https://musicbrainz.org/doc/MusicBrainz_API/Rate_Limiting
         """
         since_last = dt.datetime.now(tz=dt.UTC) - MusicBrainzSession._last_api_call
-        if (sleep_seconds := (MusicBrainzSession._api_rate - since_last).total_seconds()) > 0:
+        if (
+            sleep_seconds := (
+                dt.timedelta(seconds=self._settings.rate_limit) - since_last
+            ).total_seconds()
+        ) > 0:
             log.debug("Sleeping %s to avoid throttling...", sleep_seconds)
             time.sleep(sleep_seconds)
             MusicBrainzSession._last_api_call = dt.datetime.now(tz=dt.UTC)
@@ -137,11 +139,17 @@ class MusicBrainzRelease:
         "work-level-rels",
     ]
 
-    def __init__(self, release_id: str, *, verbose: bool = False) -> None:
+    def __init__(
+        self,
+        release_id: str,
+        settings: config.MusicBrainzSettings,
+        *,
+        verbose: bool = False,
+    ) -> None:
         """Initialize an MusicBrainzRelease."""
         self._release_id = release_id
         self._verbose = verbose
-        self._session = MusicBrainzSession()
+        self._session = MusicBrainzSession(settings=settings)
         self._session.sleep()
         self._release = mb.get_release_by_id(release_id, includes=self._includes)["release"]
         self._release_record: records.Release | None = None
@@ -392,10 +400,16 @@ class Searcher:
     mb_release_id: str = ""
     __mb_session: MusicBrainzSession | None = None
 
+    settings: dataclasses.InitVar[config.MusicBrainzSettings] = None
+
+    def __post_init__(self, settings: config.MusicBrainzSettings) -> None:
+        """Process additional variables."""
+        self._settings = settings
+
     @property
     def _mb_session(self) -> MusicBrainzSession:
         if self.__mb_session is None:
-            self.__mb_session = MusicBrainzSession()
+            self.__mb_session = MusicBrainzSession(settings=self._settings)
         return self.__mb_session
 
     def find_music_brains_release(self) -> records.Release | None:
@@ -419,7 +433,7 @@ class Searcher:
         else:
             release_id = self._prompt_uuid("MusicBrainz Release ID: ")
 
-        return MusicBrainzRelease(release_id).get_release()
+        return MusicBrainzRelease(release_id=release_id, settings=self._settings).get_release()
 
     def _get_release_group_ids(self) -> list[str]:
         # Return release groups that fuzzy-match the search criteria.

audiolibrarian/normalizer.py

@@ -0,0 +1,155 @@
+"""Audio normalization functionality using different backends."""
+#
+#  Copyright (c) 2000-2025 Stephen Jibson
+#
+#  This file is part of audiolibrarian.
+#
+#  Audiolibrarian is free software: you can redistribute it and/or modify it under the terms of the
+#  GNU General Public License as published by the Free Software Foundation, either version 3 of the
+#  License, or (at your option) any later version.
+#
+#  Audiolibrarian is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+#  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
+#  the GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License along with audiolibrarian.`
+#  If not, see <https://www.gnu.org/licenses/>.
+#
+
+import abc
+import logging
+import pathlib
+import shutil
+import subprocess
+from typing import Any, TypeVar
+
+import ffmpeg_normalize
+import pydantic
+
+from audiolibrarian import config
+
+log = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=pydantic.BaseModel)
+
+
+class Normalizer[T](abc.ABC):
+    """Abstract base class for audio normalizers."""
+
+    def __init__(self, settings: T) -> None:
+        """Initialize a Normalizer instance.
+
+        Args:
+            settings: The settings specific to this normalizer type.
+        """
+        self._settings: T = settings
+
+    @classmethod
+    def factory(cls, settings: config.NormalizeSettings) -> "Normalizer[Any]":
+        """Create the appropriate normalizer based on settings.
+
+        Args:
+            settings: The normalization settings.
+
+        Returns:
+            An instance of the appropriate Normalizer implementation.
+        """
+        if settings.normalizer == "none":
+            return NoOpNormalizer(config.EmptySettings())
+
+        wavegain_found = shutil.which("wavegain")
+        if settings.normalizer in ("auto", "wavegain") and wavegain_found:
+            return WaveGainNormalizer(settings.wavegain)
+
+        ffmpeg_found = shutil.which("ffmpeg")
+        if settings.normalizer in ("auto", "ffmpeg") and ffmpeg_found:
+            return FFmpegNormalizer(settings.ffmpeg)
+
+        if wavegain_found:
+            log.warning("ffmpeg not found, using wavegain for normalization")
+            return WaveGainNormalizer(settings.wavegain)
+        if ffmpeg_found:
+            log.warning("wavegain not found, using ffmpeg for normalization")
+            return FFmpegNormalizer(settings.ffmpeg)
+        log.warning("wavegain not found, ffmpeg not found, using no normalization")
+        return NoOpNormalizer(config.EmptySettings())
+
+    @abc.abstractmethod
+    def normalize(self, paths: set[pathlib.Path]) -> None:
+        """Normalize the given audio files.
+
+        Args:
+            paths: Set of audio file paths to normalize.
+
+        Raises:
+            Exception: If the normalization process fails.
+        """
+
+
+class NoOpNormalizer(Normalizer[config.EmptySettings]):
+    """No-op normalizer that does nothing."""
+
+    def normalize(self, paths: set[pathlib.Path]) -> None:
+        """Do not perform any normalization."""
+        del paths  # Unused.
+        log.info("Skipping audio normalization")
+
+
+class WaveGainNormalizer(Normalizer[config.NormalizeWavegainSettings]):
+    """Audio normalizer using wavegain."""
+
+    def normalize(self, paths: set[pathlib.Path]) -> None:
+        """Normalize audio files using wavegain.
+
+        Args:
+            paths: List of audio file paths to normalize.
+
+        Raises:
+            subprocess.CalledProcessError: If wavegain process fails.
+        """
+        if not paths:
+            return
+
+        log.info("Normalizing %d files with wavegain...", len(paths))
+
+        command = [
+            "wavegain",
+            f"--{self._settings.preset}",
+            f"--gain={self._settings.gain}",
+            "--apply",
+            *[str(f) for f in paths],
+        ]
+        result = subprocess.run(command, capture_output=True, check=False)  # noqa: S603
+        for line in str(result.stderr).split(r"\n"):
+            line_trunc = line[:137] + "..." if len(line) > 140 else line  # noqa: PLR2004
+            log.info("WAVEGAIN: %s", line_trunc)
+        result.check_returncode()  # May raise subprocess.CalledProcessError.
+
+
+class FFmpegNormalizer(Normalizer[config.NormalizeFFmpegSettings]):
+    """Audio normalizer using ffmpeg-normalize."""
+
+    def normalize(self, paths: set[pathlib.Path]) -> None:
+        """Normalize audio files using ffmpeg-normalize.
+
+        Args:
+            paths: List of audio file paths to normalize.
+
+        Raises:
+            Exception: If ffmpeg-normalize process fails.
+        """
+        if not paths:
+            return
+
+        log.info("Normalizing %d files with ffmpeg-normalize...", len(paths))
+
+        normalizer = ffmpeg_normalize.FFmpegNormalize(
+            extension="wav",
+            keep_loudness_range_target=True,
+            target_level=self._settings.target_level,
+        )
+        for path in paths:
+            normalizer.add_media_file(str(path), str(path))
+        log.info("Starting ffmpeg normalization...")
+        normalizer.run_normalization()
+        log.info("FFmpeg normalization completed successfully")

audiolibrarian/templates/config.toml

@@ -0,0 +1,36 @@
+# AudioLibrarian Configuration
+#
+# This file was automatically generated. Modify as needed.
+#
+
+# Path to your music library
+# library_dir = "~/Music/Library"
+
+# Disc ID device (default: system default)
+# discid_device = "/dev/sr0"
+
+# Working directory for temporary files
+# work_dir = "~/.cache/audiolibrarian"
+
+
+[musicbrainz]
+# MusicBrainz username and password (optional)
+# username = ""
+# password = ""  # Will be stored in plain text!
+
+# Rate limit in seconds between requests
+# rate_limit = 1.5
+
+[normalize]
+# Normalizer to use: "auto", "wavegain", "ffmpeg", or "none"
+# normalizer = "auto"
+
+[normalize.ffmpeg]
+# Target level in dB for ffmpeg normalization
+# target_level = -13.0
+
+[normalize.wavegain]
+# Album gain preset: "album" or "radio"
+# preset = "radio"
+# Gain in dB for wavegain
+# gain = 5

{audiolibrarian-0.17.0.dist-info → audiolibrarian-0.18.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiolibrarian
-Version: 0.17.0
+Version: 0.18.0
 Summary: Manage my audio library.
 Project-URL: Repository, https://github.com/toadstule/audiolibrarian
 Author-email: Steve Jibson <steve@jibson.com>

audiolibrarian-0.18.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+audiolibrarian/__init__.py,sha256=y8iHtIRKpBt2gg-NJssr_wBkpo_qMXNDzyugA5QXUi0,792
+audiolibrarian/audiosource.py,sha256=UvTU2XBY_-B4bBCOh4Dl7xn1hQ2KUPcW1jjoEGMTe-Q,8548
+audiolibrarian/base.py,sha256=H-lX1A-ve950AY6SAlwBlLmKBQT5WU_fHbvNRfOYhes,19118
+audiolibrarian/commands.py,sha256=QEmKp0OYlg6XVcFi8tZ8XUj-X53xRCk7LILmBMV8fr0,12990
+audiolibrarian/config.py,sha256=OjHxyslIOkOsaALC3zd6JtmXxz3HPBb2iaDFvmyRweA,5345
+audiolibrarian/genremanager.py,sha256=cwHXAQ44toSe_ZSOix8iSaHkVyyXuy62TjcjOUHvMA0,7420
+audiolibrarian/musicbrainz.py,sha256=pLgj0Z2PmwPVBw0WTLDDX8vGoV4cfKLTI3cLkK7r7NU,19712
+audiolibrarian/normalizer.py,sha256=TaQcSsFkJqSTbNTfjFm4YcXAm9-T1uTcAa75pwJ2W-Y,5213
+audiolibrarian/output.py,sha256=MQGsKrOfkRASGkVG4CEi2kgj0smEm8TfXqAR-lwULwk,1707
+audiolibrarian/records.py,sha256=87DXbpwzl8Fsh71Nzi5XmJDAaEGvRjH6vwJ75cIM9PQ,7934
+audiolibrarian/sh.py,sha256=7V-FrSSiq56cNL1IyYBEcSUXtMbwFs6Ob1EhU_i_c84,1917
+audiolibrarian/text.py,sha256=VrxrQm6pZtuYbK9MlukSC3MdqDBSlsnTgkhBTwj9MpY,4031
+audiolibrarian/audiofile/__init__.py,sha256=PTBAVV5gfSc0UVvWMHyeL1d3xwhgJ8J00L-KVhuCGhY,898
+audiolibrarian/audiofile/audiofile.py,sha256=UCVXu2ga7stnTzeeLzrx-JTFl5ad82qy45HmB3g2a8c,4357
+audiolibrarian/audiofile/tags.py,sha256=Di8TjvOYZYYgedMNRZ8tTGFxZ1KN4oAK7z17TzTSeZg,1790
+audiolibrarian/audiofile/formats/__init__.py,sha256=DexI0KdI6hnbDhvK9xuEFvYyyQA2SOFT_xfadc42Nsk,759
+audiolibrarian/audiofile/formats/flac.py,sha256=UNXfZbnL0cjzmlS3nuZ26QczrfD-twgc7S6PbtoOkqA,9713
+audiolibrarian/audiofile/formats/m4a.py,sha256=Ki-pHnObeEMXegIAHu7ymtB_PjMiWLDU5HHXaWxaPPo,10557
+audiolibrarian/audiofile/formats/mp3.py,sha256=SQOcPVAE-coDz4tK-gopWSWJE02nQBTbxrlmRkyK7QU,12886
+audiolibrarian/entrypoints/__init__.py,sha256=9xOQM6uwVi_sP5pdnKI_mVIIEWEGvp2MvMOHA28RmrQ,772
+audiolibrarian/entrypoints/cli.py,sha256=Mz_MsjHK5NyWwfv1VBZrlgvzt4VR8M53cGzWbqZccP8,4223
+audiolibrarian/templates/config.toml,sha256=NYf6kN0cEY-34_76v1r9nB6PChdm2Q8N2zhzlSDUmmI,803
+picard_src/README.md,sha256=mtJ7RNLlC7Oz9M038WU-3ciPa7jPdXlFLYdJBL8iRQo,411
+picard_src/__init__.py,sha256=acu0-oac_qfEgiB0rw0RvuL---O15-rOckWboVMxWtM,198
+picard_src/textencoding.py,sha256=0MRHFwhqEwauQbjTTz6gpgzo6YH1VDPfdJqQoCWHtjM,26234
+audiolibrarian-0.18.0.dist-info/METADATA,sha256=c0Jv3vtxtJdf8o-KsqjSmBdZSDRCQzHViqaELj1Nmhg,2578
+audiolibrarian-0.18.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+audiolibrarian-0.18.0.dist-info/entry_points.txt,sha256=6TrDdRLEnIpD56rCeA0TURxwhT3vaFpeyis1zRF0Kdo,71
+audiolibrarian-0.18.0.dist-info/licenses/COPYING,sha256=WJ7YI-moTFb-uVrFjnzzhGJrnL9P2iqQe8NuED3hutI,35141
+audiolibrarian-0.18.0.dist-info/licenses/LICENSE,sha256=WJ7YI-moTFb-uVrFjnzzhGJrnL9P2iqQe8NuED3hutI,35141
+audiolibrarian-0.18.0.dist-info/RECORD,,

audiolibrarian-0.18.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+audiolibrarian = audiolibrarian.entrypoints.cli:main

audiolibrarian-0.17.0.dist-info/RECORD

@@ -1,28 +0,0 @@
-audiolibrarian/__init__.py,sha256=nk7MHHw3booS4scifS56NhceSDNsLnU7vcljwNcLcZ0,792
-audiolibrarian/audiosource.py,sha256=Xs8KBvb0Jd-JRHv3veyBA9lL2siC70-gO2RdZqy2ntk,8550
-audiolibrarian/base.py,sha256=yDN2PELNboUr_eD-Ix8xi-JHhq8XbDuaj4AnvergSIE,21263
-audiolibrarian/cli.py,sha256=vtAJND7U5yoBCbm20HRCvIFp2HYzXl3jfHNfsNUQVlE,4196
-audiolibrarian/commands.py,sha256=rM44NQUKtZsBI3C8EY0u0vRrricfj3felM00x16fBeU,11171
-audiolibrarian/genremanager.py,sha256=ag4LGcXPHjuI-Y07DTmGjVcaUKyKazyWHGBak9YzVAg,7362
-audiolibrarian/musicbrainz.py,sha256=hoZKDueqgfMo-Da_ZH3_bQcRXqRvaz9KCx9MARMI5h8,19317
-audiolibrarian/output.py,sha256=MQGsKrOfkRASGkVG4CEi2kgj0smEm8TfXqAR-lwULwk,1707
-audiolibrarian/records.py,sha256=87DXbpwzl8Fsh71Nzi5XmJDAaEGvRjH6vwJ75cIM9PQ,7934
-audiolibrarian/settings.py,sha256=GSuT3zOa6jyrejx14_dLwJaTA6eCTNYFq6EQ9UQOzhI,4042
-audiolibrarian/sh.py,sha256=7V-FrSSiq56cNL1IyYBEcSUXtMbwFs6Ob1EhU_i_c84,1917
-audiolibrarian/text.py,sha256=VrxrQm6pZtuYbK9MlukSC3MdqDBSlsnTgkhBTwj9MpY,4031
-audiolibrarian/audiofile/__init__.py,sha256=PTBAVV5gfSc0UVvWMHyeL1d3xwhgJ8J00L-KVhuCGhY,898
-audiolibrarian/audiofile/audiofile.py,sha256=UCVXu2ga7stnTzeeLzrx-JTFl5ad82qy45HmB3g2a8c,4357
-audiolibrarian/audiofile/tags.py,sha256=Di8TjvOYZYYgedMNRZ8tTGFxZ1KN4oAK7z17TzTSeZg,1790
-audiolibrarian/audiofile/formats/__init__.py,sha256=DexI0KdI6hnbDhvK9xuEFvYyyQA2SOFT_xfadc42Nsk,759
-audiolibrarian/audiofile/formats/flac.py,sha256=UNXfZbnL0cjzmlS3nuZ26QczrfD-twgc7S6PbtoOkqA,9713
-audiolibrarian/audiofile/formats/m4a.py,sha256=Ki-pHnObeEMXegIAHu7ymtB_PjMiWLDU5HHXaWxaPPo,10557
-audiolibrarian/audiofile/formats/mp3.py,sha256=SQOcPVAE-coDz4tK-gopWSWJE02nQBTbxrlmRkyK7QU,12886
-picard_src/README.md,sha256=mtJ7RNLlC7Oz9M038WU-3ciPa7jPdXlFLYdJBL8iRQo,411
-picard_src/__init__.py,sha256=acu0-oac_qfEgiB0rw0RvuL---O15-rOckWboVMxWtM,198
-picard_src/textencoding.py,sha256=0MRHFwhqEwauQbjTTz6gpgzo6YH1VDPfdJqQoCWHtjM,26234
-audiolibrarian-0.17.0.dist-info/METADATA,sha256=CvHJpVXiHY01H6rQ828Nu_a4Yzr-KXrXWXh5BgOl-X0,2578
-audiolibrarian-0.17.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-audiolibrarian-0.17.0.dist-info/entry_points.txt,sha256=reubnr_SGbTTDXji8j7z8aTmIL0AEQKVSLcnmFG3YYY,59
-audiolibrarian-0.17.0.dist-info/licenses/COPYING,sha256=WJ7YI-moTFb-uVrFjnzzhGJrnL9P2iqQe8NuED3hutI,35141
-audiolibrarian-0.17.0.dist-info/licenses/LICENSE,sha256=WJ7YI-moTFb-uVrFjnzzhGJrnL9P2iqQe8NuED3hutI,35141
-audiolibrarian-0.17.0.dist-info/RECORD,,

audiolibrarian-0.17.0.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-audiolibrarian = audiolibrarian:cli.main