The canonical additive harmonic synthesizer of the Harmonic Beacon ecosystem: 32 voices + waveshaper + per-voice LFO + sidechain.
This package is the reconciled standalone extraction of the evolved Shaper in
digital-beacon. The older NaturalHarmony/harmonic_shaper implementation is
historical; its Minilab3 controller was recovered here because it had been lost
from the fork.
python -m venv .venv
source .venv/bin/activate
pip install -e .PortAudio must be available on the host for real-time output through
sounddevice.
python -m harmonic_shaper
# or, after installation:
harmonic-shaperThe default process starts the audio engine, native OSC listener, MIDI controllers when present (Launchpad, Minilab3, and a native keyboard note source), and the FastAPI state service.
Standalone mode defaults to sequential natural-harmonic banks: adjacent keys
select n=1..32 at exact f1*n frequencies. The lower configured bank is
momentary; the upper bank is toggle/sustain. No 12-TET pitch adaptation is
applied. See Native MIDI Harmonic Banks
for configuration and controller calibration. No NaturalHarmony beacon is
required. Useful flags:
python -m harmonic_shaper --slave # opt in to NH /beacon/* broadcasts
python -m harmonic_shaper --f1 40.40 --anchor 24
python -m harmonic_shaper --native-midi-momentary-start 24 --native-midi-toggle-start 72
python -m harmonic_shaper --native-midi-mode legacy_hybrid
python -m harmonic_shaper --no-native-midi # keyboards off; pads/CC still on
python -m harmonic_shaper --no-audio # headless control/API process
python -m harmonic_shaper --no-midi
python -m harmonic_shaper --no-api
python -m harmonic_shaper --helpDefault bindings:
- UDP
:9002: current v1 wire protocol under/digital/*. - UDP
:9001: optional/beacon/*slave input, only with--slave. - HTTP
127.0.0.1:8080:GET /api/state,POST /api/shaper/*, and WebSocket/ws.
/shaper/* is the planned native namespace. It is intentionally not mapped on
the wire yet because renaming /digital/* requires a contract version bump.
The extracted offline reference is also installable:
harmonic-shaper-synth-pure input.wav --out output.wavIt retains the fork's voice-analysis and NumPy rendering path for the clipping work tracked after this extraction.
pytest -qSee the extraction report for the module map, fork reconciliation, dependency audit, and clipping notes.
MIT — see LICENSE.