| name | juce-random-effects-soak |
| description | Run a full JUCE callback-path soak using 10 random native effects at once, rotating serial/parallel flow topologies and blend strategies between flows while collecting xrun, jitter, and CPU evidence. Use when validating engine stability after graph/device/lifecycle changes, reproducing post-start_audio regressions, or generating release-grade performance proof. |
JUCE Random Effects Soak
Run the script in this skill to execute a long-duration JUCE soak with:
- exactly 10 randomly selected effects active per flow epoch
- rotating chain and parallel flow layouts
- rotating blend behavior between flows
- artifact capture for pass/fail evidence
Workflow
- Build the JUCE engine module in Release mode.
- Run a smoke soak first.
- Run the full soak profile.
- Review generated JSON and markdown evidence.
Commands
Smoke run:
python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
--duration-seconds 180 \
--flow-rotation-seconds 12 \
--sample-interval-seconds 0.5 \
--reset-stats-after-warmup
Full run:
python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
--duration-seconds 1800 \
--flow-rotation-seconds 20 \
--sample-interval-seconds 1.0 \
--reset-stats-after-warmup \
--threshold-max-xruns 0 \
--threshold-max-peak-jitter-ms 0.35 \
--threshold-max-budget-utilization-percent 80
Device-targeted bench run (use the exact JUCE/JACK device name):
python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
--audio-device "TASCAM US-144MKII Multichannel" \
--duration-seconds 1800 \
--flow-rotation-seconds 20 \
--sample-interval-seconds 1.0 \
--reset-stats-after-warmup \
--threshold-max-xruns 0 \
--threshold-max-peak-jitter-ms 0.35 \
--threshold-max-budget-utilization-percent 80
Aggressive crash-repro variant (live rewire while callback is running):
python3 .codex/skills/juce-random-effects-soak/scripts/run_juce_random_fx_soak.py \
--duration-seconds 600 \
--flow-rotation-seconds 8 \
--live-rewire
Required Outputs
- JSON artifact with samples, flow transitions, selected effects, and checks
- Markdown summary with PASS/FAIL verdict and thresholds
- Stable callback behavior through repeated graph rewires
Default output path:
docs/fit-for-purpose-evidence/<YYYYMMDD>/juce-random-fx-soak-<timestamp>.{json,md}
Adjustment Rules
- Keep
10 active effects per flow epoch.
- Keep flow rotation enabled; do not run static topology for this skill.
- Keep blend strategy rotation enabled between flow epochs.
- Default to safe rewire mode (stop/start audio around graph rewires); enable
--live-rewire only when intentionally probing race/crash behavior.
- Use
--reuse-effects only for focused callback-only triage where plugin load/unload churn is intentionally excluded.
- Use
--audio-device for bench evidence that must bind a specific interface. MAP2_SOAK_AUDIO_DEVICE is kept as an environment fallback for legacy runbooks, but the CLI flag is preferred because it is captured in the generated JSON/Markdown artifacts.
References
- Flow and blend definitions:
references/flow-and-blend-spec.md
