ShadeCore v1.4.1 — Logging, Validation, and Stability Pass

Overview

This release focuses on stability, observability, and developer experience.
No core rendering, shader, or output behavior has changed.

v1.4.1 establishes a solid foundation for debugging, auditing, and future
feature work (bundling, multipass, UI layers).

Key Changes

1. Unified Logging System

---

• All internal logs now use a consistent format:

  YYYY-MM-DD HH:MM:SS.mmm [TAG][thread] message

• Millisecond-resolution timestamps

• Thread names included for concurrency clarity

• Consistent behavior across macOS and Windows

This makes logs suitable for:

• debugging complex runtime issues
• sharing logs with other developers
• long-running sessions and audits

2. External Process Logging (FFmpeg)

---

• FFmpeg stdout/stderr is now routed through ShadeCore logging
• Output is timestamped and tagged (e.g. FFMPEG_STREAM, FFMPEG_RECORD)
• Prevents unstructured subprocess output from breaking log clarity

3. Run IDs and Session IDs

---

• Each application launch generates a unique run_id
• Recording sessions generate unique session IDs

These identifiers help:

• correlate logs with captures
• track multi-hour sessions
• support user bug reports more effectively

4. Config & Profile Validation (Friendly Errors)

---

Validation is now performed for:

• params.json
• recording.json + recording profiles

When an issue is detected:

• A [CONFIG] log entry is emitted
• The exact JSON path is shown
• A clear explanation is provided
• Hints list valid alternatives when applicable

Example:
[CONFIG] recording.json:/active_profile: active_profile 'foo' not found
(hint: available: 1080p, 720p_fast_preview)

Validation summaries are always logged, even when configs are clean:
[CONFIG] validation: params.json OK (0 issues)

5. Internal Cleanup (No Behavior Changes)

---

• Logging utilities consolidated and clarified
• Unsafe blocks aligned with actual unsafe call boundaries
• Internal consistency improvements

IMPORTANT:
No shader behavior, rendering logic, MIDI routing, OSC handling,
or output routing behavior was changed.

What Did NOT Change

• No rendering pipeline changes
• No shader execution changes
• No output routing changes
• No config schema changes
• No new runtime dependencies

This release is safe as a drop-in update from v1.4.0.

Recommended User Actions

• No configuration changes required
• Existing assets and profiles continue to work
• When reporting issues, include full log output
  (timestamps and tags are now reliable)

Developer Notes

• This release establishes a stable observability baseline
• Logging and validation are considered "done" for v1.x
• Future work can safely build on this foundation:
  • application bundling
  • multipass / feedback pipelines
  • UI layers
  • documentation and marketing

ShadeCore v1.4.0 - OSC Control Plane + Introspection

Release Tag: v1.4
Title: OSC Control Plane + Introspection

SHORT DESCRIPTION

Adds OSC control and introspection endpoints alongside MIDI for a redundant,
modular live-control system with no changes to the core render pipeline.

SUMMARY

This release introduces a full OSC control plane alongside the existing MIDI
system, enabling remote and networked control of shader parameters with
introspection support. MIDI remains fully supported and unchanged.

Together, OSC and MIDI provide two interchangeable control paths feeding the
same parameter system, increasing reliability for live performance,
installations, and development workflows.

KEY FEATURES

• OSC input support using the same parameter names as MIDI (uniform names like:
  u_gain, u_zoom, u_spin)
• OSC introspection endpoints for validating routing and inspecting engine state
• JSON-configurable OSC settings and mappings (no rebuild required)
• Existing MIDI routing and smoothing behavior preserved
• No changes to the core render pipeline

OSC ROUTING

Default prefix: /shadecore
Default bind: 0.0.0.0:9000

Normalized route (0..1 mapped through min/max):
/shadecore/param/<param_name>

Raw route (direct value, clamped to min/max):
/shadecore/raw/<param_name>

Examples:
/shadecore/param/u_gain 0.5
/shadecore/raw/u_zoom 2.25

OSC INTROSPECTION (REPLIES SENT TO SENDER)

List all parameters:
/shadecore/list/params
-> /shadecore/reply/list/params (string args)

Get parameter state:
/shadecore/get/<param_name>
-> /shadecore/reply/get/<param_name>
(floats: current, target, min, max, smoothing)
or ("unknown_param")

List supported OSC mappings:
/shadecore/list/mappings
-> /shadecore/reply/list/mappings

CONFIGURATION

OSC behavior is defined at startup via JSON configuration:

• enabled
• bind address
• prefix
• normalized mode
• optional OSC-to-param mappings

This allows ports, prefixes, and mappings to be changed without rebuilding.

COMPATIBILITY NOTES

• MIDI input continues to work exactly as before.
• OSC and MIDI both write into the same parameter store.
• Last update wins per parameter target, with smoothing applied as usual.

TESTING

OSC (terminal example using oscsend):
oscsend 127.0.0.1 9000 /shadecore/list/params
oscsend 127.0.0.1 9000 /shadecore/get/u_gain
oscsend 127.0.0.1 9000 /shadecore/param/u_gain f 0.5

MIDI:

• Connect MIDI device
• Verify CC mappings still drive u_* uniforms

ShadeCore v1.3.0 - Live coding, recording and hotswap

• Added FBO texture output recording using recording profiles. The profiles define output video format and codec parameters for ffmpeg.
• Added the ability to live-code with shaders by adding a "watcher" to the folder. Use the IDE of your choice, edit the .frag and the changes will be reflected instantly.
• Added a template for hotswapping shaders for testing which have JSON profiles for each
• Each profile has the name of the shader, parameters, MIDI parameters etc.
• MIDI is functional again

All output functionality has stayed the same.

ShadeCore v1.2.0 - macOS/Win/RTSP/NDI

• NDI integrated
• macOS tested/validated
• Optimization will happen after docs are written and baseline code established.

ShadeCore v1.1.0 - macOS/Win/RTSP

• Integrated RTSP streaming for numpad 4
• mediamtx or relative RTSP server is required to receive the FBO texture from shadecore

ShadeCore v1.0.0 - macOS + Win

• Identifies operating system at runtime and triggers a params JSON that defines which framework to use
• Spout & Syphon have been tested
• Numpad controls the output of the engine; 1) FBO texture, 2) Syphon, 3) Spout