matchpatch 0.4.0__py3-none-any.whl

matchpatch/__init__.py

@@ -0,0 +1,20 @@
+"""MatchPatch package."""
+
+from __future__ import annotations
+
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+def _version_from_pyproject() -> str:
+    pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    with pyproject_path.open("rb") as pyproject_file:
+        pyproject = tomllib.load(pyproject_file)
+    return str(pyproject["project"]["version"])
+
+
+try:
+    __version__ = version("matchpatch")
+except PackageNotFoundError:  # pragma: no cover - fallback for direct source execution
+    __version__ = _version_from_pyproject()

matchpatch/analysis.py

@@ -0,0 +1,97 @@
+"""Audio measurements compatible with the historical MatchPatch CSV format."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pyloudnorm as pyln
+
+MINIMUM_LUFS_WINDOW_SECONDS = 0.4
+
+
+@dataclass(frozen=True)
+class AudioMeasurements:
+    short_term_lufs: float
+    crest_factor_db: float
+
+
+@dataclass(frozen=True)
+class AnalysisOptions:
+    window_seconds: float = 3.0
+    interval_seconds: float = 0.1
+    minimum_valid_lufs: float = -100.0
+
+
+def _as_float_audio(audio: np.ndarray) -> np.ndarray:
+    result = np.asarray(audio, dtype=np.float64)
+
+    if result.ndim == 1:
+        result = result[:, np.newaxis]
+
+    if result.ndim != 2 or result.shape[0] == 0:
+        raise ValueError("Audio must contain frames and one or more channels")
+
+    return result
+
+
+def calculate_average_short_term_lufs(
+    audio: np.ndarray,
+    sample_rate: int,
+    window_seconds: float = 3.0,
+    interval_seconds: float = 0.1,
+    minimum_valid_lufs: float = -100.0,
+) -> float:
+    """Average LUFS values from sliding three-second analysis windows."""
+
+    samples = _as_float_audio(audio)
+    window_frames = round(window_seconds * sample_rate)
+    interval_frames = round(interval_seconds * sample_rate)
+
+    if window_seconds < MINIMUM_LUFS_WINDOW_SECONDS:
+        raise ValueError(f"LUFS window must be at least {MINIMUM_LUFS_WINDOW_SECONDS:g} s")
+
+    if samples.shape[0] < window_frames:
+        raise ValueError(f"Audio is shorter than the {window_seconds:g} s LUFS window")
+
+    meter = pyln.Meter(sample_rate)
+    values = []
+
+    for end in range(window_frames, samples.shape[0] + 1, interval_frames):
+        value = meter.integrated_loudness(samples[end - window_frames : end])
+
+        if np.isfinite(value) and value > minimum_valid_lufs:
+            values.append(float(value))
+
+    if not values:
+        raise ValueError("Could not collect valid short-term LUFS values")
+
+    return float(np.mean(values))
+
+
+def calculate_crest_factor_db(audio: np.ndarray) -> float:
+    samples = _as_float_audio(audio)
+    peak = float(np.max(np.abs(samples)))
+    rms = float(np.sqrt(np.mean(np.square(samples))))
+
+    if peak <= 0.0 or rms <= 0.0:
+        raise ValueError("Could not calculate crest factor from silent audio")
+
+    return float(20.0 * np.log10(peak / rms))
+
+
+def analyze_audio(
+    audio: np.ndarray,
+    sample_rate: int,
+    options: AnalysisOptions = AnalysisOptions(),
+) -> AudioMeasurements:
+    return AudioMeasurements(
+        short_term_lufs=calculate_average_short_term_lufs(
+            audio,
+            sample_rate,
+            options.window_seconds,
+            options.interval_seconds,
+            options.minimum_valid_lufs,
+        ),
+        crest_factor_db=calculate_crest_factor_db(audio),
+    )

matchpatch/app.py

@@ -0,0 +1,71 @@
+"""Unified MatchPatch application entry point."""
+
+from __future__ import annotations
+
+import sys
+
+CLI_SWITCHES = {"--cli", "/cli"}
+ATTACH_PARENT_PROCESS = 0xFFFFFFFF
+
+
+def _stream_is_usable(stream: object) -> bool:
+    write = getattr(stream, "write", None)
+    flush = getattr(stream, "flush", None)
+    if write is None or flush is None:
+        return False
+    try:
+        write("")
+        flush()
+    except (AttributeError, OSError, ValueError):
+        return False
+    return True
+
+
+def _attach_parent_console() -> bool:
+    if sys.platform != "win32":
+        return False
+
+    try:
+        import ctypes
+
+        kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        attach_console = kernel32.AttachConsole
+        attach_console.argtypes = [ctypes.c_uint32]
+        attach_console.restype = ctypes.c_int
+        attached = attach_console(ATTACH_PARENT_PROCESS) != 0
+        already_attached = ctypes.get_last_error() == 5
+        if not attached and not already_attached:
+            return False
+        sys.stdout = open("CONOUT$", "w", encoding="utf-8", buffering=1)
+        sys.stderr = open("CONOUT$", "w", encoding="utf-8", buffering=1)
+    except (AttributeError, OSError, ValueError):
+        return False
+    return True
+
+
+def _prepare_cli_stdout() -> bool:
+    if _stream_is_usable(sys.stdout):
+        return True
+    if _attach_parent_console():
+        return _stream_is_usable(sys.stdout)
+    return False
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if args and args[0].lower() in CLI_SWITCHES:
+        if args[1:] == ["--version"] and not _prepare_cli_stdout():
+            return
+
+        from matchpatch.cli import main as cli_main
+
+        cli_main(args[1:])
+        return
+
+    from matchpatch.gui.app import main as gui_main
+
+    gui_main(args)
+
+
+if __name__ == "__main__":  # pragma: no cover - frozen executable entry point
+    main()

matchpatch/audio.py

@@ -0,0 +1,148 @@
+"""Native Windows duplex audio support shared by hardware profiles."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, replace
+from typing import Any
+
+import numpy as np
+
+os.environ.setdefault("SD_ENABLE_ASIO", "1")
+
+import sounddevice as sd  # noqa: E402
+
+
+@dataclass(frozen=True)
+class AudioConfig:
+    device: str | int | None
+    sample_rate: int
+    input_mapping: tuple[int, int]
+    output_mapping: tuple[int, int]
+    blocksize: int = 0
+    pre_roll_seconds: float = 0.2
+    post_roll_seconds: float = 0.1
+    round_trip_latency_seconds: float = 0.02
+
+
+def _matches_device(device: dict[str, Any], query: str) -> bool:
+    return query.casefold() in str(device["name"]).casefold()
+
+
+def resolve_audio_device(query: str | int | None) -> int | None:
+    if query is None:
+        return None
+
+    if isinstance(query, int) or str(query).isdigit():
+        return int(query)
+
+    devices = sd.query_devices()
+    matches = [index for index, device in enumerate(devices) if _matches_device(device, str(query))]
+
+    if not matches:
+        raise ValueError(f"No audio device matched {query!r}")
+
+    asio_matches = [
+        index
+        for index in matches
+        if "asio" in sd.query_hostapis(devices[index]["hostapi"])["name"].lower()
+    ]
+
+    if len(asio_matches) == 1:
+        return asio_matches[0]
+
+    if len(matches) == 1:
+        return matches[0]
+
+    raise ValueError(f"Audio device query {query!r} is ambiguous; use a numeric device ID")
+
+
+def prepare_audio_config(config: AudioConfig) -> AudioConfig:
+    """Resolve and validate audio settings once before recording starts."""
+    device = resolve_audio_device(config.device)
+    sd.check_input_settings(
+        device=device,
+        channels=len(config.input_mapping),
+        dtype="float32",
+        samplerate=config.sample_rate,
+    )
+    sd.check_output_settings(
+        device=device,
+        channels=len(config.output_mapping),
+        dtype="float32",
+        samplerate=config.sample_rate,
+    )
+    return replace(config, device=device)
+
+
+def validate_audio_device_available(config: AudioConfig) -> AudioConfig:
+    """Quickly validate that a matching audio device with enough channels is present."""
+    device = resolve_audio_device(config.device)
+    if device is None:
+        return replace(config, device=device)
+
+    device_info = sd.query_devices(device)
+    input_channels = int(device_info.get("max_input_channels", 0))
+    output_channels = int(device_info.get("max_output_channels", 0))
+
+    if input_channels < max(config.input_mapping):
+        raise ValueError(
+            f"Audio device {device_info['name']!r} has {input_channels} input channels; "
+            f"need channel {max(config.input_mapping)}"
+        )
+
+    if output_channels < max(config.output_mapping):
+        raise ValueError(
+            f"Audio device {device_info['name']!r} has {output_channels} output channels; "
+            f"need channel {max(config.output_mapping)}"
+        )
+
+    return replace(config, device=device)
+
+
+def record_processed_audio(
+    reference_audio: np.ndarray,
+    config: AudioConfig,
+) -> np.ndarray:
+    device = resolve_audio_device(config.device)
+    pre_roll_frames = round(config.pre_roll_seconds * config.sample_rate)
+    post_roll_frames = round(config.post_roll_seconds * config.sample_rate)
+    latency_frames = round(config.round_trip_latency_seconds * config.sample_rate)
+
+    if min(pre_roll_frames, post_roll_frames, latency_frames) < 0:
+        raise ValueError("Audio pre-roll, post-roll, and round-trip latency must not be negative")
+
+    if latency_frames > post_roll_frames:
+        raise ValueError("Audio post-roll must be at least as long as round-trip latency")
+
+    reference = np.asarray(reference_audio)
+
+    if reference.ndim != 2 or reference.shape[0] == 0:
+        raise ValueError("Reference audio must contain frames and one or more channels")
+
+    silence_shape = (pre_roll_frames + post_roll_frames, reference.shape[1])
+    silence = np.zeros(silence_shape, dtype=reference.dtype)
+    playback = np.concatenate(
+        [silence[:pre_roll_frames], reference, silence[pre_roll_frames:]],
+        axis=0,
+    )
+
+    recorded = sd.playrec(
+        playback,
+        samplerate=config.sample_rate,
+        channels=len(config.input_mapping),
+        dtype="float32",
+        input_mapping=list(config.input_mapping),
+        output_mapping=list(config.output_mapping),
+        blocking=True,
+        device=(device, device),
+        blocksize=config.blocksize,
+    )
+    aligned_start = pre_roll_frames + latency_frames
+    aligned_end = aligned_start + reference.shape[0]
+    return recorded[aligned_start:aligned_end]
+
+
+def play_audio(audio: np.ndarray, sample_rate: int) -> None:
+    """Play audio through the system default output device."""
+    sd.play(np.asarray(audio), samplerate=sample_rate, blocking=True)

