PVC-to-pvx Parity Matrix

May 25, 2026 ยท View on GitHub

pvx logo

PVC-to-pvx Parity Matrix

This document tracks functional parity work between Paul Koonce's historical PVC package and modern pvx.

Primary references:

Scope

  • Goal: preserve useful PVC workflow primitives while keeping pvx quality-first and automation-friendly.
  • Out of scope: byte-for-byte command-line compatibility with historical PVC binaries.

Capability Matrix

PVC capabilityWhy it mattersCurrent pvx statusGap level
Persistent phase-vocoder analysis files (pvanalysis)Reuse analysis across multiple processing passesImplemented in phase 1/2 via PVXAN schema and pvx analysisClosed (foundation)
Response-file workflows (freqresponse, chordresponsemaker)Reusable filter/target curvesImplemented in phase 1/2 via PVXRF schema and pvx responseClosed (foundation)
Time-varying spectral filtering from response files (tvfilter)Dynamic timbral trajectoriesImplemented in phase 3 via pvx tvfilter + scalar map interpolationClosed (phase 3)
Ring/resonator family (ring, ringfilter, ringtvfilter)Controlled resonant colorationImplemented in phase 4 via dedicated ring CLI familyClosed (phase 4)
Response-driven compander/noise/band emphasis (compander, noisefilter, bandamp)Precision spectral dynamicsImplemented in phase 3 (pvx spec-compander, pvx noisefilter, pvx bandamp)Closed (phase 3)
Harmonic/chord remapping (harmonizer, chordmapper, inharmonator)Musically constrained spectral remapImplemented in phase 5 via pvx chordmapper and pvx inharmonatorClosed (phase 5)
Spectral convolver with response semantics (convolver)Controlled blend of source/target spectraPartial overlap via morph/cross-synthesisMedium
Generic function stream utilities (envelope, reshape)Text-based control-signal authoringImplemented in phase 6 via pvx envelope and pvx reshapeClosed (phase 6)
Parity benchmark scenarios and regression gatesReproducible quality checks for PVC-inspired operatorsImplemented in phase 7 via benchmarks/run_pvc_parity.py + CI workflow gateClosed (phase 7)
Explicit resynthesis families and thresholdsOperator transparency and reproducibilityPartially available but not as PVC-style dedicated modesMedium

Implemented in Phase 1 and Phase 2

  1. Data-model and schema foundations:
    • PVXAN analysis artifact schema in /Users/cleider/dev/pvx/src/pvx/core/analysis_store.py
    • PVXRF response artifact schema in /Users/cleider/dev/pvx/src/pvx/core/response_store.py
  2. User-facing command-line interface (CLI) foundations:
    • pvx analysis create|inspect in /Users/cleider/dev/pvx/src/pvx/cli/pvxanalysis.py
    • pvx response create|inspect in /Users/cleider/dev/pvx/src/pvx/cli/pvxresponse.py
    • Unified CLI registration in /Users/cleider/dev/pvx/src/pvx/cli/pvx.py

Schema Notes

PVXAN

  • Container: compressed NumPy .npz
  • Required members:
    • meta_json
    • spectrum_real (channels x frames x bins)
    • spectrum_imag (channels x frames x bins)
  • Includes deterministic sha256 digest function for reproducibility checks.

PVXRF

  • Container: compressed NumPy .npz
  • Required members:
    • meta_json
    • frequencies_hz (bins)
    • magnitude (channels x bins)
    • phase (channels x bins)
  • Includes deterministic sha256 digest function for reproducibility checks.

Implemented in Phase 3, Phase 4, and Phase 5

  1. Response-driven spectral operators (filter, tvfilter, noisefilter, bandamp, spec-compander):
    • core: /Users/cleider/dev/pvx/src/pvx/core/pvc_ops.py
    • command-line interface (CLI): /Users/cleider/dev/pvx/src/pvx/cli/pvxfilter.py + wrappers
  2. Ring/resonator family (ring, ringfilter, ringtvfilter):
    • core: /Users/cleider/dev/pvx/src/pvx/core/pvc_resonators.py
    • CLI: /Users/cleider/dev/pvx/src/pvx/cli/pvxring.py + wrappers
  3. Harmonic/chord mapping family (chordmapper, inharmonator):
    • core: /Users/cleider/dev/pvx/src/pvx/core/pvc_harmony.py
    • CLI: /Users/cleider/dev/pvx/src/pvx/cli/pvxharmmap.py + wrappers

Implemented in Phase 6 and Phase 7

  1. Function-stream generators/transforms (envelope, reshape) interoperable with control-bus workflows:
    • core: /Users/cleider/dev/pvx/src/pvx/core/pvc_functions.py
    • CLI: /Users/cleider/dev/pvx/src/pvx/cli/pvxenvelope.py, /Users/cleider/dev/pvx/src/pvx/cli/pvxreshape.py
    • installed entry points: pvx envelope, pvx reshape
  2. Parity benchmarks and regression gates:
    • benchmark runner: /Users/cleider/dev/pvx/benchmarks/run_pvc_parity.py
    • baseline: /Users/cleider/dev/pvx/benchmarks/baseline_pvc_parity.json
    • CI workflow: /Users/cleider/dev/pvx/.github/workflows/pvc-parity-regression.yml
    • expanded pipeline scenario: analysis_response_function_chain (analysis-derived response + function-stream modulation)

Immediate Next Steps

  1. Add explicit PVC-style resynthesis family toggles and thresholds where they improve auditability without fragmenting the core pvx voc interface.
  2. Add additional parity scenarios that stress the same pipeline family with persisted artifact round-trips (pvx analysis create + pvx response create) and stricter drift gates.
  3. Add the sorted top-level command roadmap below to stage user-facing workflow expansion in quality-first order.

Sorted Top-Level Command Roadmap

PhasePriorityProposed commandsParity and quality rationale
Phase 1Highestdoctor, inspect, validate, schema, preset, configImproves reproducibility and inspectability before introducing more operator complexity.
Phase 2Highrender, graph, queue, watch, cacheSupports longer research- and production-oriented runs with less shell friction.
Phase 3Medium-Highmod, derive, route, quantize, smoothBrings function-stream/control-signal workflows closer to classic PVC flexibility with modern parameter routing.
Phase 4Mediumbench, compare, regress, abx, reportEstablishes objective parity and regression tracking as first-class command surfaces.
Phase 5Medium-Lowalign, match, stem, spatialize, live, serveExpands into advanced alignment, immersive, and deployment workflows after core parity and QA gates are stable.

Attribution