matchpatch 0.4.0__tar.gz

matchpatch-0.4.0/.gitattributes

@@ -0,0 +1,18 @@
+# Text files
+* text=auto eol=lf
+
+# Windows scripts
+*.cmd eol=crlf
+*.bat eol=crlf
+
+# Shell scripts
+*.sh eol=lf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.wav binary
+*.hlx binary
+*.hls binary

matchpatch-0.4.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"

matchpatch-0.4.0/.github/workflows/quality.yml

@@ -0,0 +1,134 @@
+name: Quality
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Docs / Python 3.12
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Synchronize docs environment
+        run: uv sync --locked --no-default-groups --group docs
+
+      - name: Build docs
+        run: uv run --frozen --no-default-groups --group docs sphinx-build -W --keep-going -b html docs docs_html
+
+  native:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: ${{ runner.os != 'Windows' }}
+          python-version: ${{ matrix.python-version }}
+
+      - name: Synchronize environment
+        run: uv sync --locked --no-default-groups --group wsl --extra gui
+
+      - name: Install Qt runtime libraries
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libegl1
+
+      - name: Ruff lint
+        run: uv run --frozen --no-default-groups --group wsl --extra gui ruff check .
+
+      - name: Ruff format check
+        run: uv run --frozen --no-default-groups --group wsl --extra gui ruff format --check .
+
+      - name: ty
+        run: uv run --frozen --no-default-groups --group wsl --extra gui ty check
+
+      - name: pytest
+        run: uv run --frozen --no-default-groups --group wsl --extra gui pytest
+
+  wsl:
+    name: WSL / Python ${{ matrix.python-version }}
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install Ubuntu on WSL
+        uses: Vampire/setup-wsl@v7
+        with:
+          distribution: Ubuntu-24.04
+          additional-packages: curl ca-certificates
+
+      - name: Run quality checks in WSL
+        shell: wsl-bash {0}
+        run: |
+          cd "$(wslpath '${{ github.workspace }}')"
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          export PATH="$HOME/.local/bin:$PATH"
+          export UV_PYTHON="${{ matrix.python-version }}"
+          uv python install "$UV_PYTHON"
+          uv sync --locked --no-default-groups --group wsl --extra gui
+          uv run --frozen --no-default-groups --group wsl --extra gui ruff check .
+          uv run --frozen --no-default-groups --group wsl --extra gui ruff format --check .
+          uv run --frozen --no-default-groups --group wsl --extra gui ty check
+          uv run --frozen --no-default-groups --group wsl --extra gui pytest
+
+  installer:
+    name: Windows installer smoke
+    runs-on: windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install Inno Setup
+        run: choco install innosetup --no-progress -y
+
+      - name: Build and test installer
+        shell: cmd
+        run: scripts\test-windows-installer.cmd
+
+      - name: Upload installer artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: matchpatch-installer-smoke
+          path: dist/installer/*.exe
+          if-no-files-found: error

matchpatch-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,128 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/matchpatch
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Verify tag matches package version
+        shell: bash
+        run: |
+          package_version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "${GITHUB_REF_NAME}" = "v${package_version}"
+
+      - name: Build distributions
+        run: uv build --no-sources
+
+      - name: Smoke test wheel
+        shell: bash
+        run: uv run --isolated --no-project --with dist/*.whl python -c "import matchpatch"
+
+      - name: Smoke test source distribution
+        shell: bash
+        run: uv run --isolated --no-project --with dist/*.tar.gz python -c "import matchpatch"
+
+      - name: Synchronize docs environment
+        run: uv sync --locked --no-default-groups --group docs
+
+      - name: Build offline docs
+        run: uv run --frozen --no-default-groups --group docs sphinx-build -W --keep-going -b html docs docs_html
+
+      - name: Stage installer docs payload
+        shell: bash
+        run: |
+          mkdir -p installer-payload/docs_html
+          cp -a docs_html/. installer-payload/docs_html/
+          test -f installer-payload/docs_html/index.html
+
+      - name: Upload installer docs payload
+        uses: actions/upload-artifact@v4
+        with:
+          name: matchpatch-docs-html-${{ github.ref_name }}
+          path: installer-payload/
+          if-no-files-found: error
+
+      - name: Publish distributions
+        run: uv publish
+
+  windows-installer:
+    name: Windows installer
+    runs-on: windows-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Resolve package version
+        id: version
+        shell: pwsh
+        run: |
+          $version = python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])"
+          if ($env:GITHUB_REF_NAME -ne "v$version") {
+            throw "Release tag '$env:GITHUB_REF_NAME' does not match package version 'v$version'."
+          }
+          "version=$version" >> $env:GITHUB_OUTPUT
+          "installer=dist/installer/MatchPatch-Setup-$version.exe" >> $env:GITHUB_OUTPUT
+
+      - name: Install Inno Setup
+        run: choco install innosetup --no-progress -y
+
+      - name: Build and test installer
+        shell: cmd
+        run: scripts\test-windows-installer.cmd
+
+      - name: Upload installer artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: matchpatch-installer-${{ github.ref_name }}
+          path: ${{ steps.version.outputs.installer }}
+          if-no-files-found: error
+
+      - name: Attach installer to GitHub Release
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          $tag = $env:GITHUB_REF_NAME
+          $installer = "${{ steps.version.outputs.installer }}"
+          if (-not (Test-Path -LiteralPath $installer)) {
+            throw "Installer artifact was not found: $installer"
+          }
+          gh release view $tag 2>$null
+          if ($LASTEXITCODE -ne 0) {
+            gh release create $tag --title $tag --notes "MatchPatch $tag"
+            if ($LASTEXITCODE -ne 0) {
+              throw "Failed to create GitHub Release for $tag."
+            }
+          }
+          gh release upload $tag $installer --clobber

matchpatch-0.4.0/.gitignore

@@ -0,0 +1,20 @@
+Attic
+Backups
+Media
+Unused
+__pycache__
+.venv
+.venv-wsl
+.venv-windows
+.coverage
+htmlcov
+/docs_html/
+/dist/
+/build/
+/plans/
+/installer-payload/
+*.spec.bak
+*.json
+*.hls
+*.hlx
+matchpatch_normalization_*

matchpatch-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,66 @@
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+  - pre-push
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        exclude: ^(audio/reference-di/|doc/assets/matchmatch-logo\.png$)
+
+  - repo: local
+    hooks:
+      - id: conventional-commit
+        name: Conventional commit message
+        entry: python scripts/check_commit_msg.py
+        language: python
+        stages:
+          - commit-msg
+
+      - id: ruff-lint
+        name: Ruff lint
+        entry: >-
+          bash -c 'export UV_PROJECT_ENVIRONMENT="${XDG_DATA_HOME:-$HOME/.local/share}/matchpatch/.venv-wsl";
+          python3 scripts/run_hook_with_hint.py
+          --hint "UV_PROJECT_ENVIRONMENT=\"\${XDG_DATA_HOME:-\$HOME/.local/share}/matchpatch/.venv-wsl\" uv run --frozen --no-default-groups --group wsl ruff check --fix ."
+          -- uv run --frozen --no-default-groups --group wsl ruff check .'
+        language: system
+        pass_filenames: false
+
+      - id: ruff-format
+        name: Ruff format check
+        entry: >-
+          bash -c 'export UV_PROJECT_ENVIRONMENT="${XDG_DATA_HOME:-$HOME/.local/share}/matchpatch/.venv-wsl";
+          python3 scripts/run_hook_with_hint.py
+          --hint "UV_PROJECT_ENVIRONMENT=\"\${XDG_DATA_HOME:-\$HOME/.local/share}/matchpatch/.venv-wsl\" uv run --frozen --no-default-groups --group wsl ruff format ."
+          -- uv run --frozen --no-default-groups --group wsl ruff format --check .'
+        language: system
+        pass_filenames: false
+
+      - id: ty
+        name: ty
+        entry: >-
+          bash -c 'export UV_PROJECT_ENVIRONMENT="${XDG_DATA_HOME:-$HOME/.local/share}/matchpatch/.venv-wsl";
+          python3 scripts/run_hook_with_hint.py
+          --hint "UV_PROJECT_ENVIRONMENT=\"\${XDG_DATA_HOME:-\$HOME/.local/share}/matchpatch/.venv-wsl\" uv run --frozen --no-default-groups --group wsl ty check"
+          -- uv run --frozen --no-default-groups --group wsl ty check'
+        language: system
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: >-
+          bash -c 'export UV_PROJECT_ENVIRONMENT="${XDG_DATA_HOME:-$HOME/.local/share}/matchpatch/.venv-wsl";
+          python3 scripts/run_hook_with_hint.py
+          --hint "UV_PROJECT_ENVIRONMENT=\"\${XDG_DATA_HOME:-\$HOME/.local/share}/matchpatch/.venv-wsl\" uv run --frozen --no-default-groups --group wsl pytest"
+          -- uv run --frozen --no-default-groups --group wsl pytest'
+        language: system
+        pass_filenames: false
+        stages:
+          - pre-push

matchpatch-0.4.0/.python-version

@@ -0,0 +1 @@
+3.12

matchpatch-0.4.0/AGENTS.md

@@ -0,0 +1,35 @@
+# MatchPatch Agent Notes
+
+Python package in `src/matchpatch`; legacy Helix JSON/HLS utilities live in `Python/`.
+Use existing WSL env, not bare `pytest` or a stale project `.venv`:
+
+```bash
+scripts/sync-wsl.sh
+$HOME/.local/share/matchpatch/.venv-wsl/bin/pytest
+```
+
+For GUI work use:
+
+```bash
+scripts/test-gui.sh [pytest args]
+```
+
+Quality checks:
+
+```bash
+ruff check .
+ruff format --check .
+ty check
+```
+
+Run them from the synced WSL env, or via the pre-push hook. GUI tests use PySide6
+with offscreen Qt. Prefer focused tests in `tests/test_gui.py` for window/widget
+changes, and broaden only when behavior crosses workflows.
+
+MatchPatch normalizes Helix `.hls` setlists and `.hlx` presets. Core flow:
+`workflow.py` creates/uses measurement CSVs, `normalize.py` bridges WSL to the
+native Windows worker, `measure.py` records/analyzes audio, device profiles adapt
+processor files and steering. Keep new device-specific behavior behind
+`DeviceProfile`/`PatchFileHandler`/`DeviceController`. Preserve the user’s dirty
+worktree; do not revert unrelated edits. Prefer `rg`, focused patches, and tests
+that mock hardware unless the user explicitly asks for real-device integration.

matchpatch-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MatchPatch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

matchpatch-0.4.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: matchpatch
+Version: 0.4.0
+Summary: Audio processor preset gain normalization and measurement tools
+Project-URL: Homepage, https://github.com/noseglasses/MatchPatch
+Project-URL: Issues, https://github.com/noseglasses/MatchPatch/issues
+Project-URL: Repository, https://github.com/noseglasses/MatchPatch.git
+License-File: LICENSE
+Requires-Python: <3.15,>=3.12
+Provides-Extra: gui
+Requires-Dist: pyside6>=6.8; extra == 'gui'
+Description-Content-Type: text/markdown
+
+# MatchPatch
+
+<p align="center">
+  <img src="docs/assets/matchmatch-logo.png" alt="MatchPatch: Normalize presets. Match volume." width="260">
+</p>
+
+[![Quality](https://github.com/noseglasses/MatchPatch/actions/workflows/quality.yml/badge.svg)](https://github.com/noseglasses/MatchPatch/actions/workflows/quality.yml)
+[![Release](https://github.com/noseglasses/MatchPatch/actions/workflows/release.yml/badge.svg)](https://github.com/noseglasses/MatchPatch/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/matchpatch.svg)](https://pypi.org/project/matchpatch/)
+[![Python](https://img.shields.io/pypi/pyversions/matchpatch.svg)](https://pypi.org/project/matchpatch/)
+
+<p align="center">
+  <strong><a href="https://youtu.be/Dw1Kez0AnCk">Watch the demo video</a></strong>
+  ·
+  <strong><a href="https://noseglasses.github.io/MatchPatch/">Read the documentation</a></strong>
+  ·
+  <strong><a href="https://github.com/noseglasses/MatchPatch/releases/latest">Download MatchPatch</a></strong>
+</p>
+
+![MatchPatch GUI showing a loaded Helix setlist](docs/assets/screenshots/normalization-ongoing.png)
+
+**No more unexpected volume jumps when switching sounds.**
+
+MatchPatch automatically equalizes the loudness of presets and snapshots in
+guitar processors such as the Line 6 Helix.
+
+## Why MatchPatch?
+
+You create a great clean sound. You create a great lead sound. Then you switch
+between them and one is much louder than the other.
+
+MatchPatch measures your presets and calculates the gain adjustments needed to
+make them consistent, so your setlist feels balanced before rehearsal or stage
+use.
+
+## Features
+
+- Measure preset loudness automatically.
+- Analyze snapshots.
+- Calculate required gain corrections.
+- Modify Helix setlists and presets.
+- Test the workflow without hardware.
+- Configure normal runs from the GUI.
+- Use CLI and worker commands for advanced scripting.
+- Open source.
+
+## Current Support
+
+Current normal workflows support:
+
+- Line 6 Helix
+- `.hls` Helix setlists
+- `.hlx` Helix presets
+- GUI-first workflows
+
+Loopback and simulated modes are available for no-hardware tests. Hardware mode
+is for real Helix measurement.
+
+## Documentation
+
+- Online manual: [noseglasses.github.io/MatchPatch](https://noseglasses.github.io/MatchPatch/)
+- Start here: [docs/index.md](docs/index.md)
+- 10-minute guide: [docs/quick-start.md](docs/quick-start.md)
+- Main manual: [docs/musician-guide.md](docs/musician-guide.md)
+- Test without hardware: [docs/workflows/test-without-hardware.md](docs/workflows/test-without-hardware.md)
+- Hardware measurement: [docs/workflows/hardware-measurement.md](docs/workflows/hardware-measurement.md)
+- Reference DI: [docs/concepts/reference-di.md](docs/concepts/reference-di.md)
+- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
+- FAQ: [docs/faq.md](docs/faq.md)
+- Glossary: [docs/glossary.md](docs/glossary.md)
+
+## Safety Notes
+
+> Warning:
+> Keep backups of your original Helix files.
+
+> Warning:
+> Measurement files are for measuring, not for live playing.
+
+## Install And Launch
+
+On Windows, download the latest installer from
+[GitHub Releases](https://github.com/noseglasses/MatchPatch/releases/latest),
+run `MatchPatch-Setup-<version>.exe`, then launch MatchPatch from the Start
+Menu. The installed app bundles offline Help, available from the GUI.
+
+For source checkouts, use the verified local setup commands below and see
+[Developer Notes](docs/developer-notes.md) and
+[developer commands](docs/dev/commands.md) for fuller setup details.
+
+Install the optional GUI support and launch MatchPatch:
+
+```bash
+# Linux or WSL
+scripts/sync-wsl.sh --extra gui
+matchpatch-gui
+```
+
+```powershell
+# Windows PowerShell
+cd C:\src\MatchPatch-windows
+.\scripts\sync-windows.cmd --extra gui
+.\.venv-windows\Scripts\matchpatch-gui.exe
+```
+
+Hardware measurement from WSL needs a synced native Windows runtime. See
+[developer commands](docs/dev/commands.md) before using real Helix hardware from
+WSL.
+
+## Advanced And Developer Information
+
+Technical details live in the developer docs:
+
+- [Developer Notes](docs/developer-notes.md)
+- [Architecture](docs/dev/architecture.md)
+- [Commands](docs/dev/commands.md)
+- [File Formats](docs/dev/file-formats.md)
+
+## License
+
+MatchPatch is open source software released under the [MIT License](LICENSE).

matchpatch-0.4.0/Python/adjust_gain.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Compatibility wrapper for the historical Helix adjustment command."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PROJECT_DIR / "src"))
+
+from matchpatch.normalize import main  # noqa: E402
+
+if __name__ == "__main__":
+    arguments = sys.argv[1:]
+
+    if "--device" not in arguments:
+        arguments = ["--device", "helix", *arguments]
+
+    main(arguments)

matchpatch-0.4.0/Python/decrypt_hls.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+
+import argparse
+import base64
+import json
+import os
+import sys
+import zlib
+
+
+def require_extension(path, expected_ext, label):
+    ext = os.path.splitext(path)[1].lower()
+
+    if ext != expected_ext:
+        raise ValueError(f"{label} must have extension {expected_ext}, got {ext or '<none>'}")
+
+
+def get_extension(path):
+    return os.path.splitext(path)[1].lower()
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description=(
+            "Decrypt/unpack a Helix .hls file to JSON, or validate/copy a .hlx preset to .hlx"
+        )
+    )
+
+    parser.add_argument("-i", "--input", required=True, help="Input .hls or .hlx file")
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        required=True,
+        help="Output .json file for .hls input, or .hlx for .hlx input",
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    input_ext = get_extension(args.input)
+
+    if input_ext == ".hlx":
+        require_extension(args.output, ".hlx", "Output")
+
+        with open(args.input, "r", encoding="utf-8") as f:
+            preset = json.load(f)
+
+        with open(args.output, "w", encoding="utf-8") as f:
+            json.dump(preset, f, indent=1)
+
+        return
+
+    require_extension(args.input, ".hls", "Input")
+    require_extension(args.output, ".json", "Output")
+
+    with open(args.input, "r", encoding="utf-8") as f:
+        wrapper = json.load(f)
+
+    compressed = base64.b64decode(wrapper["encoded_data"])
+    raw = zlib.decompress(compressed)
+    text = raw.decode("utf-8")
+
+    with open(args.output, "w", encoding="utf-8") as f:
+        f.write(text)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(1)