matchpatch 0.4.0__py3-none-any.whl

matchpatch/devices/base.py

@@ -0,0 +1,204 @@
+"""Interfaces implemented by each supported audio processor."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from types import TracebackType
+from typing import Self
+
+
+@dataclass(frozen=True)
+class PatchAssignment:
+    id: int
+    device_patch: str
+    name: str
+    snapshot_names: tuple[str, ...] = ()
+    snapshot_output_levels: tuple[tuple[float, ...], ...] = ()
+    snapshot_output_paths: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class PatchFileAdjustments:
+    preset_names: dict[str, str]
+    snapshot_names: dict[str, dict[int, str]]
+    gain_deltas: dict[str, dict[int, float]]
+
+
+@dataclass(frozen=True)
+class AudioRouting:
+    device: str | int | None
+    sample_rate: int
+    input_mapping: tuple[int, int]
+    output_mapping: tuple[int, int]
+
+
+@dataclass(frozen=True)
+class SteeringOptions:
+    output: str | None
+    channel: int
+    preset_wait_seconds: float
+    snapshot_wait_seconds: float
+    measurement_wait_seconds: float
+
+
+@dataclass(frozen=True)
+class NormalizationPolicy:
+    snapshot_count: int = 4
+    solo_regex: str = r"(?i)\bsolo\b"
+    ignore_snapshot_regex: str = r"(?i)^SNAPSHOT [1-9]\d*$"
+    solo_gain_bump_db: float = 3.0
+    crest_factor_reference_db: float = 12.0
+    crest_factor_correction_ratio: float = 0.4
+    max_crest_factor_correction_db: float = 3.0
+    gain_deadband_db: float = 0.25
+
+
+def normalize_regex_pattern(pattern: str) -> str:
+    r"""Preserve user-visible ``\b`` word-boundary escapes decoded by config/UI paths."""
+    return pattern.replace("\b", r"\b")
+
+
+class DeviceController(ABC):
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        return None
+
+    @abstractmethod
+    def activate_preset(self, preset_id: int) -> None:
+        """Select a processor preset by its internal numeric ID."""
+
+    @abstractmethod
+    def reapply_snapshot(self, snapshot: int) -> None:
+        """Select a processor snapshot by its one-based numeric ID."""
+
+
+class PatchFileHandler(ABC):
+    def set_log_callback(self, callback: Callable[[str], None] | None) -> None:
+        """Receive device-specific utility output when a front end wants it."""
+        return None
+
+    @abstractmethod
+    def validate_input(self, input_path: Path) -> None:
+        """Validate an input setlist or preset file."""
+
+    @abstractmethod
+    def validate_output(self, input_path: Path, output_path: Path) -> None:
+        """Validate the requested output filename."""
+
+    @abstractmethod
+    def list_assignments(self, input_path: Path) -> list[PatchAssignment]:
+        """List measurable presets contained in a patch file."""
+
+    def metadata(self, input_path: Path) -> dict[str, object]:
+        """Extract displayable metadata from a patch file."""
+        return {}
+
+    def diff_preset_ids(self, input_path: Path, previous_input_path: Path) -> list[int]:
+        """List presets whose loudness-affecting content differs between two patch files."""
+        raise NotImplementedError("Preset diff selection is not supported for this device")
+
+    def diff_snapshot_ids(
+        self,
+        input_path: Path,
+        previous_input_path: Path,
+        snapshot_count: int,
+    ) -> dict[int, tuple[int, ...]]:
+        """List changed one-based snapshots per changed preset."""
+        return {
+            preset_id: tuple(range(1, snapshot_count + 1))
+            for preset_id in self.diff_preset_ids(input_path, previous_input_path)
+        }
+
+    @abstractmethod
+    def parse_patch_set(self, value: str) -> list[int]:
+        """Parse device-facing preset labels into numeric preset IDs."""
+
+    @abstractmethod
+    def select_preset_ids(
+        self,
+        input_path: Path,
+        assignments: list[PatchAssignment],
+        requested_ids: list[int] | None,
+    ) -> list[int]:
+        """Resolve the presets that should be measured."""
+
+    @abstractmethod
+    def format_patch_id(self, preset_id: int) -> str:
+        """Format a numeric preset ID for logs and CSV output."""
+
+    @abstractmethod
+    def create_measurement_file(self, input_path: Path, output_path: Path) -> None:
+        """Rewrite a patch file for processor USB measurement."""
+
+    @abstractmethod
+    def apply_analysis_csv(
+        self,
+        input_path: Path,
+        output_path: Path,
+        csv_path: Path,
+        ignore_bad_lufs: bool,
+        target_lufs: float,
+        policy: NormalizationPolicy,
+        custom_adjustments_path: Path | None = None,
+        adjustments: PatchFileAdjustments | None = None,
+    ) -> None:
+        """Apply measured gain adjustments to a patch file."""
+
+    @abstractmethod
+    def automation_output_path(self, input_path: Path, postfix: str) -> Path:
+        """Build a device-compatible output path beside the input file."""
+
+
+class DeviceProfile(ABC):
+    name: str
+    display_name: str
+    snapshot_count: int = 4
+    max_snapshot_count: int | None = None
+    preset_name_max_length: int | None = None
+    snapshot_name_max_length: int | None = None
+
+    @abstractmethod
+    def create_patch_file_handler(self, project_dir: Path) -> PatchFileHandler:
+        """Create the device-specific patch-file adapter."""
+
+    def format_patch_id(self, preset_id: int) -> str:
+        """Format a numeric preset ID for device-facing status text."""
+        return str(preset_id)
+
+    @abstractmethod
+    def default_audio_routing(self) -> AudioRouting:
+        """Return the processor's USB measurement channel defaults."""
+
+    @abstractmethod
+    def default_steering_options(self) -> SteeringOptions:
+        """Return the processor's steering defaults."""
+
+    @abstractmethod
+    def create_controller(self, options: SteeringOptions) -> DeviceController:
+        """Open the transport used to select presets and snapshots."""
+
+
+def validate_snapshot_count(profile: DeviceProfile, snapshot_count: int) -> None:
+    if not isinstance(snapshot_count, int) or isinstance(snapshot_count, bool):
+        raise ValueError("Configured measured snapshot count must be an integer")
+
+    if snapshot_count < 1:
+        raise ValueError("Configured measured snapshot count must be at least 1")
+
+    max_snapshot_count = getattr(profile, "max_snapshot_count", None)
+
+    if max_snapshot_count is not None and snapshot_count > max_snapshot_count:
+        raise ValueError(
+            f"Configured measured snapshot count for {profile.display_name} "
+            f"must not exceed {max_snapshot_count}"
+        )

