feat(control): OSC output, so the visualizer can drive other software

[Barbaror4]

Closes CaYatur#437

Note on the diff: this fork's main is one merge behind CaYatur/SoundVisualizer main, so the already-merged Stereo Trails commits (CaYatur#732: f9d0a32, 7f95e03, ecdea02, 619580c, 6a1900d) also appear here. The OSC output change itself is the single commit 1afca3a.

What

The app already listens to OSC. This adds the other direction: audio levels, drum hits, the tempo with a beat clock, and scene, mode and MilkDrop preset changes go out as OSC messages to Resolume, TouchDesigner, Max or a lighting desk.

Address (prefix /cayadev)	Type	When
/level /bass /mid /treble	f, 0..1	at the chosen rate, up to 30 Hz
/hit/kick /hit/snare /hit/hat	f, strength	when a hit happens
/tempo/bpm /tempo/confidence	f	on change, else once a second
/tempo/beat	i i	each tempo beat: beat in the bar (1..N) and N
/scene /visualizer /background /milkdrop/preset	s	on change, and again every 5 s

The repeat lets a receiver that starts late still learn the current state.

How

• src/main/osc-out.js (new) has three parts, in the style of the existing OSC input:
  • a hand-written OSC 1.0 encoder;
  • a pure planner that decides what to send each tick, testable without a network;
  • a UDP sender with Art-Net's lifecycle. The host name is resolved once at start, not on every packet.
• Levels and hits come from the visualizer's ~30 Hz audio-meter message, the same hook Art-Net and the lights use. A hit lasts one frame, so the visualizer keeps the strongest kick, snare and hat seen since the last message.
• The beat clock comes from the panel's tempo engine (autovj.js), which reports each beat, but only while OSC output is on. main accepts tempo:beat only from the admin window.
• Settings: a new top-level oscOut section next to artnet, with the same MCP permission (output in PATH_GROUPS). control stays midi/osc only, so MCP's control validator is unchanged.
• Panel: an OSC Çıkışı / OSC Output card in Control, with target, port, rate, prefix and one switch per group. Its live packet counter polls only while the card is on screen.

Safety

• Off by default. The default target is 127.0.0.1:9001; the OSC input listens on 9000.
• Feedback-loop guard. It refuses to send when the target is this computer's open OSC input on the same port. That covers loopback, the machine's own addresses and its subnet broadcast, since the packets would feed back into mapped settings.
• Re-validation in main. Every field (host, port, rate, prefix) is checked again in the main process, so an MCP write or a hand-edited settings file falls back to safe defaults.
• Silent in automation. Like Art-Net, nothing is sent in smoke or screenshot runs (HW_OFF).

Found by running the real app

Levels arrived at 17 Hz with the rate set to 30. An interval threshold dropped every meter message that arrived a millisecond early. The rate is now kept by a schedule. Re-measured in the app: 29.6 Hz, median gap 33 ms. A test reproduces the old behaviour: 205 sends in 10 s where ~300 are expected.

Checks

• npm test: 2959 pass, 17 new in tests/osc-out.test.js:
  • the two example packets from the OSC 1.0 specification, byte for byte;
  • every planned message decoded by the app's own parser (parsePacket is now exported from osc-server.js for this);
  • the rate under meter jitter, and hits, tempo, state, beat, prefix and settings validation;
  • the loop guard;
  • two real UDP round trips over loopback.
• Mutations: 18 of 18 caught (encoding, rate, clamping, tempo/state timing, beat bounds, loop guard, host and prefix checks, the panel-only beat sender, HW_OFF).
• Live, in the real app: isolated --user-data-dir, with the floating window opened through MCP. 1383 packets arrived in 12 s, with levels at 29.6/s, kick/snare/hat hits, beats cycling 1/4..4/4, and the mode switch reported 0.01 s after it happened.
• npm run smoke (isolated --user-data-dir): PASS. Its crawl reported no untranslated text in the English UI.

For the reviewer

• Levels need an open visualizer. Like Art-Net and the lights, levels and hits are sent only while a visualizer window (or the floating window) is open. Tempo, the beat clock and state come from the panel and main.
• Messages, not bundles. Some simple receivers (Max/Pd patches, some lighting desks) don't open #bundle, and ~120 small packets a second are trivial on loopback or a LAN.
• UTF-8 strings. OSC 1.0 says ASCII, but scene names can be Turkish, so strings are UTF-8 (as Resolume, TouchDesigner and Max read them), truncated at a character boundary at 200 bytes.

🤖 Generated with Claude Code