matchpatch/cli.py

@@ -0,0 +1,70 @@
+"""Command-line entry point for MatchPatch."""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import sys
+
+from matchpatch import __version__
+from matchpatch.config import export_default_config
+from matchpatch.devices import list_device_profiles
+
+
+def print_environment() -> None:
+    print(f"MatchPatch {__version__}")
+    print(f"Platform: {platform.platform()}")
+    print(f"Python  : {sys.executable}")
+
+
+def print_devices() -> None:
+    for profile in list_device_profiles():
+        print(f"{profile.name}\t{profile.display_name}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if args and args[0] == "normalize":
+        from matchpatch.normalize import main as normalize_main
+
+        normalize_main(args[1:])
+        return
+
+    parser = argparse.ArgumentParser(description="Normalize gain across audio processor presets")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "--environment",
+        action="store_true",
+        help="Print the Python environment used for this invocation",
+    )
+    parser.add_argument(
+        "--devices",
+        action="store_true",
+        help="List supported audio processor profiles",
+    )
+    parser.add_argument(
+        "--export-default-config",
+        metavar="PATH",
+        help="Write a TOML configuration file populated with MatchPatch defaults",
+    )
+    args = parser.parse_args(args)
+
+    if args.export_default_config:
+        path = export_default_config(args.export_default_config)
+        print(f"Wrote default config: {path}")
+    elif args.environment:
+        print_environment()
+    elif args.devices:
+        print_devices()
+    else:
+        parser.print_help()
+        print("\nNormalization command:")
+        print("  matchpatch normalize --device DEVICE --input PATCH_FILE [options]")
+
+
+if __name__ == "__main__":  # pragma: no cover - console script entry point
+    main()