matchpatch/devices/helix.py

@@ -0,0 +1,447 @@
+"""Line 6 Helix profile: patch files, MIDI steering, and USB routing."""
+
+from __future__ import annotations
+
+import csv
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from collections.abc import Callable
+from pathlib import Path
+from types import TracebackType
+
+from matchpatch.devices.base import (
+    AudioRouting,
+    DeviceController,
+    DeviceProfile,
+    NormalizationPolicy,
+    PatchAssignment,
+    PatchFileAdjustments,
+    PatchFileHandler,
+    SteeringOptions,
+)
+
+
+class HelixPatchFileHandler(PatchFileHandler):
+    def __init__(self, project_dir: Path) -> None:
+        self.script = project_dir / "Python" / "preset_handling.py"
+        self.log_callback: Callable[[str], None] | None = None
+
+    def set_log_callback(self, callback: Callable[[str], None] | None) -> None:
+        self.log_callback = callback
+
+    def _run(
+        self,
+        *args: object,
+        capture: bool = False,
+        log_output: bool = True,
+    ) -> subprocess.CompletedProcess[str]:
+        should_capture = capture or self.log_callback is not None
+
+        try:
+            completed = subprocess.run(
+                [sys.executable, str(self.script), *(str(arg) for arg in args)],
+                check=True,
+                text=True,
+                stdout=subprocess.PIPE if should_capture else None,
+                stderr=subprocess.PIPE if should_capture else None,
+            )
+        except subprocess.CalledProcessError as exc:
+            if log_output:
+                self._log_output(exc.stdout)
+                self._log_output(exc.stderr)
+            raise
+
+        if log_output:
+            self._log_output(completed.stdout)
+            self._log_output(completed.stderr)
+        return completed
+
+    def _log_output(self, output: str | None) -> None:
+        if self.log_callback is None or not output:
+            return
+
+        for line in output.splitlines():
+            if line.strip():
+                self.log_callback(line)
+
+    def validate_input(self, input_path: Path) -> None:
+        if input_path.suffix.lower() not in {".hls", ".hlx"}:
+            raise ValueError("Helix input must be an .hls or .hlx file")
+
+    def validate_output(self, input_path: Path, output_path: Path) -> None:
+        if output_path.suffix.lower() != input_path.suffix.lower():
+            raise ValueError(f"Helix output must use the {input_path.suffix.lower()} extension")
+
+    def list_assignments(self, input_path: Path) -> list[PatchAssignment]:
+        completed = self._run("-i", input_path, "--list-presets", capture=True, log_output=False)
+        return [
+            PatchAssignment(
+                id=assignment["id"],
+                device_patch=assignment["helix_preset"],
+                name=assignment["name"],
+                snapshot_names=tuple(assignment.get("snapshot_names", ())),
+                snapshot_output_paths=tuple(
+                    str(path) for path in assignment.get("snapshot_output_paths", ())
+                ),
+                snapshot_output_levels=tuple(
+                    tuple(float(level) for level in levels)
+                    for levels in assignment.get("snapshot_output_levels", ())
+                ),
+            )
+            for assignment in json.loads(completed.stdout)
+        ]
+
+    def metadata(self, input_path: Path) -> dict[str, object]:
+        completed = self._run("-i", input_path, "--metadata", capture=True, log_output=False)
+        metadata = json.loads(completed.stdout)
+        if not isinstance(metadata, dict):
+            raise ValueError("Helix metadata output must be a JSON object")
+        return metadata
+
+    def diff_preset_ids(self, input_path: Path, previous_input_path: Path) -> list[int]:
+        if previous_input_path.suffix.lower() != input_path.suffix.lower():
+            raise ValueError(
+                "Helix diff input must use the same extension as the active input file"
+            )
+
+        completed = self._run(
+            "-i",
+            input_path,
+            "--diff-presets",
+            previous_input_path,
+            capture=True,
+            log_output=False,
+        )
+        diff_ids = json.loads(completed.stdout)
+        if not isinstance(diff_ids, list) or not all(isinstance(item, int) for item in diff_ids):
+            raise ValueError("Helix diff output must be a JSON array of preset IDs")
+        return diff_ids
+
+    def diff_snapshot_ids(
+        self,
+        input_path: Path,
+        previous_input_path: Path,
+        snapshot_count: int,
+    ) -> dict[int, tuple[int, ...]]:
+        if previous_input_path.suffix.lower() != input_path.suffix.lower():
+            raise ValueError(
+                "Helix diff input must use the same extension as the active input file"
+            )
+
+        completed = self._run(
+            "-i",
+            input_path,
+            "--diff-snapshots",
+            previous_input_path,
+            "--snapshot-count",
+            snapshot_count,
+            capture=True,
+            log_output=False,
+        )
+        raw_plan = json.loads(completed.stdout)
+        if not isinstance(raw_plan, dict):
+            raise ValueError("Helix snapshot diff output must be a JSON object")
+        result: dict[int, tuple[int, ...]] = {}
+        for preset_id, snapshots in raw_plan.items():
+            if not str(preset_id).isdigit() or not isinstance(snapshots, list):
+                raise ValueError("Helix snapshot diff output has an invalid preset entry")
+            if not all(isinstance(snapshot, int) for snapshot in snapshots):
+                raise ValueError("Helix snapshot diff output has an invalid snapshot list")
+            result[int(preset_id)] = tuple(snapshots)
+        return result
+
+    def parse_patch_set(self, value: str) -> list[int]:
+        preset_ids = []
+
+        for token in value.split(","):
+            text = token.strip().upper()
+
+            if len(text) < 2 or not text[:-1].isdigit() or text[-1] not in "ABCD":
+                raise ValueError(f"Invalid Helix preset ID: {token}")
+
+            bank = int(text[:-1])
+
+            if bank < 1:
+                raise ValueError(f"Invalid Helix preset ID: {token}")
+
+            preset_id = (bank - 1) * 4 + "ABCD".index(text[-1]) + 1
+
+            if preset_id not in preset_ids:
+                preset_ids.append(preset_id)
+
+        if not preset_ids:  # pragma: no cover - guarded by token validation
+            raise ValueError("Preset set did not contain Helix presets")
+
+        return preset_ids
+
+    def select_preset_ids(
+        self,
+        input_path: Path,
+        assignments: list[PatchAssignment],
+        requested_ids: list[int] | None,
+    ) -> list[int]:
+        if input_path.suffix.lower() == ".hlx":
+            if requested_ids is None or len(requested_ids) != 1:
+                raise ValueError(
+                    "Helix .hlx input requires exactly one --preset-set value, "
+                    "for example --preset-set 12A"
+                )
+
+            return requested_ids
+
+        available_ids = {assignment.id for assignment in assignments}
+
+        if requested_ids is None:
+            return [assignment.id for assignment in assignments]
+
+        missing_ids = [preset_id for preset_id in requested_ids if preset_id not in available_ids]
+
+        if missing_ids:
+            missing = ",".join(self.format_patch_id(preset_id) for preset_id in missing_ids)
+            raise ValueError(f"Requested Helix presets are missing or empty: {missing}")
+
+        requested = set(requested_ids)
+        return [assignment.id for assignment in assignments if assignment.id in requested]
+
+    def format_patch_id(self, preset_id: int) -> str:
+        zero_based = preset_id - 1
+        return f"{zero_based // 4 + 1:02d}{'ABCD'[zero_based % 4]}"
+
+    def create_measurement_file(self, input_path: Path, output_path: Path) -> None:
+        self._run("-i", input_path, "-o", output_path, "--measurement")
+
+    def apply_analysis_csv(
+        self,
+        input_path: Path,
+        output_path: Path,
+        csv_path: Path,
+        ignore_bad_lufs: bool,
+        target_lufs: float,
+        policy: NormalizationPolicy = NormalizationPolicy(),
+        custom_adjustments_path: Path | None = None,
+        adjustments: PatchFileAdjustments | None = None,
+    ) -> None:
+        legacy_csv_path = self._create_legacy_analysis_csv(csv_path)
+        adjustments_path = None
+
+        try:
+            adjustments_path = self._create_adjustments_json(csv_path, adjustments)
+            args: list[object] = [
+                "-i",
+                input_path,
+                "-o",
+                output_path,
+                "--adjust-gain",
+                "-g",
+                legacy_csv_path,
+                "--target-lufs",
+                target_lufs,
+                "--snapshot-count",
+                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,
+            ]
+
+            args.append("--ignore-bad-lufs")
+            if custom_adjustments_path is not None:
+                args.extend(["--custom-adjustments-file", custom_adjustments_path])
+            if adjustments_path is not None:
+                args.extend(["--manual-adjustments", adjustments_path])
+
+            try:
+                self._run(*args, capture=True)
+            except subprocess.CalledProcessError as exc:
+                details = _error_details(exc)
+                message = "Helix gain adjustment failed"
+                if details:
+                    message += f":\n{details}"
+                raise RuntimeError(message) from exc
+        finally:
+            legacy_csv_path.unlink(missing_ok=True)
+            if adjustments_path is not None:
+                adjustments_path.unlink(missing_ok=True)
+
+    def _create_legacy_analysis_csv(self, csv_path: Path) -> Path:
+        with csv_path.open("r", encoding="utf-8-sig", newline="") as source:
+            reader = csv.DictReader(source)
+            fieldnames = [
+                "Preset",
+                "HelixPreset",
+                *(
+                    field
+                    for field in reader.fieldnames or []
+                    if field not in {"Preset", "DevicePatch", "HelixPreset"}
+                ),
+            ]
+            temporary = tempfile.NamedTemporaryFile(
+                "w",
+                encoding="utf-8",
+                newline="",
+                suffix=".helix.csv",
+                dir=csv_path.parent,
+                delete=False,
+            )
+
+            with temporary:
+                writer = csv.DictWriter(temporary, fieldnames=fieldnames)
+                writer.writeheader()
+
+                for row in reader:
+                    row["HelixPreset"] = row["DevicePatch"]
+                    writer.writerow({field: row.get(field, "") for field in fieldnames})
+
+        return Path(temporary.name)
+
+    def _create_adjustments_json(
+        self,
+        csv_path: Path,
+        adjustments: PatchFileAdjustments | None,
+    ) -> Path | None:
+        if adjustments is None:
+            return None
+
+        temporary = tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            suffix=".adjustments.json",
+            dir=csv_path.parent,
+            delete=False,
+        )
+        with temporary:
+            json.dump(
+                {
+                    "preset_names": adjustments.preset_names,
+                    "snapshot_names": adjustments.snapshot_names,
+                    "gain_deltas": adjustments.gain_deltas,
+                },
+                temporary,
+            )
+        return Path(temporary.name)
+
+    def automation_output_path(self, input_path: Path, postfix: str) -> Path:
+        self.validate_input(input_path)
+        return input_path.with_name(input_path.stem + postfix + input_path.suffix)
+
+
+class HelixMidiController(DeviceController):
+    def __init__(self, options: SteeringOptions) -> None:
+        self.options = options
+        self.port = None
+
+    def __enter__(self) -> "HelixMidiController":
+        import mido
+
+        names = mido.get_output_names()
+        query = self.options.output
+        matches = (
+            names
+            if query is None
+            else [name for name in names if query.casefold() in name.casefold()]
+        )
+
+        if len(matches) != 1:
+            raise ValueError(
+                f"Helix MIDI output query {query!r} matched {len(matches)} ports; "
+                "use --steering-output with a unique substring"
+            )
+
+        self.port = mido.open_output(matches[0])
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self.port is not None:
+            self.port.close()
+
+    def _send(self, message_type: str, **kwargs: int) -> None:
+        import mido
+
+        if self.port is None:
+            raise RuntimeError("Helix MIDI output is not open")
+
+        self.port.send(mido.Message(message_type, channel=self.options.channel, **kwargs))
+
+    def activate_preset(self, preset_id: int) -> None:
+        value = preset_id - 1
+
+        if value < 0 or value > 127:
+            raise ValueError(f"Invalid Helix preset ID: {preset_id}")
+
+        self._send("program_change", program=value)
+        time.sleep(self.options.preset_wait_seconds)
+
+    def activate_snapshot(self, snapshot: int) -> None:
+        value = snapshot - 1
+
+        if value < 0 or value > 7:
+            raise ValueError(f"Invalid Helix snapshot: {snapshot}")
+
+        self._send("control_change", control=69, value=value)
+        time.sleep(self.options.snapshot_wait_seconds)
+
+    def reapply_snapshot(self, snapshot: int) -> None:
+        self.activate_snapshot(snapshot)
+
+
+class HelixDeviceProfile(DeviceProfile):
+    name = "helix"
+    display_name = "Line 6 Helix"
+    max_snapshot_count = 8
+    preset_name_max_length = 16
+    snapshot_name_max_length = 10
+
+    def create_patch_file_handler(self, project_dir: Path) -> PatchFileHandler:
+        return HelixPatchFileHandler(project_dir)
+
+    def format_patch_id(self, preset_id: int) -> str:
+        zero_based = preset_id - 1
+        return f"{zero_based // 4 + 1:02d}{'ABCD'[zero_based % 4]}"
+
+    def default_audio_routing(self) -> AudioRouting:
+        return AudioRouting(
+            device="Helix",
+            sample_rate=48000,
+            input_mapping=(1, 2),
+            output_mapping=(3, 4),
+        )
+
+    def default_steering_options(self) -> SteeringOptions:
+        return SteeringOptions(
+            output="Helix",
+            channel=0,
+            preset_wait_seconds=0.5,
+            snapshot_wait_seconds=0.2,
+            measurement_wait_seconds=0.1,
+        )
+
+    def create_controller(self, options: SteeringOptions) -> DeviceController:
+        return HelixMidiController(options)
+
+
+def _error_details(exc: subprocess.CalledProcessError) -> str:
+    lines = (exc.stderr or "").splitlines() + (exc.stdout or "").splitlines()
+    errors = [line for line in lines if line.strip().startswith("ERROR:")]
+
+    if errors:
+        return "\n".join(errors)
+
+    return lines[-1].strip() if lines else ""

matchpatch/devices/registry.py

@@ -0,0 +1,22 @@
+"""Registry of audio processor profiles."""
+
+from __future__ import annotations
+
+from matchpatch.devices.base import DeviceProfile
+from matchpatch.devices.helix import HelixDeviceProfile
+
+_PROFILES: dict[str, DeviceProfile] = {
+    "helix": HelixDeviceProfile(),
+}
+
+
+def get_device_profile(name: str) -> DeviceProfile:
+    try:
+        return _PROFILES[name]
+    except KeyError as exc:
+        supported = ", ".join(sorted(_PROFILES))
+        raise ValueError(f"Unsupported device {name!r}; choose one of: {supported}") from exc
+
+
+def list_device_profiles() -> list[DeviceProfile]:
+    return [_PROFILES[name] for name in sorted(_PROFILES)]

matchpatch/gui/__init__.py

@@ -0,0 +1 @@
+"""PySide6 desktop interface for MatchPatch."""