fix(streaming): slew-rate-limit continuous knobs so fast sweeps don't clip

[qianghan]

Summary

Fixes the tracker bug: "Quickly adjusting settings (especially when exploring unfamiliar parameters) can send output into heavy distortion or clipping. No hysteresis or rate-limiting on control changes means a single fast sweep can produce chaotic, unusable audio."

A fast knob sweep was applied to the running stream as a raw discontinuity. This adds an engine-side, contract-first slew/rate-limiter on continuous knobs so a fast sweep ramps instead of jumping.

Root cause analysis

The path a control change takes from client → engine:

1. Client sends the full knob dict on the params WS channel (~125 Hz). ws_adapter → StreamingSession.set_knobs (acestep/streaming/session.py) coerces it (coerce_knob_values) and virtual_knobs.update(clean) writes the raw target into the shared KnobState.
2. Once per tick the runner calls backend.read_knobs() (acestep/streaming/pipeline_runner.py ~L489). For ACE this returned self.midi_knobs.get_all_values() verbatim — i.e. whatever the operator last set, with no smoothing (acestep/streaming/ace_backend.py read_knobs).
3. produce() → _prepare_tick() turns those values straight into the per-inference-step quantities the diffusion stream consumes (k1/denoise, feedback, shift, channel-group gains, guidance, DCW, hint_strength, x0_target, …) and pushes them onto the in-flight slots via set_shared_curve.

So between two consecutive ticks a knob could jump its entire range in one step; consecutive generations then differed discontinuously → audible distortion/clipping. There was no existing smooth|slew|throttle|hysteresis on this path (verified by search). Two values (hint_strength, x0_target) were additionally read straight off KnobState, bypassing even a future read-time smoothing point.

Fix

• Where: KnobSlewLimiter, applied in ACEStepBackend.read_knobs() — the single once-per-tick boundary. Behind the GeneratorBackend seam, so it protects every transport (web, VST, MCP, headless) with one implementation, not per-UI tweens.
• Contract-first: the ceiling is registry metadata — KnobSpec.slew_max_per_s — projected into the /api/knobs catalog and bumped to KNOB_SCHEMA_VERSION = 2 (TS types regenerated).
• Defaults / no regressions:
  • Range-relative default DEFAULT_SLEW_FRACTION_PER_S = 3.0 → a full-range sweep ramps over ~0.33 s. A slew limiter caps only the rate, so normal/slow adjustments pass through with zero added latency.
  • Only float knobs are slewed. int/enum/bool (seed, steps_override, rcfg_mode, DCW modes, toggles) and non-registry keys (curve specs, the playback clock) pass through verbatim — the rebuild signature and discrete controls are untouched.
  • dt is wall-clock-paced and capped (max_dt_s) so resuming after an idle pause can't release one un-ramped jump.
  • slew_max_per_s = 0 opts a continuous knob out; per-knob overrides honored.
• hint_strength / x0_target now read from the slewed knob dict instead of KnobState directly, so the whole translation path honors the limit.

Test plan / evidence

New tests/unit/test_knob_slew.py (a large jump is broken into bounded per-tick deltas; discrete + unknown keys pass through; slow changes incur no lag; dt cap; first-sighting snap; runtime-knob limit rebuild; catalog projection).

$ pytest tests/unit/test_knob_slew.py --noconftest -q
15 passed in 0.03s

$ pytest tests/unit/test_wire_contract.py tests/unit/test_client_sdk.py --noconftest -q
18 passed in 1.63s   # incl. test_generated_wire_types_match_contract (KNOB_SCHEMA_VERSION 2)

$ npm run typecheck   # demos/realtime_motion_graph_web/web
tsc --noEmit  -> clean

$ npm run build       # demos/realtime_motion_graph_web/web
✓ Compiled successfully; TypeScript clean

(Local box has no GPU/torch, so torch-dependent unit tests and the GPU golden harness were not run here; the changed translation path stays a verbatim pass-through whenever a knob is steady or moving below its ceiling.)

Made with Cursor

[seanhanca]

Superseded by #279, re-opened from a branch on this repo (daydreamlive/DEMON) instead of the qianghan fork. Closing this fork-based PR in favor of #279.