matchpatch/config.py

@@ -0,0 +1,181 @@
+"""TOML configuration helpers shared by MatchPatch entry points."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from matchpatch.devices import list_device_profiles
+from matchpatch.devices.base import NormalizationPolicy
+
+Config = dict[str, Any]
+
+
+def default_config_path() -> Path:
+    return Path.home() / ".config" / "matchpatch" / "config.toml"
+
+
+def load_config(path: str | Path | None) -> Config:
+    config_path = Path(path).expanduser() if path is not None else default_config_path()
+
+    if not config_path.is_file():
+        if path is None:
+            return {}
+
+        raise ValueError(f"MatchPatch config file does not exist: {config_path}")
+
+    with config_path.open("rb") as config_file:
+        return tomllib.load(config_file)
+
+
+def config_value(config: Config, *keys: str, default: Any = None) -> Any:  # noqa: ANN401
+    value: Any = config
+
+    for key in keys:
+        if not isinstance(value, dict):
+            return default
+
+        value = value.get(key, default)
+
+    return value
+
+
+def prefer(cli_value: object, config: Config, *keys: str, default: object = None) -> object:
+    if cli_value is not None:
+        return cli_value
+
+    return config_value(config, *keys, default=default)
+
+
+def parse_channel_mapping(value: object) -> tuple[int, int]:
+    if isinstance(value, str):
+        channels = tuple(int(item.strip()) for item in value.split(",") if item.strip())
+    elif isinstance(value, (list, tuple)):
+        channels = tuple(value)
+    else:
+        raise ValueError("Channel mapping must contain two positive IDs")
+
+    if len(channels) != 2 or any(
+        not isinstance(channel, int) or channel < 1 for channel in channels
+    ):
+        raise ValueError("Channel mapping must contain two positive IDs")
+
+    first, second = channels
+    assert isinstance(first, int) and isinstance(second, int)
+    return first, second
+
+
+def default_config() -> Config:
+    from matchpatch.normalize import DEFAULT_REFERENCE_DI, DEFAULT_WINDOWS_PYTHON
+
+    policy = NormalizationPolicy()
+    config: Config = {
+        "normalize": {
+            "backend": "hardware",
+            "windows_python": str(DEFAULT_WINDOWS_PYTHON),
+            "reference_di": str(DEFAULT_REFERENCE_DI),
+            "target_lufs": -16.0,
+        },
+        "analysis": {
+            "window_seconds": 3.0,
+            "interval_seconds": 0.1,
+            "minimum_valid_lufs": -100.0,
+            "pre_roll_seconds": 0.2,
+            "post_roll_seconds": 0.1,
+            "round_trip_latency_seconds": 0.02,
+        },
+        "measurement": {
+            "stability_runs": 3,
+            "termination_tolerance_percent": 10.0,
+            "stability_tolerance_percent": 2.0,
+        },
+        "policy": {
+            "measured_snapshots": policy.snapshot_count,
+            "solo_regex": policy.solo_regex,
+            "ignore_snapshot_regex": policy.ignore_snapshot_regex,
+            "solo_gain_bump_db": policy.solo_gain_bump_db,
+            "crest_factor_reference_db": policy.crest_factor_reference_db,
+            "crest_factor_correction_ratio": policy.crest_factor_correction_ratio,
+            "max_crest_factor_correction_db": policy.max_crest_factor_correction_db,
+            "gain_deadband_db": policy.gain_deadband_db,
+        },
+        "devices": {},
+    }
+
+    devices = config["devices"]
+    assert isinstance(devices, dict)
+    for profile in list_device_profiles():
+        audio = profile.default_audio_routing()
+        steering = profile.default_steering_options()
+        devices[profile.name] = {
+            "audio": {
+                "device": audio.device,
+                "sample_rate": audio.sample_rate,
+                "input_mapping": list(audio.input_mapping),
+                "output_mapping": list(audio.output_mapping),
+                "blocksize": 0,
+            },
+            "steering": {
+                "output": steering.output,
+                "channel": steering.channel,
+                "preset_wait_seconds": steering.preset_wait_seconds,
+                "snapshot_wait_seconds": steering.snapshot_wait_seconds,
+                "measurement_wait_seconds": steering.measurement_wait_seconds,
+            },
+        }
+
+    return config
+
+
+def export_default_config(path: str | Path) -> Path:
+    return export_config(path, default_config())
+
+
+def export_config(path: str | Path, config: Config) -> Path:
+    config_path = Path(path).expanduser()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(_toml_document(config), encoding="utf-8")
+    return config_path
+
+
+def _toml_document(config: Config) -> str:
+    lines: list[str] = []
+
+    for key, value in config.items():
+        if not isinstance(value, dict):
+            continue
+        _append_toml_table(lines, (key,), value)
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _append_toml_table(lines: list[str], path: tuple[str, ...], table: dict[str, Any]) -> None:
+    scalar_items = [
+        (key, value)
+        for key, value in table.items()
+        if value is not None and not isinstance(value, dict)
+    ]
+    nested_items = [(key, value) for key, value in table.items() if isinstance(value, dict)]
+
+    if scalar_items:
+        if lines:
+            lines.append("")
+        lines.append(f"[{'.'.join(path)}]")
+        for key, value in scalar_items:
+            lines.append(f"{key} = {_toml_value(value)}")
+
+    for key, value in nested_items:
+        _append_toml_table(lines, (*path, key), value)
+
+
+def _toml_value(value: object) -> str:
+    if isinstance(value, str):
+        return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_toml_value(item) for item in value) + "]"
+    raise TypeError(f"Unsupported default config value: {value!r}")

matchpatch/custom_adjustments.py

@@ -0,0 +1,60 @@
+"""Custom per-preset snapshot loudness target bumps."""
+
+from __future__ import annotations
+
+import csv
+import math
+from pathlib import Path
+
+CustomAdjustments = dict[str, dict[int, float]]
+
+
+def load_custom_adjustments_file(path: Path, snapshot_count: int) -> CustomAdjustments:
+    """Load custom dB target bumps from a preset/snapshot CSV."""
+    adjustments: CustomAdjustments = {}
+    expected_columns = snapshot_count + 1
+
+    with path.open("r", encoding="utf-8-sig", newline="") as csv_file:
+        sample = csv_file.read(4096)
+        csv_file.seek(0)
+        try:
+            dialect = csv.Sniffer().sniff(sample, delimiters=",|")
+        except csv.Error:
+            dialect = csv.excel
+        reader = csv.reader(csv_file, dialect)
+        for line_number, row in enumerate(reader, start=1):
+            if not row or all(not cell.strip() for cell in row):
+                continue
+            if len(row) != expected_columns:
+                raise ValueError(
+                    f"Line {line_number}: expected {expected_columns} columns, got {len(row)}"
+                )
+
+            preset_id = row[0].strip().upper()
+            if not preset_id:
+                raise ValueError(f"Line {line_number}: preset ID is empty")
+            if preset_id in adjustments:
+                raise ValueError(f"Line {line_number}: duplicate preset ID {preset_id!r}")
+
+            preset_adjustments: dict[int, float] = {}
+            for snapshot_index, cell in enumerate(row[1:]):
+                text = cell.strip()
+                if not text:
+                    continue
+                try:
+                    value = float(text)
+                except ValueError as exc:
+                    raise ValueError(
+                        f"Line {line_number}: snapshot {snapshot_index + 1} "
+                        f"custom adjustment is not a floating point number: {text!r}"
+                    ) from exc
+                if not math.isfinite(value):
+                    raise ValueError(
+                        f"Line {line_number}: snapshot {snapshot_index + 1} "
+                        f"custom adjustment is not finite: {text!r}"
+                    )
+                preset_adjustments[snapshot_index] = value
+
+            adjustments[preset_id] = preset_adjustments
+
+    return adjustments

matchpatch/devices/__init__.py

@@ -0,0 +1,5 @@
+"""Audio processor profiles supported by MatchPatch."""
+
+from matchpatch.devices.registry import get_device_profile, list_device_profiles
+
+__all__ = ["get_device_profile", "list_device_profiles"]