c64cast.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "c64cast configuration",
  "description": "Generated by `c64cast --print-schema`. Do not edit by hand \u2014 regenerate with `make schema`.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "hardware": {
      "type": "object",
      "description": "Hardware backend selection.",
      "additionalProperties": false,
      "properties": {
        "backend": {
          "type": "string",
          "description": "Hardware backend family driving the C64.",
          "enum": [
            "ultimate",
            "teensyrom"
          ],
          "default": "ultimate"
        }
      }
    },
    "teensyrom": {
      "type": "object",
      "description": "TeensyROM+ backend connection.",
      "additionalProperties": false,
      "properties": {
        "transport": {
          "type": "string",
          "description": "TR control link: USB serial or raw TCP (port 2112).",
          "enum": [
            "serial",
            "tcp"
          ],
          "default": "serial"
        },
        "serial_port": {
          "type": [
            "string",
            "null"
          ],
          "description": "Serial device for transport=serial over a plain USB data cable (e.g. /dev/cu.usbmodem* or COM3; NOT an FTDI null-modem cable). On macOS, leave unset to auto-detect the TeensyROM by its USB serial number; required (no auto-detect yet) on other platforms."
        },
        "baud": {
          "type": "integer",
          "description": "Serial baud rate (TR uses full USB bandwidth; 2 Mbaud 8N1).",
          "default": 2000000
        },
        "host": {
          "type": [
            "string",
            "null"
          ],
          "description": "TR IP address for transport=tcp (find via CCGMS \"ATC\" or RTC sync). Required for tcp."
        },
        "tcp_port": {
          "type": "integer",
          "description": "TR TCP listener port (firmware default 2112).",
          "default": 2112
        },
        "storage": {
          "type": "string",
          "description": "Where helper PRGs are uploaded + launched from.",
          "enum": [
            "sd",
            "usb"
          ],
          "default": "sd"
        }
      }
    },
    "ultimate64": {
      "type": "object",
      "description": "Ultimate 64 target + transport.",
      "additionalProperties": false,
      "properties": {
        "url": {
          "type": "string",
          "description": "Base URL of the Ultimate 64 (REST + DMA host).",
          "default": "http://192.168.2.64"
        },
        "system": {
          "type": "string",
          "description": "Target video system timing (affects frame rate + SID PLAY rate).",
          "enum": [
            "NTSC",
            "PAL"
          ],
          "default": "NTSC"
        },
        "dma_port": {
          "type": "integer",
          "description": "TCP port of the U64 Ultimate DMA Service (firmware default 64).",
          "default": 64
        },
        "dma_password": {
          "type": [
            "string",
            "null"
          ],
          "description": "U64 network password, if set. Prefer the C64CAST_DMA_PASSWORD env var over committing it here."
        },
        "auto_reu": {
          "type": "boolean",
          "description": "Auto-enable + size the U64 REU (live, volatile, restored at teardown) for runs that hard-require it ([audio].use_reu_pump or explicit [video].use_reu_staged = true). Removes the manual F2 enable step. false = manage the REU yourself. No effect on no-REU backends or under --skip-probe.",
          "default": true
        },
        "sid_model": {
          "type": "string",
          "description": "Auto-configure the SID chip model (6581/8580) to match what a .sid file's PSID header requests, remapping to a matching physical socket or an UltiSID core if needed. 'off' disables. An explicit '6581'/'8580' forces that model for every chip, ignoring the header.",
          "enum": [
            "auto",
            "6581",
            "8580",
            "off"
          ],
          "default": "auto"
        },
        "sid_panning": {
          "type": "array",
          "description": "Stereo pan per SID audio source, U64 only. Max 4 entries \u2014 the U64 has one pan control per source (2 SID sockets + 2 UltiSID cores), and entry N pans the Nth source the tune uses. Each entry is an int -5..5 (negative = left, 0 = center) or a label ('Left 3', 'Center', 'Right 2'). Empty = auto spread: 1 source centered, 2 [-3, 3], 3 [0, -3, 3], 4 [-2, 2, -5, 5] \u2014 ordered so the primary chip stays nearest center. Fewer positions exist without socketed SIDs: with none, only the 2 UltiSID cores are pannable, so chips beyond the 2nd share a pan.",
          "default": []
        },
        "sid_volume": {
          "type": "array",
          "description": "Mixer level per SID audio source, U64 only. Max 4 entries \u2014 the U64 has one volume control per source (2 SID sockets + 2 UltiSID cores), and entry N sets the Nth source the tune uses, same indexing as sid_panning. Each entry is a dB int (0, -6, 3) or a label ('0 dB', '-6 dB', 'off'). Empty = auto: a source the tune plays on is raised to 0 dB when it would otherwise be OFF (silent), a source already at a deliberate level is left alone, and every source the tune does not use is muted. The ladder is sparse below -18 dB: -42, -36, -30, -27, -24, then every dB from -18 to +6.",
          "default": []
        }
      }
    },
    "video": {
      "type": "object",
      "description": "Webcam input + experimental video paths.",
      "additionalProperties": false,
      "properties": {
        "device": {
          "type": [
            "integer",
            "string"
          ],
          "description": "Webcam device: an integer cv2 index (-1 = system default camera, cv2 index 0), or a string matched to a camera by name substring (e.g. \"Cam Link\") or USB VID:PID (e.g. \"0fd9:0066\"). String selection needs the 'camera' extra; run --list-devices to see names + VID:PID.",
          "default": -1
        },
        "use_reu_staged": {
          "type": [
            "boolean",
            "string"
          ],
          "description": "REU bank-swap double-buffer for video push. \"auto\" (default) stages bitmap modes (hires/mhires) when the startup probe finds the U64's REU enabled, leaving char modes on the cheaper host-DMA path; true forces it on for every mode, false off. auto silently falls back to host-DMA when REU isn't confirmed.",
          "default": "auto"
        },
        "double_buffer": {
          "type": [
            "boolean",
            "string"
          ],
          "description": "Host-DMA double-buffer (page flip) for tear-free bitmap video where REU staging can't help. \"auto\" (default) enables it for bitmap modes (hires/mhires) when REU staging is off and either the backend has no REU (e.g. TeensyROM) or the scene has a text overlay (whose presence turns the REU path off to dodge bank-swap shimmer, otherwise leaving single-buffer host-DMA that tears on cuts). true forces it on for bitmap modes, false off; gated off when the REU mic pump is active (shared $0314). Independent of [video].use_reu_staged (the REU path).",
          "default": "auto"
        }
      }
    },
    "audio": {
      "type": "object",
      "description": "SID audio streaming.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Master switch for SID audio streaming (the 4-bit $D418 DAC). On by default; mute with the --no-audio CLI flag.",
          "default": true
        },
        "device": {
          "type": [
            "integer",
            "string"
          ],
          "description": "Audio input device: an integer index (-1 = system default microphone), or a string matched to an input device by name substring (e.g. \"Cam Link\"). Run --list-devices to see names + indices.",
          "default": -1
        },
        "sample_rate": {
          "type": "integer",
          "description": "Audio sample rate in Hz fed to the SID DAC. Default 12000 lifts the Nyquist to ~6.0 kHz so fricatives/sibilants survive (8000 lost them). HW-verified clean on a real NTSC U64-II via a pitch A/B sweep (no NMI handler overrun) in both char and bitmap modes, and safe on PAL. Note the REAL streaming ceiling sits BELOW the isolated-handler ceiling (max_safe_sample_rate ~13.6 kHz NTSC): the host-DMA audio ring writes themselves halt the 6510 and steal cycles from the NMI handler, so the overrun onset under the live pipeline was measured at ~12500 Hz (identical in char and bitmap \u2014 the audio feed, not the video, is the driver). 12000 keeps margin below that. Rates past the isolated-handler ceiling are rejected at load (see c64.nmi_rate_safety). Sampler-backend playback uses [audio].sampler_sample_rate instead.",
          "default": 12000
        },
        "backend": {
          "type": "string",
          "description": "Video-audio backend: 'auto' (sampler on a capable U64, else DAC), 'dac' (4-bit $D418 NMI DAC, all backends, lo-fi), or 'sampler' (U64 'Ultimate Audio' FPGA PCM, high fidelity, off the C64 bus).",
          "enum": [
            "auto",
            "dac",
            "sampler"
          ],
          "default": "auto"
        },
        "sampler_sample_rate": {
          "type": "integer",
          "description": "Sample rate (Hz) for the Ultimate Audio sampler backend. 1000..48000; default 44100 (CD quality). The FPGA plays at the nearest divider of its 6.25 MHz reference (a <0.5% constant pitch offset, drift-free).",
          "default": 44100
        },
        "sampler_bits": {
          "type": "integer",
          "description": "PCM bit depth for the Ultimate Audio sampler backend: 8 (signed) or 16 (signed little-endian). Default 16.",
          "default": 16
        },
        "sampler_clock_hz": {
          "type": "integer",
          "description": "Ultimate Audio sampler reference clock (Hz), used to derive the rate divider AND the resample target so they stay matched (heard speed = real_clock / this). Default is the MEASURED effective clock of the shipping U64 firmware (~6160000 Hz): the FPGA runs ~1.44% slow vs the 6250000 Hz design nominal, so nominal made sampler audio drift against video. This is a firmware property (same across U64 units), not per-unit \u2014 so it ships baked in. If a firmware update fixes the clock (or on hardware that clocks it correctly), set 6250000. Re-measure with scripts/diags/sampler_av_align_calib.py (prints the value). Only affects the sampler backend.",
          "default": 6160000
        },
        "mic_sensitivity": {
          "type": "number",
          "description": "Microphone input gain multiplier.",
          "default": 1.5
        },
        "noise_gate": {
          "type": "number",
          "description": "Mic level below which input is squelched to silence.",
          "default": 0.05
        },
        "dither": {
          "type": "boolean",
          "description": "TPDF dither on the 4-bit quantization step. Default off; flip on for smoother hiss on already-noisy sources.",
          "default": false
        },
        "digi_boost": {
          "type": "boolean",
          "description": "EXPERIMENTAL: lock SID voices to a DC pulse so the ADSR D/As bias the master mixer, raising $D418 playback level.",
          "default": false
        },
        "dac_curve": {
          "type": "string",
          "description": "SID $D418 DAC companding curve. 'auto' (default) = per-system calibrated table if present, else 'mahoney_ultisid' on the Ultimate, else 'linear'. 'linear' = classic 4-bit volume nibble. 'mahoney_ultisid' = Mahoney 8-bit technique (full $D418 byte, ~6-7 effective bits) with the baked emulated-UltiSID table. 'calibrated' = this system's per-unit table from --calibrate-dac (errors if none). Non-linear curves require the Mahoney SID env (auto-installed) and are mutually exclusive with digi_boost.",
          "enum": [
            "auto",
            "linear",
            "mahoney_ultisid",
            "calibrated"
          ],
          "default": "auto"
        },
        "dac_calibration_profile": {
          "type": [
            "string",
            "null"
          ],
          "description": "Override the auto-derived calibration file key (device unique_id / TR USB serial) with this name \u2014 calibration/dac/profile-<name>.json. Use when a TeensyROM+ moves between physical C64s: name each host's calibration once at --calibrate-dac time, then pass the same name on every playback run against that host."
        },
        "sid_filter_cutoff": {
          "type": "integer",
          "description": "SID low-pass cutoff for the PWM carrier voice (0 = disabled). Attenuates the carrier above the audio band.",
          "default": 0
        },
        "use_reu_pump": {
          "type": "boolean",
          "description": "EXPERIMENTAL: stream video/mic audio from a REU ring (bus-clean) instead of per-write host DMA. Requires REU enabled.",
          "default": false
        },
        "reu_pump_governor": {
          "type": "boolean",
          "description": "C64-side rate governor for the REU audio pump: the pump IRQ skips a chunk when its write head outruns the reader, stopping drift/echo with no host writes. Only active with use_reu_pump.",
          "default": true
        },
        "host_dma_servo": {
          "type": "boolean",
          "description": "Closed-loop pacing for the host-DMA audio worker (mic / videos): reads the C64 NMI read pointer and adjusts the producer's software pace so the ring write head holds a fixed gap behind the reader, stopping the ~26s drift/echo. Pure host-side timing, no C64 writes. Not the REU pump path.",
          "default": true
        },
        "nmi_rate_adaptive": {
          "type": "boolean",
          "description": "Adaptive NMI-rate compensation: closed-loop on the measured C64 consumer rate, raises the NMI rate to cancel a video slowdown from bus-halt-stolen NMI ticks. DEFAULT OFF \u2014 modern fps caps + REU-staged double-buffer drove that loss to ~0, so this only adds pitch error now. Supersedes pitch_mult_* when on. Host-DMA path only.",
          "default": false
        },
        "source_alignment_marker": {
          "type": "boolean",
          "description": "DEBUG/CAPTURE ONLY: prepend a 100 ms chirp to REU audio as a capture-alignment anchor. Turn OFF for production listening.",
          "default": false
        },
        "pitch_mult_petscii": {
          "type": "number",
          "description": "Host-DMA servo playback-rate multiplier for PETSCII mode (light char-mode load). 1.0 = none (default; U64-II NTSC is dead-on). Quantized: the NMI period is an integer cycle count, so a request rounds onto the latch grid (~1.2% steps at 12 kHz) \u2014 1.005 is a no-op, 1.015 lands on +1.19%.",
          "default": 1.0
        },
        "pitch_mult_hires": {
          "type": "number",
          "description": "Host-DMA servo playback-rate multiplier for Hires / Hires-edges modes. 1.0 = none (default; modern fps caps + REU staging leave ~0 loss on U64-II NTSC). Re-tune only if a platform (PAL/TR+) drifts. Quantized: the NMI period is an integer cycle count, so a request rounds onto the latch grid (~1.2% steps at 12 kHz) \u2014 1.005 is a no-op, 1.015 lands on +1.19%.",
          "default": 1.0
        },
        "pitch_mult_mhires": {
          "type": "number",
          "description": "Host-DMA servo playback-rate multiplier for MultiHires mode. 1.0 = none (default; modern fps caps + REU staging leave ~0 loss on U64-II NTSC). Re-tune only if a platform (PAL/TR+) drifts. Quantized: the NMI period is an integer cycle count, so a request rounds onto the latch grid (~1.2% steps at 12 kHz) \u2014 1.005 is a no-op, 1.015 lands on +1.19%.",
          "default": 1.0
        },
        "pitch_mult_mcm": {
          "type": "number",
          "description": "Host-DMA servo playback-rate multiplier for MCM mode (char-based, light load; U64-II NTSC: good at 1.0). Quantized: the NMI period is an integer cycle count, so a request rounds onto the latch grid (~1.2% steps at 12 kHz) \u2014 1.005 is a no-op, 1.015 lands on +1.19%.",
          "default": 1.0
        },
        "pitch_mult_blank": {
          "type": "number",
          "description": "Host-DMA servo playback-rate multiplier for Blank mode (no video input; 1.0 = none). Quantized: the NMI period is an integer cycle count, so a request rounds onto the latch grid (~1.2% steps at 12 kHz) \u2014 1.005 is a no-op, 1.015 lands on +1.19%.",
          "default": 1.0
        },
        "dac_bitmap_tempo_hires": {
          "type": "number",
          "description": "Observed $D418-DAC playback-speed fraction on Hires / Hires-edges bitmap modes (measure via clock/wall). Content is time-compressed by 1/value (pitch-preserving) so bitmap+DAC video plays at real time. 1.0 = off. Host-DMA DAC path only \u2014 no effect on the Ultimate Audio sampler or the REU pump. Default 0.89 = U64-II NTSC (Hires drains slightly faster than MHires); re-measure per platform (PAL / TR+).",
          "default": 0.89
        },
        "dac_bitmap_tempo_mhires": {
          "type": "number",
          "description": "Observed $D418-DAC playback-speed fraction on MultiHires bitmap mode (measure via clock/wall). Content is time-compressed by 1/value (pitch-preserving) so bitmap+DAC video plays at real time. 1.0 = off. Host-DMA DAC path only \u2014 no effect on the Ultimate Audio sampler or the REU pump. Default 0.88 = U64-II NTSC; re-measure per platform (PAL / TR+).",
          "default": 0.88
        }
      }
    },
    "vision": {
      "type": "object",
      "description": "Webcam hand-gesture control (extra).",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable webcam hand-gesture control (pinch=pause/resume, swipe=skip, open-hand=cycle). Needs the 'vision' extra.",
          "default": false
        },
        "model_path": {
          "type": "string",
          "description": "Path to the MediaPipe HandLandmarker .task model bundle (download separately; see assets/models/README.md).",
          "default": "assets/models/hand_landmarker.task"
        },
        "num_hands": {
          "type": "integer",
          "description": "Max hands the tracker detects per frame.",
          "default": 1
        },
        "min_detection_confidence": {
          "type": "number",
          "description": "Minimum confidence to detect a hand (0..1). Raise it if your torso/face occasionally register as a phantom hand.",
          "default": 0.7
        },
        "min_tracking_confidence": {
          "type": "number",
          "description": "Minimum confidence to keep tracking a hand across frames (0..1).",
          "default": 0.5
        },
        "poll_interval_s": {
          "type": "number",
          "description": "Seconds between gesture-recognition ticks (~0.066 = 15 Hz).",
          "default": 0.066
        },
        "pinch_threshold": {
          "type": "number",
          "description": "Thumb-index normalized distance below which a pinch registers.",
          "default": 0.05
        },
        "swipe_velocity": {
          "type": "number",
          "description": "Wrist horizontal speed (frame-widths/sec) that triggers a skip. HW-tuned: deliberate swipes peak ~0.5-1.1, drift stays < ~0.2.",
          "default": 0.4
        },
        "gesture_cooldown_s": {
          "type": "number",
          "description": "Minimum seconds between fired gesture events (debounce).",
          "default": 1.0
        },
        "gesture_dwell_s": {
          "type": "number",
          "description": "Seconds a pose (pinch / open hand) must be held STILL before it fires (0 = first frame). With the stillness gate this rejects busy/moving hands and poses passing through on the way to a swipe. Swipe (motion) ignores it.",
          "default": 0.4
        },
        "hold_threshold_s": {
          "type": "number",
          "description": "Seconds a pinch must be held while paused to resume.",
          "default": 3.0
        },
        "mirror": {
          "type": "boolean",
          "description": "Mirror the frame before tracking so swipe direction matches the mirrored webcam view.",
          "default": true
        },
        "performance": {
          "type": "boolean",
          "description": "Live DJ/VJ Phase 6: remap the RUNNING-state gestures to clip-launch performance actions instead of transport \u2014 swipe = launch the next [[performance.clips]] slot, pinch-hold = bypass effect layer 0, open-hand-hold = bypass effect layer 1. Off (default) keeps the transport mapping (swipe=skip, pinch=pause, open-hand=cycle style). Pinch-hold-to-resume while paused is unchanged either way. Needs a [[performance.clips]] grid for the clip-advance gesture to do anything.",
          "default": false
        }
      }
    },
    "interstitial": {
      "type": "object",
      "description": "The 'UP NEXT' card shown between scenes.",
      "additionalProperties": false,
      "properties": {
        "duration_s": {
          "type": "number",
          "description": "How long the 'UP NEXT' interstitial shows between scenes.",
          "default": 4.0
        },
        "text_color": {
          "type": "string",
          "description": "Interstitial text color: a C64 color name, 'rainbow', or 'random'.",
          "default": "rainbow"
        },
        "background": {
          "type": "string",
          "description": "Animated parallax background style behind the interstitial text.",
          "enum": [
            "starfield",
            "petscii_bars",
            "raster_bars",
            "checker",
            "nature",
            "city",
            "none",
            "random"
          ],
          "default": "random"
        }
      }
    },
    "playlist": {
      "type": "object",
      "description": "Playlist behavior + video interleaving.",
      "additionalProperties": false,
      "properties": {
        "videos_dir": {
          "type": "string",
          "description": "Directory of videos to interleave between scenes.",
          "default": "assets/videos"
        },
        "interleave_videos": {
          "type": "boolean",
          "description": "Insert a video from videos_dir after each scene (multi-scene playlists only; ignored in single-scene mode).",
          "default": false
        },
        "songlengths_file": {
          "type": [
            "string",
            "null"
          ],
          "description": "Path to an HVSC Songlengths.md5 file; gives waveform scenes their true duration when duration_s is unset. Left unset (the default), an unpacked HVSC under assets/sids/ (either the whole C64Music/ tree or just its contents) is auto-detected. Set to an empty string to disable auto-detection."
        },
        "loop": {
          "type": "boolean",
          "description": "Loop the playlist after the last scene (--no-loop exits after one pass; useful for 'play one video and quit').",
          "default": true
        },
        "fade_duration_s": {
          "type": "number",
          "description": "Fade-in/out duration (seconds) at scene setup/teardown: non-black pixels rise from black on entry and sink to black on a normal scene end, across every compose-based display mode. 0 disables (hard cuts). A CTRL skip aborts an in-progress fade immediately.",
          "default": 0.4
        }
      }
    },
    "debug": {
      "type": "object",
      "description": "Logging, heartbeat, profiling.",
      "additionalProperties": false,
      "properties": {
        "verbose": {
          "type": "integer",
          "description": "Log verbosity (0 = INFO; 1+ = DEBUG). CLI: -v / -vv.",
          "default": 0
        },
        "heartbeat": {
          "type": "number",
          "description": "Seconds between health heartbeat log lines (0 disables).",
          "default": 10.0
        },
        "skip_probe": {
          "type": "boolean",
          "description": "Skip the startup U64 reachability probe.",
          "default": false
        },
        "log_file": {
          "type": [
            "string",
            "null"
          ],
          "description": "Also mirror log output to this file (useful for headless runs)."
        },
        "profile": {
          "type": "boolean",
          "description": "Emit per-scene frame-timing summaries (render/compose/push/wait).",
          "default": false
        },
        "profile_interval": {
          "type": "number",
          "description": "Seconds between profiler summary lines.",
          "default": 10.0
        },
        "frame_numbers": {
          "type": "boolean",
          "description": "Overlay the playback timecode + source frame number on video/slideshow/webcam frames (debug aid for locating flashing/flickering frames).",
          "default": false
        }
      }
    },
    "preview": {
      "type": "object",
      "description": "Local mirror window of the C64 display.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Open a local window mirroring the U64 display (needs a desktop session; no extra required).",
          "default": false
        },
        "fps": {
          "type": "integer",
          "description": "Preview window refresh rate.",
          "default": 30
        },
        "scale": {
          "type": "integer",
          "description": "Integer pixel scale factor for the preview window.",
          "default": 3
        },
        "charset_path": {
          "type": [
            "string",
            "null"
          ],
          "description": "C64 character ROM used to render char modes in the preview.",
          "default": "assets/roms/characters.901225-01.bin"
        }
      }
    },
    "recording": {
      "type": "object",
      "description": "Record the rendered display to a file.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Record the rendered display to a video file (cv2.VideoWriter).",
          "default": false
        },
        "path": {
          "type": "string",
          "description": "Output video file path.",
          "default": "recording.mp4"
        },
        "fps": {
          "type": "integer",
          "description": "Recording frame rate.",
          "default": 30
        },
        "scale": {
          "type": "integer",
          "description": "Integer pixel scale factor for the recording.",
          "default": 2
        },
        "fourcc": {
          "type": "string",
          "description": "FourCC codec code passed to cv2.VideoWriter.",
          "default": "mp4v"
        }
      }
    },
    "color": {
      "type": "object",
      "description": "Global pre-quantize color shaping for mcm/mhires/petscii: static channel boost + hue corrections, plus per-source adaptive auto_fit (video/slideshow).",
      "additionalProperties": false,
      "properties": {
        "channel_boost": {
          "type": "array",
          "description": "Per-channel pre-quantize gain [blue, green, red] (OpenCV BGR order). Empty = built-in default [1.3, 1.2, 1.0] (blue/green lift toward C64-friendly hues; red left neutral).",
          "default": []
        },
        "hue_corrections": {
          "type": "array",
          "description": "List of [[color.hue_corrections]] bands applied before quantize (keys: hue_lo_deg, hue_hi_deg, sat_thresh, val_thresh, sat_mult, val_mult, hue_target_deg, name). Empty = built-in purple rescue only.",
          "default": []
        },
        "hue_corrections_replace_defaults": {
          "type": "boolean",
          "description": "If true, user hue_corrections REPLACE the built-in defaults instead of extending them.",
          "default": false
        },
        "auto_fit": {
          "type": "boolean",
          "description": "Per-source adaptive color fit for video + slideshow scenes: pre-scan the source and stretch its contrast + saturation to fill the C64 gamut (faithful \u2014 hue preserved). Ignored by webcam scenes (can't pre-scan).",
          "default": true
        },
        "auto_fit_strength": {
          "type": "number",
          "description": "Strength of the auto_fit transform, 0..1 (1 = full, 0 = off). Lerps the derived stretch toward identity.",
          "default": 1.0
        },
        "force_palette": {
          "type": "boolean",
          "description": "EXTREME forced-palette remap (mcm/mhires): k-means the source into N clusters and map each to a DISTINCT C64 color so all N colors are used. Pre-scanned for video + slideshow; adapts live (rolling, warm-start + hysteresis) for webcam/wled/generative. Deliberate false-color (NOT faithful) \u2014 off by default; also reachable via the SHIFT cycle's 'percell+forced' stop once enabled. Tip: `--suggest-palette FILE` ranks a good force_palette_colors set.",
          "default": false
        },
        "force_palette_colors": {
          "type": [
            "integer",
            "array"
          ],
          "description": "How force_palette allocates C64 colors: either an int count of distinct colors to spread the source across (2..16), OR an explicit list of colors to whitelist \u2014 each a color name (fuzzy + case-insensitive, e.g. \"light blue\", \"lgrn\", \"blk\") or an index 0..15. A list's length sets the color count.",
          "default": 16
        },
        "dither": {
          "type": "string",
          "description": "Spatial dither applied before nearest-palette quantization on mhires/mcm/hires. 'auto' picks the best method that's actually useful for the scene: floyd-steinberg (highest quality) for static scenes (slideshow), blue_noise (vectorized, temporally stable \u2014 no added shimmer, and no Bayer grid structure) for motion scenes (video/webcam/generative). Any value can be forced on any scene; floyd-steinberg/atkinson are a Python-level per-pixel loop and can shimmer frame-to-frame on motion; 'ordered' (Bayer) is the older motion default and still available if the cross-hatch pattern is wanted (see docs/caveats.md).",
          "enum": [
            "auto",
            "none",
            "ordered",
            "blue_noise",
            "floyd-steinberg",
            "atkinson"
          ],
          "default": "auto"
        },
        "dither_strength": {
          "type": "number",
          "description": "Dither strength, roughly 0..2.0. For 'ordered'/'blue_noise' it scales the threshold spread (same scale for both, so switching between them doesn't need a strength retune); for floyd-steinberg/atkinson it scales how much of each pixel's quantization error is diffused to its neighbors (1.0 = the textbook kernel weights).",
          "default": 0.5
        },
        "color_match": {
          "type": "string",
          "description": "Color space for the nearest-palette match on the quantizing modes (mcm/mhires/hires/petscii). 'perceptual' measures nearest-color in CIE-Lab (perceptually uniform \u2014 picks the color the eye calls closest, e.g. a warm gray \u2192 orange/brown, not muddy gray). 'rgb' is the classic brightness-weighted BGR metric. Both keep the channel_boost + gray-penalty shaping; only the distance space differs. 'auto' (default) picks perceptual on every quantizing mode (a no-op on hires edges / blank, which pick no colors).",
          "enum": [
            "auto",
            "rgb",
            "perceptual"
          ],
          "default": "auto"
        },
        "cell_strategy": {
          "type": "string",
          "description": "How mhires percell mode fills each 4\u00d78 cell's 3 per-cell color slots from the colors present in that cell. 'frequency' = the 3 most-common (temporally stable). 'luminance' = darkest/median/brightest (preserves a cell's full tonal span). 'contrast' = the two luma extremes plus the color farthest from both. 'error-min' = the trio minimizing the cell's reconstruction error (best quality, costlier). 'auto' (default) uses error-min for static scenes (slideshow \u2014 composed once) and frequency for motion scenes (video/webcam/generative, where frequency's stability avoids per-frame slot churn). Only affects mhires with palette_mode=percell.",
          "enum": [
            "auto",
            "frequency",
            "luminance",
            "contrast",
            "error-min"
          ],
          "default": "auto"
        },
        "motion_smoothing": {
          "type": "number",
          "description": "Temporal smoothing for mhires percell mode, 0..1. The percell path smooths its per-cell color choices over time (an EMA over color counts plus per-pixel/per-cell decision hysteresis) to suppress frame-to-frame flicker on noisy video. That smoothing trades motion-tracking for stability, so on a hard shot cut an outline from the previous shot lingers as an after-image for a moment. 1.0 (full smoothing) is the most stable but ghostiest; 0.0 tracks the source exactly (no after-image) but can flicker on grainy content. The default 0.25 was picked by hardware A/B as the best ghost/flicker balance. Lower it if after-images still bother you, raise it if motion shimmers. No effect on other modes or palette_modes.",
          "default": 0.25
        }
      }
    },
    "dsp": {
      "type": "object",
      "description": "Host-side audio DSP before the 4-bit DAC: compressor/limiter, expander (replaces the hard gate), pre-emphasis, and mic AGC.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Master switch for the host-side audio DSP chain (ON by default \u2014 the 4-bit DAC needs it). Set false for the legacy linear encode + hard mic gate.",
          "default": true
        },
        "pre_emphasis": {
          "type": [
            "number",
            "null"
          ],
          "description": "High-frequency boost amount; y[n]=x+amt*(x-x[-1]). Brightens speech for intelligibility. Unset = source-aware default (mic 0.7 / line 0.6); a number forces that amount for all sources; 0 disables. Per-scene [[scenes]].pre_emphasis overrides this."
        },
        "expander": {
          "type": "boolean",
          "description": "Downward expander with hysteresis (replaces the hard noise gate when DSP is enabled). Attenuates below the threshold.",
          "default": true
        },
        "expander_threshold_db": {
          "type": "number",
          "description": "Level below which the expander attenuates (dBFS).",
          "default": -45.0
        },
        "expander_ratio": {
          "type": "number",
          "description": "Expansion ratio (>1; larger = more attenuation below thresh).",
          "default": 2.0
        },
        "expander_hysteresis_db": {
          "type": "number",
          "description": "Gap (dB) below the open threshold before the gate closes \u2014 prevents chatter on signal hovering at the threshold.",
          "default": 6.0
        },
        "expander_floor_db": {
          "type": "number",
          "description": "Maximum attenuation the expander applies (dB).",
          "default": -60.0
        },
        "expander_attack_ms": {
          "type": "number",
          "description": "Expander gain open (attack) time constant in ms.",
          "default": 5.0
        },
        "expander_release_ms": {
          "type": "number",
          "description": "Expander gain close (release) time constant in ms.",
          "default": 80.0
        },
        "compress": {
          "type": "boolean",
          "description": "Soft-knee feed-forward compressor + makeup gain \u2014 the main win for fitting program dynamics into 4 bits.",
          "default": true
        },
        "comp_threshold_db": {
          "type": "number",
          "description": "Compression threshold (dBFS); above this, gain reduces.",
          "default": -18.0
        },
        "comp_ratio": {
          "type": "number",
          "description": "Compression ratio (>=1; e.g. 3 = 3:1 above threshold).",
          "default": 3.0
        },
        "comp_knee_db": {
          "type": "number",
          "description": "Soft-knee width in dB around the threshold (0 = hard knee).",
          "default": 6.0
        },
        "comp_attack_ms": {
          "type": "number",
          "description": "Compressor attack time constant in ms.",
          "default": 5.0
        },
        "comp_release_ms": {
          "type": "number",
          "description": "Compressor release time constant in ms.",
          "default": 120.0
        },
        "comp_makeup_auto": {
          "type": "boolean",
          "description": "Auto-compute makeup gain so threshold-level signal exits near unity. Set false to use comp_makeup_db explicitly.",
          "default": true
        },
        "comp_makeup_db": {
          "type": "number",
          "description": "Explicit makeup gain (dB) when comp_makeup_auto is false.",
          "default": 0.0
        },
        "limiter": {
          "type": "boolean",
          "description": "Fast peak limiter / brickwall ceiling \u2014 final safety stage.",
          "default": true
        },
        "limiter_ceiling": {
          "type": "number",
          "description": "Limiter output ceiling, linear 0..1 (just under full scale).",
          "default": 0.95
        },
        "limiter_release_ms": {
          "type": "number",
          "description": "Limiter gain recovery (release) time constant in ms.",
          "default": 50.0
        },
        "agc": {
          "type": "boolean",
          "description": "Automatic gain control for the MIC path only (line/video audio is already peak-normalized). Slow gain toward a target. EXPERIMENTAL: being level-based it can boost a sustained noise floor during long pauses \u2014 best on clean mics, or pair with the expander / raise agc_noise_floor_db above the floor.",
          "default": false
        },
        "agc_target_db": {
          "type": "number",
          "description": "AGC target RMS level (dBFS).",
          "default": -18.0
        },
        "agc_max_gain_db": {
          "type": "number",
          "description": "Maximum AGC gain/attenuation magnitude (dB).",
          "default": 24.0
        },
        "agc_time_ms": {
          "type": "number",
          "description": "AGC adaptation time constant in ms (larger = slower/steadier).",
          "default": 300.0
        },
        "agc_noise_floor_db": {
          "type": "number",
          "description": "Below this input RMS, AGC holds gain instead of amplifying the noise floor.",
          "default": -60.0
        }
      }
    },
    "audio_features": {
      "type": "object",
      "description": "Analyzer that turns live audio input into reactive-visual features (level / bands / transients / tempo) for a generative scene with audio_source = 'mic' and reactive = true.",
      "additionalProperties": false,
      "properties": {
        "bands": {
          "type": "integer",
          "description": "Number of log-spaced frequency bands the analyzer reports (low\u2192high). Generators fold these into bass/mid/treble thirds, so multiples of 3 are not required; 8 matches the spectrum_petscii overlay's bands. More bands = finer spectral detail, no meaningful cost.",
          "default": 8
        },
        "onset_sensitivity": {
          "type": "number",
          "description": "Transient-detection sensitivity. The spectral-flux threshold is divided by this, so >1 fires onsets more readily (sparse/soft material, a quiet feed) and <1 fires less (dense or heavily compressed material where everything reads as a transient). 1.0 is the tuned default.",
          "default": 1.0
        },
        "poll_hz": {
          "type": "number",
          "description": "Analysis rate in Hz. 60 matches a full-rate display, so every rendered frame sees fresh features. Lower it only to save host CPU; below ~30 transients start to smear.",
          "default": 60.0
        },
        "fft_size": {
          "type": "integer",
          "description": "Analysis window in samples. Larger = finer frequency resolution but blurrier transient timing; 1024 is the balance point at the DAC's sample rates.",
          "default": 1024
        },
        "listen_sample_rate": {
          "type": "integer",
          "description": "Capture rate in Hz for audio_source = 'listen' (the listen-only path, which never feeds the DAC and so isn't bound to its ~12 kHz rate). 44100 gives the analyzer full-bandwidth audio \u2014 real hi-hat energy above the DAC's 6 kHz Nyquist and cleaner transients. Ignored by audio_source = 'mic' (that path analyzes at the DAC rate, matching what the C64 actually plays).",
          "default": 44100
        }
      }
    },
    "control": {
      "type": "object",
      "description": "HTTP control plane (extra).",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Run the HTTP control plane (pause/resume/skip/reload); requires the 'control' extra.",
          "default": false
        },
        "host": {
          "type": "string",
          "description": "Bind address for the control-plane HTTP server.",
          "default": "127.0.0.1"
        },
        "port": {
          "type": "integer",
          "description": "Bind port for the control-plane HTTP server.",
          "default": 8765
        }
      }
    },
    "midi_control": {
      "type": "object",
      "description": "MIDI CC control surface for live performance: scene jumps, style cycling, transport, live effect params (extra).",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Run the MIDI control listener; requires the 'midi' extra.",
          "default": false
        },
        "port": {
          "type": [
            "string",
            "null"
          ],
          "description": "MIDI input port name (substring match, case-insensitive). None = first available port."
        },
        "broadcast_channel": {
          "type": "integer",
          "description": "1-based MIDI channel that targets every system at once in ensemble mode. Other channels 1..N target the Nth system in ensemble order. Ignored in single-system mode (the one playlist is always the target).",
          "default": 16
        },
        "jump_transition": {
          "type": "string",
          "description": "How a 'jump' action changes scenes: 'cut' (instant, no interstitial \u2014 the live-performance default) or 'interstitial' (routes through the normal UP-NEXT card).",
          "enum": [
            "cut",
            "interstitial"
          ],
          "default": "cut"
        },
        "osd": {
          "type": "string",
          "description": "On-screen display for live-tune feedback: a brief 'param value' message appears when you sweep a knob or change a mode via MIDI/WLED, then fades. 'top' or 'bottom' picks the corner; 'off' disables it. Rendered pre-quantization so it shows on every display mode (like --frame-numbers).",
          "enum": [
            "bottom",
            "top",
            "off"
          ],
          "default": "bottom"
        },
        "loop_audio": {
          "type": "string",
          "description": "What happens to a video's audio once a transport.* action touches the scene: 'on' (default) keeps audio playing and re-syncs it across every seek/pause/loop splice; 'mute' restores the Phase-2 escape valve (audio mutes for the rest of that scene's run). Falls back to mute behavior automatically when the scene has no audio. The REU-pump audio path is always forced off under transport regardless.",
          "enum": [
            "on",
            "mute"
          ],
          "default": "on"
        },
        "cc_map": {
          "type": "array",
          "description": "MIDI-message -> action mappings ([[midi_control.cc_map]] tables); see --describe section:midi_control. Set to [] to disable the shipped defaults, or override/extend individual entries. Each entry: type ('cc'|'note'|'pc'|'mmc'), number (0-127 for cc/note/pc; an MMC command byte \u2014 0x01 stop, 0x02 play, 0x04 FF, 0x05 RW, 0x06 record, 0x09 pause \u2014 for mmc), action ('pause'|'resume'|'toggle_pause'|'skip'|'cycle_style'|'jump'|'param'|'transport.play_pause'|'transport.stop'|'transport.loop_toggle'|'transport.rw'|'transport.ff'|'transport.jog'|'transport.record'|'loop_slot'); 'jump' also needs an int scene; 'param' also needs a string target ('effect.<name>', 'source.<name>', 'scene.<name>' for scope scenes, or 'mode.<name>' for the display mode's live color knobs \u2014 dither_strength/method, motion_smoothing, auto_fit_strength, cell_strategy, color_match, palette_mode). A knob (cc) sweeps a scalar or bucket-selects a choice; a note/pad cycles a choice. The transport.* actions give DJ-style control of a playing video scene (pause-in-place, seek, RW/FF with acceleration while a note is held, an A/B loop, and a rotary jog \u2014 'mode' 'abs'|'rel', default 'rel'); once touched, that scene's audio follows every seek/pause/loop by default (see loop_audio, and docs/architecture.md's transport note). A 'mmc' entry also matches an MMC transport SysEx from a DAW/controller. 'transport.record' arms a loop (Record -> Stop workflow, red border while armed); 'loop_slot' also needs an int 'slot' >= 1 (a pad number) and recalls that per-video saved loop on a plain press, saves the current loop into it while Stop is held, or clears it while Record is held (note mappings only \u2014 an mmc record/stop can't reliably hold for the chord, since MMC has no release event). 'look_save'/'look_recall' (Phase 6) each need an int 'slot' >= 1 \u2014 a look captures the active clip + effect-chain state on save and re-fires it on recall.",
          "default": [
            {
              "type": "note",
              "number": 36,
              "action": "skip"
            },
            {
              "type": "note",
              "number": 37,
              "action": "cycle_style"
            },
            {
              "type": "note",
              "number": 38,
              "action": "toggle_pause"
            },
            {
              "type": "note",
              "number": 39,
              "action": "jump",
              "scene": 0
            },
            {
              "type": "note",
              "number": 40,
              "action": "jump",
              "scene": 0
            },
            {
              "type": "note",
              "number": 41,
              "action": "jump",
              "scene": 1
            },
            {
              "type": "note",
              "number": 42,
              "action": "jump",
              "scene": 2
            },
            {
              "type": "note",
              "number": 43,
              "action": "jump",
              "scene": 3
            },
            {
              "type": "note",
              "number": 44,
              "action": "jump",
              "scene": 4
            },
            {
              "type": "note",
              "number": 45,
              "action": "jump",
              "scene": 5
            },
            {
              "type": "note",
              "number": 46,
              "action": "jump",
              "scene": 6
            },
            {
              "type": "note",
              "number": 47,
              "action": "jump",
              "scene": 7
            },
            {
              "type": "note",
              "number": 48,
              "action": "jump",
              "scene": 8
            },
            {
              "type": "note",
              "number": 49,
              "action": "jump",
              "scene": 9
            },
            {
              "type": "note",
              "number": 50,
              "action": "jump",
              "scene": 10
            },
            {
              "type": "note",
              "number": 51,
              "action": "jump",
              "scene": 11
            },
            {
              "type": "note",
              "number": 52,
              "action": "jump",
              "scene": 12
            },
            {
              "type": "note",
              "number": 53,
              "action": "jump",
              "scene": 13
            },
            {
              "type": "note",
              "number": 54,
              "action": "jump",
              "scene": 14
            },
            {
              "type": "note",
              "number": 55,
              "action": "jump",
              "scene": 15
            },
            {
              "type": "pc",
              "number": 0,
              "action": "jump",
              "scene": 0
            },
            {
              "type": "pc",
              "number": 1,
              "action": "jump",
              "scene": 1
            },
            {
              "type": "pc",
              "number": 2,
              "action": "jump",
              "scene": 2
            },
            {
              "type": "pc",
              "number": 3,
              "action": "jump",
              "scene": 3
            },
            {
              "type": "pc",
              "number": 4,
              "action": "jump",
              "scene": 4
            },
            {
              "type": "pc",
              "number": 5,
              "action": "jump",
              "scene": 5
            },
            {
              "type": "pc",
              "number": 6,
              "action": "jump",
              "scene": 6
            },
            {
              "type": "pc",
              "number": 7,
              "action": "jump",
              "scene": 7
            },
            {
              "type": "pc",
              "number": 8,
              "action": "jump",
              "scene": 8
            },
            {
              "type": "pc",
              "number": 9,
              "action": "jump",
              "scene": 9
            },
            {
              "type": "pc",
              "number": 10,
              "action": "jump",
              "scene": 10
            },
            {
              "type": "pc",
              "number": 11,
              "action": "jump",
              "scene": 11
            },
            {
              "type": "pc",
              "number": 12,
              "action": "jump",
              "scene": 12
            },
            {
              "type": "pc",
              "number": 13,
              "action": "jump",
              "scene": 13
            },
            {
              "type": "pc",
              "number": 14,
              "action": "jump",
              "scene": 14
            },
            {
              "type": "pc",
              "number": 15,
              "action": "jump",
              "scene": 15
            },
            {
              "type": "cc",
              "number": 13,
              "action": "param",
              "target": "effect.decay"
            },
            {
              "type": "cc",
              "number": 14,
              "action": "param",
              "target": "source.speed"
            },
            {
              "type": "cc",
              "number": 15,
              "action": "param",
              "target": "source.scale"
            },
            {
              "type": "cc",
              "number": 16,
              "action": "param",
              "target": "source.scroll_speed"
            }
          ]
        },
        "controller_profile": {
          "type": "string",
          "description": "Which learned controller profile (from --midi-setup) to layer under this config's cc_map. 'auto' (default) loads the stored profile whose learned port name matches the opened MIDI port; a '<name>' loads that named profile (the file stem under the controllers data dir); 'off' ignores profiles entirely. Merge precedence is shipped-defaults < profile < an explicit cc_map here: with no cc_map set, a profile can reclaim the default note/CC assignments; an explicit cc_map (including []) always wins over the profile. Requires [midi_control] to be enabled; needs no extra.",
          "default": "auto"
        }
      }
    },
    "performance": {
      "type": "object",
      "description": "Live-performance tempo/beat grid: follow an external MIDI clock or free-run at a static/tapped BPM (drives launch quantization + tempo-locked effects).",
      "additionalProperties": false,
      "properties": {
        "tempo_source": {
          "type": "string",
          "description": "Where the beat grid gets its tempo: 'internal' (free-run at `bpm`, with a `tempo_tap` pad for live tapping), 'midi' (follow an external MIDI clock \u2014 0xF8 clock / start / stop / song-position \u2014 which arrives via the [midi_control] listener, so enable that too), or 'audio' (lock to the beat the live-input analyzer detects \u2014 the audio_source = 'mic'/'listen' scene's reactive tempo drives launch quantize, mod_source='clock' effects and WLED tempo). With 'midi' or 'audio' the grid idles until the first clock byte / detected tempo.",
          "enum": [
            "internal",
            "midi",
            "audio"
          ],
          "default": "internal"
        },
        "bpm": {
          "type": "number",
          "description": "Static tempo (beats per minute) for internal drive, and the starting tempo before an external clock is measured. A tap-tempo pad overrides it live.",
          "default": 120.0
        },
        "beats_per_bar": {
          "type": "integer",
          "description": "Beats per bar (the numerator of the time signature) \u2014 sets where bar boundaries fall for bar-quantized launches and bar-locked effects.",
          "default": 4
        },
        "clock_port": {
          "type": [
            "string",
            "null"
          ],
          "description": "MIDI input port to read the external clock from when it arrives on a DIFFERENT port than the [midi_control] control surface (substring match, case-insensitive). None (default) = read clock on the same port as control. Only used when tempo_source = 'midi'."
        },
        "midi_feedback": {
          "type": "boolean",
          "description": "Light a grid controller's pads to show performance state (Live DJ/VJ Phase 4): loaded clip pads dim, the arming pad blinks, the live clip bright, and enabled effect-chain layers lit \u2014 all over a MIDI OUTPUT port ([midi_control] must be enabled). The C64 screen stays audience-facing; this replaces on-screen readouts with controller LEDs. The velocity->color convention is per-controller and comes from the learned controller profile's `feedback` block (--midi-setup writes it); Launchpad-X palette defaults otherwise. Needs a grid that lights pads from note-on velocity (Novation Launchpad, Akai APC/MPC, Ableton Push); Arturia and other SysEx-only controllers won't light \u2014 use the web console for those.",
          "default": false
        },
        "feedback_port": {
          "type": [
            "string",
            "null"
          ],
          "description": "MIDI OUTPUT port for LED feedback (substring match, case-insensitive). None (default) = the profile's own port, else the same device as the [midi_control] input, else the first output. Only used when midi_feedback = true."
        },
        "clips": {
          "type": "array",
          "description": "Clip-launch grid ([[performance.clips]], Live DJ/VJ Phase 2): each table is a scene spec (any [[scenes]] field \u2014 type, file, source, display, name, duration_s, effect \u2026) plus launch semantics: `slot` (1-based id, unique), `pad`/`pad_type` (the note/PC number that fires it, auto-mapped when [midi_control] is on), `launch` (\"trigger\"|\"gate\"|\"toggle\"), `quantize` (\"off\"|\"beat\"|\"bar\" \u2014 align the swap to the beat grid), and `loop` (repeat until another clip fires). Fired from a controller or the web console; the scene is built on a background thread during the count-in and swapped in on the grid boundary. Empty = no grid.",
          "default": []
        }
      }
    },
    "menu": {
      "type": "object",
      "description": "On-C64 SPACE-key menu for live scene tweaks.",
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Enable the on-C64 SPACE-key menu for live scene tweaks.",
          "default": false
        },
        "prompt_to_save": {
          "type": "boolean",
          "description": "On menu exit with unsaved changes, offer to write them back to the source config file. False = apply to the running scene only, never persist (handy for conventions/demos).",
          "default": true
        }
      }
    },
    "wled": {
      "type": "object",
      "description": "Two-directional WLED bridge: broadcast SID audio-sync out (Mode 3) and/or act as a virtual WLED device the app can control (Mode 1).",
      "additionalProperties": false,
      "properties": {
        "broadcast": {
          "type": [
            "string",
            "null"
          ],
          "description": "Mode 3 (audio-sync out). 'disabled' (default) | 'enabled' | '[host][:port]'. 'enabled' multicasts to WLED's default group 239.0.0.1:11988 (every WLED with 'Receive' enabled reacts); give a unicast '[host][:port]' to target one device."
        },
        "rate_hz": {
          "type": "number",
          "description": "Broadcast rate in Hz (Mode 3). WLED expects roughly frame-rate updates; ~40-60 is typical.",
          "default": 50.0
        },
        "broadcast_tempo_fallback": {
          "type": "boolean",
          "description": "Mode 3 performance glue (Live DJ/VJ Phase 6): when the on-screen scene has NO SID features to broadcast (a video, webcam, or slideshow), fall back to the [performance] beat grid so WLED strips keep pulsing to the MIDI/tap tempo instead of going dark. The synthesized pulse spikes on each beat (from the TempoClock phase); only active while the grid is running. Off (default) = a non-SID scene broadcasts nothing, matching pre-Phase-6 behavior. A SID-driven scene always wins over the fallback.",
          "default": false
        },
        "listen": {
          "type": [
            "string",
            "null"
          ],
          "description": "Mode 1 (control surface in). 'disabled' (default) | 'enabled' | '[host][:port]'. 'enabled' binds the WLED JSON API on 0.0.0.0:8080; override the bind with '[host][:port]'. Needs the 'wled' extra."
        },
        "name": {
          "type": "string",
          "description": "Friendly/mDNS device name advertised in Mode 1 (what the WLED app shows for this virtual device).",
          "default": "c64cast"
        }
      }
    },
    "scenes": {
      "type": "array",
      "description": "Playlist scenes ([[scenes]] blocks).",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "description": "Scene kind.",
            "enum": [
              "webcam",
              "blank",
              "video",
              "waveform",
              "midi",
              "asid",
              "slideshow",
              "launcher",
              "generative",
              "wled"
            ],
            "default": "webcam"
          },
          "display": {
            "type": [
              "string",
              "null"
            ],
            "description": "VIC-II display mode. Unset resolves per scene type: 'mhires' for video (richest bitmap mode, suits arbitrary film/photo content) and 'hires_edges' for webcam/blank/slideshow/generative (tuned for live Canny-edge stylization). waveform and midi are bitmap-only (both ignore this); slideshow also accepts 'random'. generative renders a frame so any quantizing mode works (not 'blank'/'random').",
            "enum": [
              "hires_edges",
              "hires",
              "petscii",
              "mcm",
              "mhires",
              "blank",
              "random"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name (shown in interstitials/logs; ensemble match key)."
          },
          "duration_s": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds before auto-advance; 0 = run forever. Unset = scene-type default (webcam/blank run forever when they're the only scene, else 30s; waveform = song length or 30s; slideshow/generative = 30s). Video scenes reject this (they run until the file ends). For launcher this is the idle timeout (reset by player input)."
          },
          "target_fps": {
            "type": [
              "number",
              "null"
            ],
            "description": "Per-scene frame-rate cap; unset = playlist default (60/50). Bitmap (hires/mhires) video/webcam/generative scenes default lower to stay under the DMA bus-halt ceiling: 20 fps while streaming digitized audio, else half rate (30/25). Generative and webcam scenes take that 20 fps cap in CHAR modes too whenever audio is on the 4-bit DAC \u2014 they repaint every tick (no dedup), so the frame writes contend with the audio ring for the DMA socket. Off-bus Ultimate Audio sampler playback keeps the high default. Waveform/midi/asid default to half rate too."
          },
          "audio": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Per-scene audio override. Unset follows [audio].enabled; false mutes this scene only."
          },
          "effect": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pixel effect applied to the frame before quantization (unset = none). Works on any frame-bearing scene. 'trails' echoes moving content; 'pulse' beat-punches the zoom; 'rgb_shift' slews the color channels apart on a transient. pulse/rgb_shift only visibly react on a music-reactive scene (generative + audio_source = 'sid'); elsewhere they're inert (no feature stream to react to).",
            "enum": [
              "trails",
              "pulse",
              "rgb_shift",
              "blur",
              "strobe",
              "invert",
              "mirror",
              "posterize"
            ]
          },
          "effects": {
            "type": "array",
            "description": "Ordered pixel-effect chain applied before quantization, e.g. effects = [\"trails\", \"rgb_shift\", \"strobe\"]. Each is one of the `effect` choices; layers apply in order and are individually tunable (map a CC to fx0.<param>/fx1.<param>\u2026) and bypass-toggleable live (fx_toggle). Mutually exclusive with the single `effect` field. Empty = none.",
            "items": {
              "type": "string",
              "enum": [
                "trails",
                "pulse",
                "rgb_shift",
                "blur",
                "strobe",
                "invert",
                "mirror",
                "posterize"
              ]
            },
            "default": []
          },
          "mod_source": {
            "type": "string",
            "description": "What drives this scene's reactive effect layers: 'audio' (the SID feature stream \u2014 needs a music-reactive scene, i.e. generative + audio_source = 'sid'), 'clock' (the [performance] beat grid, so effects lock to MIDI/tap tempo on any scene \u2014 the way to tempo-lock a 'strobe'), or 'off' (never react \u2014 layers use their static baseline). Applies to every effect layer on the scene.",
            "enum": [
              "audio",
              "clock",
              "off"
            ],
            "default": "audio"
          },
          "pre_emphasis": {
            "type": [
              "number",
              "null"
            ],
            "description": "Per-scene HF pre-emphasis (0 = off, ~0.3-0.7 typical; brightens speech). Unset = global [dsp].pre_emphasis / source-aware default. Needs [dsp].enabled + scene audio."
          },
          "palette_mode": {
            "type": "string",
            "description": "VIC-II slot-allocation strategy for mcm/mhires display (ignored by other modes): percell (default), cheap, vivid, grayscale. Color shaping (channel boost + hue corrections, e.g. the purple rescue) is the global [color] section, applied to every mode.",
            "enum": [
              "percell",
              "cheap",
              "vivid",
              "grayscale"
            ],
            "default": "percell"
          },
          "text_double_height": {
            "type": "boolean",
            "description": "On mhires, render text overlays (clock/marquee/\u2026) at double height \u2014 16px / 2 cell rows \u2014 for across-the-room legibility. Text is always double-WIDE on mhires (8x8 glyph spans 2 of the 4px cells); this toggle adds the vertical stretch. Ignored on other display modes.",
            "default": false
          },
          "style": {
            "type": "string",
            "description": "PETSCII glyph/color style (only when display = 'petscii'); 'random' picks one at setup.",
            "enum": [
              "default",
              "halftone",
              "random_glyph",
              "letter_rain",
              "neon",
              "inverse_pop",
              "hatch",
              "color_only",
              "random"
            ],
            "default": "default"
          },
          "overlays": {
            "type": "array",
            "description": "List of overlay tables ([[scenes.overlays]]); see --list-overlays.",
            "items": {
              "type": "object",
              "required": [
                "type"
              ],
              "properties": {
                "type": {
                  "description": "Overlay kind.",
                  "enum": [
                    "big_text",
                    "callsign",
                    "clock",
                    "countdown",
                    "logo",
                    "marquee",
                    "network",
                    "obs_status",
                    "rss",
                    "scrolling_text",
                    "spectrum_bitmap",
                    "spectrum_petscii",
                    "weather"
                  ]
                }
              },
              "allOf": [
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "big_text"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "big_text"
                      },
                      "messages": {
                        "type": "array",
                        "description": "List of message strings (or {text, color} tables) to scroll."
                      },
                      "charset_path": {
                        "type": "string",
                        "description": "C64 character ROM used to rasterize the big glyphs.",
                        "default": "assets/roms/characters.901225-01.bin"
                      },
                      "row": {
                        "type": "string",
                        "description": "Vertical placement: 'top', 'middle', or 'bottom'.",
                        "default": "middle"
                      },
                      "speed_cells_per_s": {
                        "type": "number",
                        "description": "Scroll speed in character cells per second.",
                        "default": 8.0
                      },
                      "inter_message_pause_s": {
                        "type": "number",
                        "description": "Pause between consecutive messages.",
                        "default": 1.5
                      },
                      "loop": {
                        "type": "boolean",
                        "description": "Loop the message list forever (false = play once then advance).",
                        "default": true
                      },
                      "target_fps": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "Override FPS used for px-per-frame snapping; unset = detect."
                      }
                    },
                    "required": [
                      "type",
                      "messages"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "callsign"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "callsign"
                      },
                      "text": {
                        "type": "string",
                        "description": "The fixed string to display.",
                        "default": ""
                      },
                      "corner": {
                        "type": "string",
                        "description": "Screen corner to anchor the text (top-left/top-right/bottom-left/bottom-right).",
                        "default": "bottom-right"
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "white"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Cell background color, or 'none' to leave the scene showing through.",
                        "default": "black"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "clock"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "clock"
                      },
                      "corner": {
                        "type": "string",
                        "description": "Screen corner to anchor the text (top-left/top-right/bottom-left/bottom-right).",
                        "default": "top-right"
                      },
                      "format": {
                        "type": "string",
                        "description": "strftime format for the time line (e.g. '%H:%M').",
                        "default": "%H:%M"
                      },
                      "show_date": {
                        "type": "boolean",
                        "description": "Also show a second line with the date.",
                        "default": false
                      },
                      "date_format": {
                        "type": "string",
                        "description": "strftime format for the date line when show_date is true.",
                        "default": "%Y-%m-%d"
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "white"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Cell background color, or 'none' to leave the scene showing through.",
                        "default": "black"
                      },
                      "refresh_s": {
                        "type": "number",
                        "description": "Seconds between value recomputes (the text is repainted every frame).",
                        "default": 1.0
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "countdown"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "countdown"
                      },
                      "target": {
                        "type": "string",
                        "description": "Target datetime (ISO 8601, e.g. '2026-12-31T23:59')."
                      },
                      "format": {
                        "type": "string",
                        "description": "'auto' for adaptive units, or a template using {d}{h}{m}{s}.",
                        "default": "auto"
                      },
                      "done_text": {
                        "type": "string",
                        "description": "Text shown once the target has passed.",
                        "default": "DONE"
                      },
                      "corner": {
                        "type": "string",
                        "description": "Screen corner to anchor the text (top-left/top-right/bottom-left/bottom-right).",
                        "default": "bottom-left"
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "yellow"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Cell background color, or 'none' to leave the scene showing through.",
                        "default": "black"
                      },
                      "refresh_s": {
                        "type": "number",
                        "description": "Seconds between value recomputes (the text is repainted every frame).",
                        "default": 1.0
                      }
                    },
                    "required": [
                      "type",
                      "target"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "logo"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "logo"
                      },
                      "file": {
                        "type": "string",
                        "description": "Path to a .txt file of PETSCII art (one screen row per line)."
                      },
                      "corner": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Corner to anchor the block (mutually exclusive with row/col)."
                      },
                      "row": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "description": "Explicit top row (use with col instead of corner)."
                      },
                      "col": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "description": "Explicit left column (use with row instead of corner)."
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Art color (C64 color name).",
                        "default": "white"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Background color, or 'none' to leave the scene showing through.",
                        "default": "black"
                      }
                    },
                    "required": [
                      "type",
                      "file"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "marquee"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "marquee"
                      },
                      "text": {
                        "type": "string",
                        "description": "The message to scroll continuously.",
                        "default": "C64CAST"
                      },
                      "row": {
                        "type": "integer",
                        "description": "Screen row (0..24) the ticker scrolls along.",
                        "default": 0
                      },
                      "speed_cells_per_s": {
                        "type": "number",
                        "description": "Scroll speed in character cells per second.",
                        "default": 3.0
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "yellow"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Background color (C64 color name).",
                        "default": "black"
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "network"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "network"
                      },
                      "items": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "description": "Which lines to show, any of: 'ip', 'hostname', 'ping'."
                      },
                      "corner": {
                        "type": "string",
                        "description": "Screen corner to anchor the text (top-left/top-right/bottom-left/bottom-right).",
                        "default": "bottom-right"
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "light gray"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Cell background color, or 'none' to leave the scene showing through.",
                        "default": "black"
                      },
                      "refresh_s": {
                        "type": "number",
                        "description": "Seconds between value recomputes (the text is repainted every frame).",
                        "default": 5.0
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "obs_status"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "obs_status"
                      },
                      "host": {
                        "type": "string",
                        "description": "OBS WebSocket host.",
                        "default": "localhost"
                      },
                      "port": {
                        "type": "integer",
                        "description": "OBS WebSocket port.",
                        "default": 4455
                      },
                      "password": {
                        "type": "string",
                        "description": "OBS WebSocket password (if auth is enabled).",
                        "default": ""
                      },
                      "show_dropped": {
                        "type": "boolean",
                        "description": "Append the dropped-frame count to the status line.",
                        "default": true
                      },
                      "corner": {
                        "type": "string",
                        "description": "Screen corner to anchor the text (top-left/top-right/bottom-left/bottom-right).",
                        "default": "bottom-right"
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "light green"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Cell background color, or 'none' to leave the scene showing through.",
                        "default": "black"
                      },
                      "refresh_s": {
                        "type": "number",
                        "description": "Seconds between value recomputes (the text is repainted every frame).",
                        "default": 2.0
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "rss"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "rss"
                      },
                      "url": {
                        "type": "string",
                        "description": "RSS/Atom feed URL to fetch."
                      },
                      "row": {
                        "type": "integer",
                        "description": "Screen row (0..24) the ticker scrolls along.",
                        "default": 0
                      },
                      "max_items": {
                        "type": "integer",
                        "description": "Maximum number of headlines to include in the ticker.",
                        "default": 10
                      },
                      "refresh_minutes": {
                        "type": "number",
                        "description": "Minutes between background feed fetches.",
                        "default": 15.0
                      },
                      "speed_cells_per_s": {
                        "type": "number",
                        "description": "Scroll speed in character cells per second.",
                        "default": 3.0
                      },
                      "separator": {
                        "type": "string",
                        "description": "Text placed between consecutive headlines.",
                        "default": "   *   "
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "light green"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Background color (C64 color name).",
                        "default": "black"
                      }
                    },
                    "required": [
                      "type",
                      "url"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "scrolling_text"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "scrolling_text"
                      },
                      "messages": {
                        "type": "array",
                        "description": "List of message strings to cycle through."
                      },
                      "row": {
                        "type": "integer",
                        "description": "Screen row (0..24) to scroll along.",
                        "default": 24
                      },
                      "speed_cells_per_s": {
                        "type": "number",
                        "description": "Scroll speed in character cells per second.",
                        "default": 6.0
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Background color (C64 color name).",
                        "default": "black"
                      }
                    },
                    "required": [
                      "type",
                      "messages"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "spectrum_bitmap"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "spectrum_bitmap"
                      },
                      "placement": {
                        "type": "string",
                        "description": "Where the bars sit: 'bottom', 'center', or 'split'.",
                        "default": "bottom"
                      },
                      "height_frac": {
                        "type": "number",
                        "description": "Fraction of screen height a full-energy bar reaches.",
                        "default": 0.5
                      },
                      "gain": {
                        "type": "number",
                        "description": "Multiplier applied to band magnitudes before bar height.",
                        "default": 1.0
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "spectrum_petscii"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "spectrum_petscii"
                      },
                      "placement": {
                        "type": "string",
                        "description": "Where the bars sit: 'bottom', 'center', or 'split'.",
                        "default": "center"
                      },
                      "height_rows": {
                        "type": "integer",
                        "description": "Height of the bar strip in character rows.",
                        "default": 12
                      },
                      "gain": {
                        "type": "number",
                        "description": "Multiplier applied to band magnitudes before bar height.",
                        "default": 1.0
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                },
                {
                  "if": {
                    "properties": {
                      "type": {
                        "const": "weather"
                      }
                    },
                    "required": [
                      "type"
                    ]
                  },
                  "then": {
                    "properties": {
                      "type": {
                        "const": "weather"
                      },
                      "provider": {
                        "type": "string",
                        "description": "Weather source: 'open-meteo' or 'wttr.in'.",
                        "default": "open-meteo"
                      },
                      "lat": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "Latitude (open-meteo; with lon)."
                      },
                      "lon": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "Longitude (open-meteo; with lat)."
                      },
                      "location": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Location name (wttr.in; alternative to lat/lon)."
                      },
                      "units": {
                        "type": "string",
                        "description": "Temperature units: 'F' or 'C'.",
                        "default": "F"
                      },
                      "corner": {
                        "type": "string",
                        "description": "Screen corner to anchor the text (top-left/top-right/bottom-left/bottom-right).",
                        "default": "top-left"
                      },
                      "fg_color": {
                        "type": "string",
                        "description": "Text color (C64 color name).",
                        "default": "light blue"
                      },
                      "bg_color": {
                        "type": "string",
                        "description": "Cell background color, or 'none' to leave the scene showing through.",
                        "default": "black"
                      },
                      "refresh_minutes": {
                        "type": "number",
                        "description": "Minutes between background weather polls.",
                        "default": 10.0
                      }
                    },
                    "required": [
                      "type"
                    ],
                    "additionalProperties": false
                  }
                }
              ]
            }
          },
          "orchestrate": {
            "type": "boolean",
            "description": "Ensemble: make this system the conductor and broadcast this scene to all others (requires name; ignored single-system).",
            "default": false
          },
          "follower_only": {
            "type": "boolean",
            "description": "Ensemble: exclude from normal rotation; used only as a broadcast follower override (requires name; excludes orchestrate).",
            "default": false
          },
          "border": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Border color (blank scenes): a C64 color name (fuzzy + case-insensitive, e.g. \"light blue\") or a palette index 0..15.",
            "default": 0
          },
          "background": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Background color (blank scenes): a C64 color name (fuzzy + case-insensitive, e.g. \"light blue\") or a palette index 0..15.",
            "default": 0
          },
          "file": {
            "type": [
              "string",
              "null"
            ],
            "description": "Asset spec (comma-separated paths/dirs/globs). Videos for video, .sid for waveform, images for slideshow, .prg/.crt for launcher, .sid for generative when audio_source = sid."
          },
          "start_s": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds into the source to begin playback (video only). Quick playback fills this from a URL's t=/start= timestamp; can also be set directly on a [[scenes]] video. Unset/0 = play from the start."
          },
          "song": {
            "type": "integer",
            "description": "SID subtune index to play (0 = the SID's default; 1-based otherwise). For generative scenes, only with audio_source = sid.",
            "default": 0
          },
          "color_mode": {
            "type": "string",
            "description": "Oscilloscope coloring: fixed per voice, or by current waveform type.",
            "enum": [
              "per_voice",
              "per_waveform"
            ],
            "default": "per_voice"
          },
          "voice_colors": {
            "type": "array",
            "description": "Per-voice trace colors (C64 color names) for color_mode=per_voice.",
            "default": []
          },
          "waveform_colors": {
            "type": "object",
            "description": "Per-waveform-type colors (e.g. pulse=cyan) for color_mode=per_waveform.",
            "default": {}
          },
          "time_base": {
            "type": "string",
            "description": "Scope time window: 'wallclock' (1 row = 1 frame) or 'auto' (per-voice window sized so auto_cycles cycles fit).",
            "enum": [
              "wallclock",
              "auto"
            ],
            "default": "wallclock"
          },
          "auto_cycles": {
            "type": "number",
            "description": "Complete cycles per render window when time_base = 'auto'.",
            "default": 4.0
          },
          "persistence": {
            "type": "string",
            "description": "Trace decay/trail length ('off' redraws each frame).",
            "enum": [
              "off",
              "short",
              "medium",
              "long",
              "random"
            ],
            "default": "off"
          },
          "scroll_columns": {
            "type": [
              "integer",
              "array"
            ],
            "description": "FIFO-scroll the strip left by N columns/frame (0 = redraw). Int or a list of 3 per-voice ints.",
            "default": 0
          },
          "midi_port": {
            "type": [
              "string",
              "null"
            ],
            "description": "MIDI input port name substring; unset = first available port."
          },
          "midi_waveform": {
            "type": "string",
            "description": "Default SID waveform for MIDI notes (the starting waveform for every voice; SHIFT cycles it, incl. into combined waveforms).",
            "enum": [
              "triangle",
              "sawtooth",
              "pulse",
              "noise"
            ],
            "default": "pulse"
          },
          "midi_voice_waveforms": {
            "type": "array",
            "description": "Per-voice starting waveforms (up to 3, e.g. ['pulse', 'sawtooth', 'triangle']). Each entry is one waveform or a '+'-combo. 'pulse+triangle' is the combined wave that reliably sounds on a 6581; sawtooth combos AND down to near-silence there (audible may differ on 8580). Empty = every voice uses midi_waveform; fewer than 3 repeats the last.",
            "default": []
          },
          "midi_voice_mode": {
            "type": "string",
            "description": "Voice allocation: 'shared' = one MIDI channel spread across the 3 voices (mono melody over a sustain pad); 'multitimbral' = MIDI channels route to fixed voices (see midi_voice_channels).",
            "enum": [
              "shared",
              "multitimbral"
            ],
            "default": "shared"
          },
          "midi_voice_channels": {
            "type": "array",
            "description": "Multitimbral channel\u2192voice map: MIDI channels (1..16) for voices 1/2/3, in order. Only used when midi_voice_mode = 'multitimbral'; notes on other channels are ignored.",
            "default": [
              1,
              2,
              3
            ]
          },
          "midi_program_change": {
            "type": "boolean",
            "description": "Honor MIDI Program Change to select a voice's waveform (shared mode = all voices; multitimbral = the message's channel).",
            "default": true
          },
          "midi_adsr": {
            "type": "array",
            "description": "ADSR envelope as [attack, decay, sustain, release] (4 nibbles 0..15).",
            "default": [
              0,
              8,
              12,
              8
            ]
          },
          "midi_pulse_width": {
            "type": "integer",
            "description": "SID pulse width (0..4095) when midi_waveform = 'pulse'. Swept live by CC1 (mod wheel).",
            "default": 2048
          },
          "midi_filter_cutoff": {
            "type": "integer",
            "description": "SID filter cutoff (0..2047); all voices are routed through the filter. Default open (neutral lowpass); swept live by CC74.",
            "default": 2047
          },
          "midi_filter_resonance": {
            "type": "integer",
            "description": "SID filter resonance (0..15) for MIDI notes; swept live by CC71.",
            "default": 0
          },
          "midi_filter_mode": {
            "type": "string",
            "description": "SID filter mode for MIDI notes.",
            "enum": [
              "lowpass",
              "bandpass",
              "highpass"
            ],
            "default": "lowpass"
          },
          "midi_master_volume": {
            "type": "integer",
            "description": "SID master volume nibble (0..15) for MIDI notes; CC7.",
            "default": 15
          },
          "asid_port": {
            "type": [
              "string",
              "null"
            ],
            "description": "MIDI input port name substring the ASID host streams to; unset = first available port."
          },
          "asid_multi_sid": {
            "type": "boolean",
            "description": "Honor ASID multi-SID streams (commands 0x50-0x5F) by configuring the U64 for multiple SIDs and routing each chip to its own address (prefers physical socket SIDs). U64 only \u2014 ignored on backends without the config API, where extra chips downmix to the primary SID.",
            "default": true
          },
          "asid_max_sids": {
            "type": "integer",
            "description": "Cap on the number of SID chips a multi-SID ASID stream may map on the U64 (1-8). Chips beyond the cap downmix to the primary SID.",
            "default": 8
          },
          "asid_buffered_player": {
            "type": "string",
            "description": "Cycle-accurate buffered playback: consume ASID frames on a C64-side REU ring player (CIA #1 Timer A IRQ) instead of coalescing block writes on the host. Fixes dropped frames on multispeed tunes (0x31 up to 16x) \u2014 arps/vibrato/hard restarts survive \u2014 and honors the 0x30 write-order/wait recipe. U64 only (needs a bus-clean REU): 'auto' = on when the backend has an REU, else the coalesced path; 'on' = force it (warns + falls back on a no-REU backend); 'off' = always coalesce.",
            "enum": [
              "auto",
              "on",
              "off"
            ],
            "default": "auto"
          },
          "image_duration_s": {
            "type": "number",
            "description": "Per-image dwell time before advancing (total runtime is duration_s).",
            "default": 5.0
          },
          "aspect_mode": {
            "type": "string",
            "description": "How each image is fit to the C64 4:2.5 aspect: 'crop' (center-crop to fill \u2014 the default, edges lost), 'fit' (letterbox/pillarbox so the whole image shows, padded black), or 'stretch' (distort to fill, no padding or cropping).",
            "enum": [
              "crop",
              "fit",
              "stretch"
            ],
            "default": "crop"
          },
          "input_source": {
            "type": "string",
            "description": "What counts as player input to reset the idle timeout: 'cia' (joystick bits at $DC00/$DC01), 'kernal' ($00C5/$00C6, only live while the kernal IRQ runs), 'auto' (both), or 'none' (pure timer, for demos). Never counts C=/SHIFT/CTRL.",
            "enum": [
              "cia",
              "kernal",
              "auto",
              "none"
            ],
            "default": "cia"
          },
          "max_duration_s": {
            "type": [
              "number",
              "null"
            ],
            "description": "Hard ceiling in seconds \u2014 advance regardless of input. Unset = no cap (a continuously-played game runs forever)."
          },
          "min_duration_s": {
            "type": "number",
            "description": "Floor in seconds before the idle timeout can advance the scene, even if no input is seen.",
            "default": 0.0
          },
          "reset_before_launch": {
            "type": "boolean",
            "description": "Reset the U64 before launching for a clean machine state.",
            "default": true
          },
          "bypass_audio_lock": {
            "type": "boolean",
            "description": "Ensemble: don't contend for the exclusive audio slot \u2014 the launched program drives its own SID concurrently, so several people can play (and hear) their own games at once. No effect single-system.",
            "default": false
          },
          "source": {
            "type": "string",
            "description": "Generative video source to render (generative scenes only).",
            "enum": [
              "plasma",
              "tunnel",
              "fire",
              "mandelbrot",
              "moire2",
              "halo",
              "epicycle",
              "hopalong",
              "rorschach",
              "hiphotic",
              "metaballs",
              "rotozoomer",
              "lissajous",
              "dna",
              "drift",
              "colored_bursts",
              "dotswarm",
              "game_of_life",
              "soap",
              "fireworks"
            ],
            "default": "plasma"
          },
          "audio_source": {
            "type": "string",
            "description": "Audio for a generative scene: 'none' = silent (default); 'mic' = live audio input \u2014 an instrument/mixer feed via an interface, or a mic \u2014 streamed to the 4-bit DAC and analyzed; 'listen' = analyze the live input for reactive visuals ONLY, with no C64 audio output (the VJ case: the real sound is on a PA and only the visuals track it \u2014 and, freed from the DAC rate, it captures full-bandwidth at [audio_features].listen_sample_rate); 'sid' = play the `file` .sid on the real chip. 'mic'/'listen' need [audio].enabled for the capture subsystem. 'mic', 'listen' and 'sid' all drive reactive visuals (see `reactive`); the input analyzer is tunable under [audio_features]. A SID source forces a host-DMA display and needs a char display (petscii/mcm) for most tunes (see `file`).",
            "enum": [
              "none",
              "mic",
              "listen",
              "file",
              "sid"
            ],
            "default": "none"
          },
          "reactive": {
            "type": "boolean",
            "description": "Generative scene: let the music drive the visuals \u2014 BPM cycles the colors, transients pulse them, bass reads differently from treble. Works with audio_source = 'sid' (a host-side SID emulator supplies the features, adding no U64 traffic) and 'mic'/'listen' (the live input is analyzed on the host \u2014 see [audio_features]); inert for 'none'. Set false to keep the pure time-driven look (and, for 'listen', to skip capture entirely).",
            "default": true
          },
          "sink_width": {
            "type": "integer",
            "description": "WLED sink: virtual LED-matrix width in pixels a sender streams to (wled scenes only). Must match the sender's configured matrix; the display mode downscales it to the C64. Default 320.",
            "default": 320
          },
          "sink_height": {
            "type": "integer",
            "description": "WLED sink: virtual LED-matrix height in pixels a sender streams to (wled scenes only). Must match the sender's configured matrix; the display mode downscales it to the C64. Default 200.",
            "default": 200
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "type": {
                  "const": "webcam"
                }
              },
              "required": [
                "type"
              ]
            },
            "then": {
              "properties": {
                "display": {
                  "enum": [
                    "hires_edges",
                    "hires",
                    "mhires",
                    "mcm",
                    "petscii",
                    "blank"
                  ]
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "type": {
                  "const": "blank"
                }
              },
              "required": [
                "type"
              ]
            },
            "then": {
              "properties": {
                "display": {
                  "enum": [
                    "blank",
                    "hires_edges"
                  ]
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "type": {
                  "const": "video"
                }
              },
              "required": [
                "type"
              ]
            },
            "then": {
              "properties": {
                "display": {
                  "enum": [
                    "mhires",
                    "hires_edges",
                    "hires",
                    "mcm",
                    "petscii",
                    "blank"
                  ]
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "type": {
                  "const": "slideshow"
                }
              },
              "required": [
                "type"
              ]
            },
            "then": {
              "properties": {
                "display": {
                  "enum": [
                    "mhires",
                    "hires",
                    "hires_edges",
                    "mcm",
                    "petscii",
                    "random"
                  ]
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "type": {
                  "const": "generative"
                }
              },
              "required": [
                "type"
              ]
            },
            "then": {
              "properties": {
                "display": {
                  "enum": [
                    "mhires",
                    "hires",
                    "hires_edges",
                    "mcm",
                    "petscii"
                  ]
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "type": {
                  "const": "wled"
                }
              },
              "required": [
                "type"
              ]
            },
            "then": {
              "properties": {
                "display": {
                  "enum": [
                    "mhires",
                    "hires",
                    "hires_edges",
                    "mcm",
                    "petscii"
                  ]
                }
              }
            }
          }
        ]
      }
    },
    "ensemble": {
      "type": "object",
      "description": "Multi-system ensemble definition (master TOML only)."
    }
  }
}