TCNetOutput.h

// Super Timecode Converter
// Copyright (c) 2026 Fiverecords -- MIT License
// https://github.com/fiverecords/SuperTimecodeConverter
//
// TCNetOutput -- Full TCNet server (broadcast + unicast).
//
// Broadcast:
//   OptIn  (68B,  port 60000, 1Hz)   -- node keepalive
//   Status (300B, port 60000, 1Hz)   -- layer states + track IDs + names
//   Time   (162B, port 60001, 60Hz)  -- playhead ms + beat + state + fader per layer
//
// Unicast server:
//   Listen on port 60000 for slave OptIn broadcasts (discovery)
//   Listen on NodeListenerPort (65023) for Request packets from slaves
//   Respond with Metadata (548B) + Metrics (122B) + Artwork (204, JPEG chunks)
//   Stream Metrics at 30Hz to all known slaves
//
// Packet formats verified against PRO DJ LINK Bridge v1.1 Wireshark capture
// and cross-referenced with TCNet Link Specification V3.5.1B.

#pragma once
#include <JuceHeader.h>
#include "TimecodeCore.h"
#include "NetworkUtils.h"
#include "StcLogoData.h"

#ifdef _WIN32
    #include <winsock2.h>
#else
    #include <sys/socket.h>
    #include <netinet/in.h>
#endif

class TCNetOutput : public juce::Timer
{
public:
    static constexpr int kMaxLayers          = 4;  // Layers 1-4 (matches MagicQ menu options)
    static constexpr int kPacketLayers       = 8;  // Time/Status packet has 8 slots regardless
    static constexpr uint16_t kPortBroadcast = 60000;
    static constexpr uint16_t kPortTime      = 60001;
    static constexpr uint16_t kListenerPort  = 65023;
    static constexpr int kTimerHz            = 60;
    static constexpr int kMaxSlaves          = 8;

    // Layer states (spec)
    static constexpr uint8_t kStateIdle    = 0;
    static constexpr uint8_t kStatePlaying = 3;
    static constexpr uint8_t kStatePaused  = 5;
    static constexpr uint8_t kStateStopped = 6;

    // TC state
    static constexpr uint8_t kTcStopped = 0;
    static constexpr uint8_t kTcRunning = 1;

    // SMPTE modes
    static constexpr uint8_t kSmpte24 = 24;
    static constexpr uint8_t kSmpte25 = 25;
    static constexpr uint8_t kSmpteDf = 29;
    static constexpr uint8_t kSmpte30 = 30;

    // Fake "no track" duration sent when an engine has no real track loaded
    // (Generator, MTC, Art-Net, LTC).
    // Empirical test history with ChamSys MagicQ:
    //   86400000 (24h)        -> rejected as invalid duration
    //   86399000 (23:59:59)   -> rejected as invalid duration
    //   21600000 (6h)         -> rejected as invalid duration
    //   14400000 (4h)         -> rejected as invalid duration
    //  10800000  (3h)         -> rejected as invalid duration
    //   9000000  (2h30)       -> rejected as invalid duration
    //   7200000  (2h)         -> accepted (highest validated value)
    //   3600000  (1h)         -> accepted
    // ChamSys hard limit is somewhere between 2h00 and 2h30. We lock in 2h.
    static constexpr uint32_t kDefaultDurationMs = 7200000;  // 2 hours

    // Message types
    static constexpr uint8_t kMsgOptIn   = 2;
    static constexpr uint8_t kMsgOptOut  = 3;
    static constexpr uint8_t kMsgStatus  = 5;
    static constexpr uint8_t kMsgTimeSync = 10;
    static constexpr uint8_t kMsgError   = 13;
    static constexpr uint8_t kMsgRequest = 20;
    static constexpr uint8_t kMsgApp     = 30;
    static constexpr uint8_t kMsgData    = 200;
    static constexpr uint8_t kMsgTime    = 254;

    struct LayerData
    {
        uint32_t currentTimeMs = 0;
        uint8_t  beatMarker    = 0;
        uint32_t beatNumber    = 0;   // continuously incrementing beat count
        uint8_t  layerState    = kStateIdle;
        uint8_t  tcHours       = 0;
        uint8_t  tcMinutes     = 0;
        uint8_t  tcSeconds     = 0;
        uint8_t  tcFrames      = 0;
        uint8_t  smpteMode     = kSmpte30;   // TCNet SMPTE mode of this layer's H:M:S:F block
        uint8_t  onAir         = 0;     // fader position 0-255 (0=off, >=1=on-air)
        uint32_t trackId       = 0;
        uint32_t bpm100        = 0;
        uint32_t trackLenMs    = 0;    // real duration or kDefaultDurationMs (2 h)
        uint32_t speed         = 0;    // 2^20 fixed-point (1048576 = 100%). Matches Bridge.
        uint8_t  masterPlayerNum = 0;  // Sync Master value: 0=not master, 1-8=master player number
        juce::String artist;
        juce::String title;
        bool metadataDirty     = false;

        // Artwork (JPEG bytes for TCNet type 204 packet)
        std::vector<uint8_t> artworkJpeg;
        bool artworkDirty      = false;

        // Small Waveform cache: 2400 bytes of PWV5-formatted data (2 bytes
        // per entry = 1200 entries: [height, color]). Filled from the CDJ's
        // analysed waveform when available, zeros otherwise.
        std::vector<uint8_t> smallWaveform;  // 2400 bytes
        // Real beat grid from CDJ (beat number, time stamp in ms). When
        // populated, takes priority over BPM-synthesized grid.
        struct RealBeat { uint16_t beatNumber; uint32_t timeMs; uint8_t type; };
        std::vector<RealBeat> realBeatGrid;

        // When a layer becomes active (CDJ connected, Generator playing,
        // etc.) this gets set true. The real Bridge keeps emitting Metrics
        // and Status for any layer that has ever been active, even after
        // the source disappears (layerState transitions to idle but the
        // layer "exists"). This stable identity prevents MagicQ from
        // entering an error state when sources change.
        bool hasEverBeenActive = false;

        // Jog anti-jitter: committed position for deadband filter.
        // During jog/scratch the CDJ's abspos oscillates +/-several ms due to
        // mechanical jog wheel resolution.  Without filtering, Resolume sees
        // sub-frame position reversals and renders a visible frame vibration.
        // The deadband suppresses direction changes smaller than one video frame
        // (~33ms at 30fps) while passing through sustained movement and playback.
        uint32_t committedMs   = 0;
        bool     wasPlaying    = false;
    };

    // A receiver that sent us an OptIn, identified by its IP and its
    // listener port: two receivers on one host are two slaves.
    struct SlaveNode
    {
        juce::String ip;
        uint16_t listenerPort = 0;
        uint16_t nodeId       = 0;
        double   lastSeenMs   = 0.0;   // hi-res counter (monotonic), not the wall clock
        bool     active       = false;
    };

    TCNetOutput()
    {
        refreshNetworkInterfaces();
        std::memset(nodeName, 0, sizeof(nodeName));
        nodeName[0]='S'; nodeName[1]='T'; nodeName[2]='C';
    }
    ~TCNetOutput() override { stop(); }

    void refreshNetworkInterfaces() { availableInterfaces = ::getNetworkInterfaces(true); }   // localhost too (#20)
    int  getInterfaceCount() const  { return availableInterfaces.size(); }
    bool getIsRunning() const       { return running; }
    int  getSelectedInterface() const { return selectedInterface; }

    // Global TCNet offset (ms), summed with the per-engine offset inside
    // setLayerFromEngine.  Use case: compensating for venue capture /
    // encoding chains that add a uniform delay to every engine.  Setting
    // 0 reproduces v1.9.11-beta6 behaviour exactly.  Both setter and the
    // read inside setLayerFromEngine run on the message thread (timer
    // callback + UI callback), so no synchronisation is required; the
    // field is a plain int matching the per-engine offset's style.
    void setGlobalOffsetMs(int v) { globalOffsetMs = juce::jlimit(-2000, 2000, v); }
    int  getGlobalOffsetMs() const { return globalOffsetMs; }

    bool start(int interfaceIndex = -1)
    {
        stop();
        if (interfaceIndex >= 0 && interfaceIndex < availableInterfaces.size())
        {
            selectedInterface = interfaceIndex;
            broadcastIp = availableInterfaces[interfaceIndex].broadcast;
            bindIp      = availableInterfaces[interfaceIndex].ip;
        }
        else
        {
            selectedInterface = -1;
            broadcastIp = "255.255.255.255";
            bindIp      = "0.0.0.0";
        }

        // Socket 1: broadcast sender for OptIn/Status (port 60000)
        broadcastSocket = std::make_unique<juce::DatagramSocket>(false);
        if (!broadcastSocket->bindToPort(0, bindIp) && !broadcastSocket->bindToPort(0))
            { broadcastSocket = nullptr; return false; }
        setBroadcast(broadcastSocket.get());

        // Socket 2: broadcast sender for Time (port 60001)
        timeSocket = std::make_unique<juce::DatagramSocket>(false);
        if (!timeSocket->bindToPort(0, bindIp) && !timeSocket->bindToPort(0))
            { timeSocket = nullptr; broadcastSocket = nullptr; return false; }
        setBroadcast(timeSocket.get());

        // Socket 3: listener on our NodeListenerPort for incoming Requests
        listenerSocket = std::make_unique<juce::DatagramSocket>(false);
        if (!listenerSocket->bindToPort(kListenerPort, bindIp) && !listenerSocket->bindToPort(kListenerPort))
            { listenerSocket = nullptr; /* non-fatal, unicast won't work */ }

        // Socket 4: listener on port 60000 for slave OptIn discovery
        // (separate from our broadcast sender).  In Localhost mode STC's
        // OptIn and Status go to 127.0.0.1:60000, a unicast that only one
        // socket on the port gets: if the receiver on this PC opened 60000
        // before STC, this socket is the one, and the receiver misses them
        // (measured on Linux, net_localhost_sim).  The Time packets (60001),
        // the OptIn unicast to discovered slaves and the replies are not
        // affected.  Left as is: no fix that is both clear and local
        // (AUDIT NET-3, BENCH B36).
        discoverySocket = std::make_unique<juce::DatagramSocket>(false);
        discoverySocket->setEnablePortReuse(true);
        if (!discoverySocket->bindToPort(kPortBroadcast))
            discoverySocket = nullptr;  // non-fatal

        // Socket 5: unicast sender for Metrics/Metadata responses
        unicastSocket = std::make_unique<juce::DatagramSocket>(false);
        if (!unicastSocket->bindToPort(0, bindIp) && !unicastSocket->bindToPort(0))
            unicastSocket = nullptr;  // non-fatal

        running = true; seq = 0; uptimeSeconds = 0; tickCount = 0;
        for (auto& s : slaves) s.active = false;

        sendOptIn();
        sendStatus();

        startTimer(1000 / kTimerHz);
        return true;
    }

    void stop()
    {
        stopTimer();
        if (running && broadcastSocket) sendOptOut();
        running = false;
        auto shutdown = [](auto& s) { if (s) { s->shutdown(); s = nullptr; } };
        shutdown(unicastSocket);
        shutdown(listenerSocket);
        shutdown(discoverySocket);
        shutdown(timeSocket);
        shutdown(broadcastSocket);
    }

    void setLayerFromEngine(int idx, const Timecode& tc, FrameRate fps,
                            uint32_t playheadMs, uint32_t durationMs,
                            bool isPlaying, uint8_t onAirFader,
                            uint8_t beatInBar, uint32_t bpm100 = 0,
                            int offsetMs = 0, uint32_t beatNumber = 0,
                            uint8_t masterPlayerNum = 0,
                            uint32_t trackId = 0,
                            double speedRatio = 1.0)
    {
        if (idx < 0 || idx >= kMaxLayers) return;
        auto& L       = layers[idx];
        L.masterPlayerNum = masterPlayerNum;  // Sync Master value for Metrics
        int64_t baseMs = (int64_t)((playheadMs > 0) ? playheadMs : tcToMs(tc, fps));
        // Engine-side per-layer offset + venue-wide global offset.
        // Both are signed ms; the sum is clamped into the uint32 wire
        // range below so negative excursions parked at 0 instead of
        // wrapping to ~49 days.
        int64_t adjusted = baseMs + offsetMs + (int64_t)globalOffsetMs;
        uint32_t newMs = (uint32_t)juce::jlimit((int64_t)0, (int64_t)0xFFFFFFFF, adjusted);

        // Jog anti-jitter deadband.
        // During playback: pass through directly (position advances monotonically).
        // On play->pause transition: the new position becomes the anchor.  The
        // layer time moves to it when it is kJogDeadband or more away from the
        // last played value (#24): a jump that came with the pause -- a
        // generator STOP back to Start TC, a CDJ CUE return -- and, for a
        // source given as a timecode (no playheadMs, so whole frames), a
        // pause that lands a frame on: the layer then shows the frame the
        // other outputs' clean stop carries.  Closer than that (a CDJ's
        // position one 60 Hz tick on, about 17 ms at normal speed) the layer
        // time stays on the last played value, as before.  Either way the
        // layer reads PAUSED: kStateStopped is never sent, no capture shows
        // what a receiver does with it (DESIGN D2).
        // While paused/jogging: only update if movement exceeds one video frame
        // (~33ms).  This suppresses the +/-few-ms oscillation from the CDJ's jog
        // wheel that causes visible frame vibration in Resolume.
        static constexpr uint32_t kJogDeadband = 33;  // ~1 frame at 30fps

        if (isPlaying)
        {
            L.currentTimeMs = newMs;
            L.committedMs   = newMs;
        }
        else
        {
            // Transition from play to pause: anchor at the new position, and
            // move there when the pause came with a jump (above).
            if (L.wasPlaying)
            {
                int64_t jump = (int64_t)newMs - (int64_t)L.currentTimeMs;
                if (jump < 0) jump = -jump;
                L.committedMs = newMs;
                if ((uint64_t)jump >= kJogDeadband)
                    L.currentTimeMs = newMs;
            }

            int64_t delta = (int64_t)newMs - (int64_t)L.committedMs;
            if (delta < 0) delta = -delta;
            if ((uint64_t)delta >= kJogDeadband)
            {
                L.committedMs   = newMs;
                L.currentTimeMs = newMs;
            }
            // else: hold L.currentTimeMs at the last committed value
        }
        L.wasPlaying    = isPlaying;
        L.hasEverBeenActive = true;

        L.beatMarker    = beatInBar;
        L.beatNumber    = beatNumber;
        L.layerState    = isPlaying ? kStatePlaying : kStatePaused;
        L.onAir         = onAirFader;
        L.trackId       = (trackId != 0) ? trackId : (uint32_t)(idx + 1);
        L.bpm100        = bpm100;
        L.trackLenMs    = (durationMs > 0) ? durationMs : kDefaultDurationMs;
        // 2^20 fixed-point = 100 %; the Bridge sends this range.  Scaled by
        // the source's pitch so a receiver that extrapolates between packets
        // runs at the right rate (it was fixed at 100 % under pitch).
        // Clamped to 0-4 before rounding, so the rounding never sees a
        // negative value (reverse reads as 0); a NaN ratio reads as 0 too,
        // where jlimit passed it on to an undefined float-to-int conversion.
        const double ratio = (speedRatio > 0.0) ? juce::jmin(4.0, speedRatio) : 0.0;
        L.speed         = isPlaying ? (uint32_t) std::lround(ratio * 1048576.0) : 0u;

        // Derive HH:MM:SS:FF from the committed currentTimeMs (post-deadband)
        // so all fields in the Time Packet stay internally consistent.
        // ChamSys and similar consoles read the TC H/M/S/F fields (starting
        // at byte 108 for L1) as the advancing timecode; if left at 0 the
        // receiver sees "timecode stopped at 00:00:00:00" and ignores it.
        // Same conversion as every other output (drop-frame numbering at
        // 29.97), and the layer's SMPTE mode byte says which rate the frame
        // field is in -- it used to be fixed at 30 while the frames were
        // counted at the engine rate, so a console reading the block at
        // 25 fps saw frame 24 as 0.80 s instead of 0.96 s.
        const Timecode wire = wallClockToTimecode((double)L.currentTimeMs, fps);
        L.tcHours   = (uint8_t)wire.hours;
        L.tcMinutes = (uint8_t)wire.minutes;
        L.tcSeconds = (uint8_t)wire.seconds;
        L.tcFrames  = (uint8_t)wire.frames;
        L.smpteMode = smpteModeFor(fps);
    }

    /// TCNet SMPTE mode byte for an engine frame rate.  23.976 has no code
    /// and is sent as 24, like MTC and Art-Net do.
    static uint8_t smpteModeFor(FrameRate fps)
    {
        switch (fps)
        {
            case FrameRate::FPS_2398:
            case FrameRate::FPS_24:   return kSmpte24;
            case FrameRate::FPS_25:   return kSmpte25;
            case FrameRate::FPS_2997: return kSmpteDf;
            case FrameRate::FPS_30:
            default:                  return kSmpte30;
        }
    }

    /// The node-wide SMPTE mode: that of the first active layer, 30 when
    /// none is (matches what the Bridge sends idle).
    uint8_t generalSmpteMode() const
    {
        for (int i = 0; i < kMaxLayers; ++i)
            if (layers[i].hasEverBeenActive)
                return layers[i].smpteMode;
        return kSmpte30;
    }

    void clearLayer(int idx)
    {
        if (idx >= 0 && idx < kMaxLayers)
        {
            // Preserve identity (hasEverBeenActive, masterPlayerNum, trackLenMs)
            // and just transition the layer state to idle. Real Bridge keeps
            // emitting Metrics for the layer indefinitely after the source
            // disappears, with layerState=0 -- this stable identity is what
            // MagicQ tracks. If we wiped everything, the receiver would see
            // the master "vanish" and enter an error state.
            bool hadContent = layers[idx].artist.isNotEmpty() || !layers[idx].artworkJpeg.empty();
            layers[idx].layerState     = kStateIdle;
            layers[idx].beatMarker     = 0;
            layers[idx].beatNumber     = 0;
            layers[idx].speed          = 0;
            layers[idx].onAir          = 0;
            layers[idx].currentTimeMs  = 0;
            layers[idx].committedMs    = 0;
            layers[idx].wasPlaying     = false;
            layers[idx].tcHours        = 0;
            layers[idx].tcMinutes      = 0;
            layers[idx].tcSeconds      = 0;
            layers[idx].tcFrames       = 0;
            layers[idx].artist.clear();
            layers[idx].title.clear();
            layers[idx].artworkJpeg.clear();
            layers[idx].smallWaveform.clear();
            layers[idx].realBeatGrid.clear();
            if (hadContent)
            {
                layers[idx].metadataDirty = true;
                layers[idx].artworkDirty = true;
            }
            // Note: hasEverBeenActive, masterPlayerNum, trackId, bpm100,
            // trackLenMs are intentionally NOT cleared so the layer keeps
            // a stable identity for the receiver.
        }
    }

    void setLayerMetadata(int idx, const juce::String& artist, const juce::String& title)
    {
        if (idx < 0 || idx >= kMaxLayers) return;
        auto& L = layers[idx];
        if (L.artist != artist || L.title != title)
        {
            L.artist = artist;
            L.title = title;
            L.metadataDirty = true;
        }
    }

    /// Set artwork JPEG for a layer. Pass empty vector to use default STC logo.
    void setLayerArtwork(int idx, const void* jpegData, size_t jpegSize)
    {
        if (idx < 0 || idx >= kMaxLayers) return;
        auto& L = layers[idx];
        if (jpegData != nullptr && jpegSize > 0)
        {
            auto* src = static_cast<const uint8_t*>(jpegData);
            if (L.artworkJpeg.size() != jpegSize || std::memcmp(L.artworkJpeg.data(), src, jpegSize) != 0)
            {
                L.artworkJpeg.assign(src, src + jpegSize);
                L.artworkDirty = true;
            }
        }
        else if (!L.artworkJpeg.empty())
        {
            L.artworkJpeg.clear();
            L.artworkDirty = true;
        }
    }

    /// Set small waveform data for a layer.
    ///
    /// srcData is the raw waveform bytes the caller has for the track;
    /// srcBytesPerEntry says how they are read:
    ///   0 = none (clear the cached waveform)
    ///   3 = three band heights per entry, each masked to 5 bits: the
    ///       CDJ-3000's PWV6 preview (mid, high, low) or PWV7 detail, and
    ///       StageLinQ's overview (reordered to mid, high, low)
    ///   6 = a colour preview in the PWV4 layout, d0..d5 (see case 6)
    ///   2 = the NXS2's PWV5 detail (see case 2)
    ///
    /// The output is always 2400 bytes, 1200 entries of (height, colour):
    /// STC's reading of TCNet's small waveform.  How each input becomes a
    /// pair is per case: case 3 packs the colour byte as two 4-bit
    /// intensities, (high << 4) | mid, and maps the height from 5 bits
    /// (0-31) to 8 (0-255) as x8 plus a quarter (31 -> 255); case 6 maps
    /// its height the same way and packs (d4 & 0x0F) << 4 | (d3 & 0x0F);
    /// case 2 passes bytes 0 and 1 as they are.  Neither the layout nor the
    /// scaling has been checked against a capture of a TCNet consumer
    /// (DESIGN D2).
    void setLayerSmallWaveform(int idx, const uint8_t* srcData, int srcEntryCount,
                               int srcBytesPerEntry)
    {
        if (idx < 0 || idx >= kMaxLayers) return;
        auto& L = layers[idx];

        if (srcData == nullptr || srcEntryCount <= 0 || srcBytesPerEntry <= 0)
        {
            L.smallWaveform.clear();
            return;
        }

        constexpr int kTargetEntries = 1200;
        constexpr int kTargetBytes = kTargetEntries * 2;  // 2400
        L.smallWaveform.assign(kTargetBytes, 0);

        // Resample source -> 1200 entries.
        for (int i = 0; i < kTargetEntries; ++i)
        {
            int srcIdx = (int)((double)i * srcEntryCount / kTargetEntries);
            if (srcIdx >= srcEntryCount) srcIdx = srcEntryCount - 1;
            const uint8_t* e = srcData + srcIdx * srcBytesPerEntry;

            uint8_t height = 0;
            uint8_t color = 0;
            switch (srcBytesPerEntry)
            {
                case 3:  // Three bands, each masked to 5 bits (0-31), scaled to 0-255.
                {
                    // The references give these bands as whole bytes:
                    // StageLinQ's overview is Engine DJ's u8 per band, 0-255
                    // (libdjinterop; StageLinQDbClient passes them on as
                    // they are), and PWV6/PWV7 are one-byte heights
                    // (dysentery track_metadata; beat-link reads PWV6's
                    // unmasked, low x0.49, mid x0.32, high x0.25, stacked).
                    // The 5-bit mask wraps any value over 31 (200 -> 8).
                    // Not changed without a capture (DESIGN D2).
                    uint8_t mid = e[0] & 0x1F;
                    uint8_t hi  = e[1] & 0x1F;
                    uint8_t lo  = e[2] & 0x1F;
                    uint8_t maxBand = std::max({mid, hi, lo});
                    // 5-bit -> 8-bit: multiply by ~8.23. Use shift + carry for
                    // a slight saturation toward max instead of simple <<3
                    // which caps at 248 instead of 255.
                    height = (uint8_t)std::min(255, (int)maxBand * 8 + (maxBand >> 2));
                    // Colour byte: high-band and mid-band intensities in the
                    // two nibbles, 5-bit -> 4-bit by >>1.
                    color = (uint8_t)(((hi >> 1) << 4) | (mid >> 1));
                    break;
                }
                case 6:  // Colour preview in the PWV4 layout, d0..d5
                {
                    // What a CDJ-3000-class player's dbserver gives as its
                    // colour preview.  An NXS2's PWV4, which the NFS route
                    // gives it since AUDIT META-15, does not come here: the
                    // MainComponent feed keeps such a deck on the detail
                    // fallback (case 2), as 1.9.14-beta2 did.  Read as: the
                    // height from the
                    // largest of d0..d2 (5 bits each), the colour as
                    // (d4 & 0x0F) << 4 | (d3 & 0x0F).  The references read
                    // these bytes otherwise: dysentery (track_metadata,
                    // colour preview analysis) calls d0 and d1 "whiteness",
                    // d2 the energy in the bottom half of the range, and d3,
                    // d4, d5 the energy in its low, mid and top parts;
                    // beat-link's WaveformPreview (RGB) takes the back
                    // (dimmer) segment's height as max(d3, d4, d5) and the
                    // front one's as d5, unmasked, and the colour from d3,
                    // d4, d5 as red, green and blue.  Not changed: what a
                    // TCNet consumer draws from it is not captured (DESIGN
                    // D2).
                    uint8_t d0 = e[0] & 0x1F;
                    uint8_t d1 = e[1] & 0x1F;
                    uint8_t d2 = e[2] & 0x1F;
                    uint8_t maxBand = std::max({d0, d1, d2});
                    height = (uint8_t)std::min(255, (int)maxBand * 8 + (maxBand >> 2));
                    uint8_t r = e[3] & 0x0F;
                    uint8_t g = e[4] & 0x0F;
                    color = (uint8_t)((g << 4) | r);
                    break;
                }
                case 2:  // NXS2 PWV5 detail, the fallback without a preview:
                         // byte 0 is sent as the height and byte 1 as the
                         // colour.  PWV5 is a big-endian u16 -- red, green,
                         // blue in bits 15..7, 3 bits each, the height in
                         // bits 6..2 (dysentery track_metadata; beat-link
                         // WaveformDetail; AUDIT META-11) -- so neither byte
                         // is a height or a colour.  Not changed (DESIGN D2).
                    height = e[0];
                    color = e[1];
                    break;
                default: break;
            }
            L.smallWaveform[i * 2] = height;
            L.smallWaveform[i * 2 + 1] = color;
        }
    }

    /// Set real beat grid from CDJ metadata.
    /// entries are (beat number 1-based, time in ms). Beat type (up/downbeat)
    /// is inferred from beat number (every 4th is a downbeat at 4/4 time).
    void setLayerBeatGrid(int idx, const uint16_t* beatNumbers,
                          const uint32_t* timesMs, int count)
    {
        if (idx < 0 || idx >= kMaxLayers) return;
        auto& L = layers[idx];
        L.realBeatGrid.clear();
        if (beatNumbers == nullptr || timesMs == nullptr || count <= 0) return;
        L.realBeatGrid.reserve((size_t)count);
        for (int i = 0; i < count; ++i)
        {
            LayerData::RealBeat rb;
            rb.beatNumber = beatNumbers[i];
            rb.timeMs = timesMs[i];
            // Downbeat if beatNumber % 4 == 1 (first beat of bar in 1-based).
            rb.type = (beatNumbers[i] > 0 && (beatNumbers[i] % 4 == 1)) ? 0x14 : 0x0a;
            L.realBeatGrid.push_back(rb);
        }
    }

private:
    // A juce::Timer, so it runs on the message thread: unlike the MTC,
    // Art-Net, LA-Net and HippoNet senders (each on its own
    // HighResolutionTimer thread) and LTC (the audio callback), TCNet's Time
    // packets stop for as long as the message thread is busy (AUDIT D8,
    // NET-11, deferred).
    void timerCallback() override
    {
        if (!running) return;

        // 1. Poll incoming packets (discovery + requests)
        pollDiscovery();
        pollRequests();

        // 2. Broadcast Time at 60Hz
        sendTime();

        // 3. Unicast Metrics to all known slaves at 30Hz (every other tick)
        bool metricsThisTick = (tickCount & 1) == 0;
        if (metricsThisTick)
            sendMetricsToSlaves();

        // 4. Send metadata when dirty
        for (int i = 0; i < kMaxLayers; ++i)
        {
            if (layers[i].metadataDirty)
            {
                sendMetadataToSlaves(i);
                layers[i].metadataDirty = false;
            }
            if (layers[i].artworkDirty)
            {
                sendArtworkToSlaves(i);
                layers[i].artworkDirty = false;
            }
        }

        // 5. 1Hz tasks: OptIn, Status, slave expiry
        if (++tickCount >= (uint32_t)kTimerHz)
        {
            tickCount = 0;
            if (++uptimeSeconds >= 43200) uptimeSeconds = 0;
            sendOptIn();
            sendStatus();
            sendOptInToSlaves();  // unicast OptIn to each slave
            expireSlaves();
        }
    }

    // ============================================================
    // Slave discovery -- listen on port 60000 for OptIn from slaves
    // ============================================================
    void pollDiscovery()
    {
        if (!discoverySocket) return;
        uint8_t buf[512];
        juce::String srcIp;
        int srcPort = 0;
        while (discoverySocket->waitUntilReady(true, 0) == 1)
        {
            int n = discoverySocket->read(buf, sizeof(buf), false, srcIp, srcPort);
            if (n < 24) continue;
            if (buf[4] != 'T' || buf[5] != 'C' || buf[6] != 'N') continue;
            if (buf[7] != kMsgOptIn) continue;
            // Don't register ourselves.  Any other OptIn registers, whatever
            // its NodeType (byte 17): no filter, since the TCNet spec's rule
            // on which node types a master serves was not available to check
            // (AUDIT NET-9).
            uint16_t remoteId = buf[0] | (buf[1] << 8);
            if (remoteId == nodeId) continue;
            // Extract slave's listener port
            if (n >= 28)
            {
                uint16_t slavePort = buf[26] | (buf[27] << 8);
                registerSlave(srcIp, slavePort, remoteId);
            }
        }
    }

    void registerSlave(const juce::String& ip, uint16_t port, uint16_t nid)
    {
        // The hi-res counter, not currentTimeMillis(): the wall clock jumps
        // when NTP or the operator sets it, and a jump expired every slave
        // at once (forward) or none for as long as it went back (AUDIT NET-9).
        const double now = juce::Time::getMillisecondCounterHiRes();
        // Update existing.  A slave is its IP and listener port: matching
        // the IP alone made two receivers on one PC (Resolume and a console
        // emulator) one slave whose port flipped with every OptIn.
        for (auto& s : slaves)
        {
            if (s.active && s.ip == ip && s.listenerPort == port)
            {
                s.lastSeenMs = now;
                return;
            }
        }
        // Add new
        for (auto& s : slaves)
        {
            if (!s.active)
            {
                s.ip = ip;
                s.listenerPort = port;
                s.nodeId = nid;
                s.lastSeenMs = now;
                s.active = true;
                // Send initial data burst to new slave
                sendInitialDataToSlave(s);
                return;
            }
        }
    }

    void expireSlaves()
    {
        const double now = juce::Time::getMillisecondCounterHiRes();
        for (auto& s : slaves)
            if (s.active && (now - s.lastSeenMs) > 10000.0)
                s.active = false;
    }

    /// The listener port to answer a request from srcIp:srcPort on: the
    /// slave with that IP whose listener port is srcPort, else the first
    /// slave with that IP (a request need not come from the listener
    /// port).  0 when no slave has that IP.
    uint16_t replyPortFor(const juce::String& srcIp, int srcPort) const
    {
        uint16_t first = 0;
        for (auto& s : slaves)
        {
            if (!s.active || s.ip != srcIp) continue;
            if ((int) s.listenerPort == srcPort) return s.listenerPort;
            if (first == 0) first = s.listenerPort;
        }
        return first;
    }

    void sendInitialDataToSlave(const SlaveNode& slave)
    {
        if (!unicastSocket) return;
        for (int i = 0; i < kPacketLayers; ++i)
        {
            sendMetadataUnicast(slave.ip, slave.listenerPort, i);
            sendMetricsUnicast(slave.ip, slave.listenerPort, i);
        }
        // Send artwork for active layers
        for (int i = 0; i < kMaxLayers; ++i)
            if (layers[i].trackId != 0)
                sendArtworkUnicast(slave.ip, slave.listenerPort, i);
    }

    // ============================================================
    // Request handler -- listen on our NodeListenerPort
    // ============================================================
    void pollRequests()
    {
        if (!listenerSocket) return;
        uint8_t buf[512];
        juce::String srcIp;
        int srcPort = 0;
        while (listenerSocket->waitUntilReady(true, 0) == 1)
        {
            int n = listenerSocket->read(buf, sizeof(buf), false, srcIp, srcPort);
            if (n < 24) continue;
            if (buf[4] != 'T' || buf[5] != 'C' || buf[6] != 'N') continue;

            uint8_t msgType = buf[7];

            if (msgType == kMsgTimeSync && n >= 32)
            {
                handleTimeSync(srcIp, buf, n);
            }
            else if (msgType == kMsgRequest && n >= 26)
            {
                uint8_t dataType = buf[24];
                uint8_t layerId  = buf[25];  // 1-based
                handleRequest(srcIp, srcPort, dataType, layerId);
            }
            else if (msgType == kMsgApp)
            {
                handleApplication(srcIp, srcPort, buf, n);
            }
        }
    }

    void handleRequest(const juce::String& srcIp, int srcPort, uint8_t dataType, uint8_t layerId)
    {
        // Find slave's listener port
        const uint16_t dstPort = replyPortFor(srcIp, srcPort);
        if (dstPort == 0) return;

        int layerIdx = layerId - 1;  // 0-based

        if (dataType == 4)  // Metadata
            sendMetadataUnicast(srcIp, dstPort, layerIdx);
        else if (dataType == 2)  // Metrics
            sendMetricsUnicast(srcIp, dstPort, layerIdx);
        else if (dataType == 128)  // Artwork (low-res JPEG)
            sendArtworkUnicast(srcIp, dstPort, layerIdx);
        else if (dataType == 8)   // Beat Grid
            sendBeatGridUnicast(srcIp, dstPort, layerIdx);
        else if (dataType == 16)  // Small Waveform
            sendSmallWaveformUnicast(srcIp, dstPort, layerIdx);
        else
        {
            // Other unsupported data types (Cue=12, Big WF=32). Reply with
            // Error so the requester doesn't keep waiting.
            if (!unicastSocket) return;
            uint8_t p[30] = {};
            hdr(p, kMsgError, 5);
            p[24] = dataType;
            p[25] = layerId;
            p[26] = 0xFF; p[27] = 0x00;
            p[28] = kMsgRequest; p[29] = 0x00;
            unicastSocket->write(srcIp, (int)dstPort, p, 30);
        }
    }

    // ============================================================
    // Synthesize a Beat Grid based on current BPM. The real PRO DJ LINK
    // Bridge always serves Beat Grid Data when requested (never Error),
    // and ChamSys MagicQ requires this to trust the node and update its
    // beat tracker display. Format (from observed Bridge traffic):
    //   Header: TCNet Data Packet type 200, DataType=8
    //   Bytes 26-29: Data Size = numBeats * 8
    //   Bytes 30-33: Total Packets = 1 (we send short grid in one packet)
    //   Bytes 34-37: Packet No = 0
    //   Bytes 38-41: Data Cluster Size = numBeats * 8
    //   Bytes 42+: N entries of 8 bytes each:
    //     [0-1] Beat Number (LE uint16)
    //     [2]   Beat Type: 0x0a (10) = upbeat, 0x14 (20) = downbeat
    //     [3]   Reserved
    //     [4-7] Beat Time Stamp in ms (LE uint32)
    //   First entry (beat 0) has all zeros. Downbeats every 4 beats.
    // ============================================================
    void sendBeatGridUnicast(const juce::String& ip, uint16_t port, int layerIdx)
    {
        if (!unicastSocket || layerIdx < 0 || layerIdx >= kPacketLayers) return;
        auto& L = layers[layerIdx];

        // Beat Grid format (observed from real Bridge):
        //   8 bytes per entry: Beat Number (2B LE) + Beat Type (1B: 0x0a upbeat,
        //   0x14 downbeat) + Reserved (1B) + Beat Time Stamp (4B LE ms).
        //   First entry is all zeros (Bridge convention).
        //   Max 2400 bytes of data per packet = 300 entries per packet.
        //   Multi-packet: Total Packets > 1, Packet No 0..N-1.
        //
        // We need the grid to cover the ENTIRE track duration so MagicQ's beat
        // counter doesn't stall at the end of the grid. For the 2-hour default
        // (kDefaultDurationMs) at 120 BPM = 14401 entries = 115208 bytes = 49
        // packets.  All of them go out here, back to back, inside one timer
        // callback on the message thread (AUDIT NET-11, deferred).
        constexpr int kEntrySize = 8;
        constexpr int kMaxEntriesPerPacket = 300;  // 2400 bytes / 8
        constexpr int kClusterSize = kMaxEntriesPerPacket * kEntrySize;  // 2400

        // Compute total beats to emit.
        int totalBeats = 0;
        std::vector<std::pair<uint32_t, uint8_t>> entries;  // (timeMs, type) for beat 1..N
        if (!L.realBeatGrid.empty())
        {
            entries.reserve(L.realBeatGrid.size());
            for (const auto& b : L.realBeatGrid)
                entries.push_back({ b.timeMs, b.type });
            totalBeats = (int)entries.size();
        }
        else
        {
            uint32_t bpm100 = (L.bpm100 > 0) ? L.bpm100 : 12000;
            double beatMs = 60000.0 * 100.0 / (double)bpm100;
            uint32_t durationMs = (L.trackLenMs > 0) ? L.trackLenMs : kDefaultDurationMs;
            int beatCount = (int)((double)durationMs / beatMs);
            if (beatCount < 1) beatCount = 1;
            // Cap at a sane upper bound to prevent pathological traffic.
            // 2h at 220 BPM = 26400 beats. 30000 covers it with margin.
            // At 8 bytes/entry + the zero entry, 30k beats = 240008 bytes =
            // 101 packets of up to 2442 bytes (each IP-fragmented) = ~240 KB
            // sent on each Beat Grid request.
            if (beatCount > 30000) beatCount = 30000;
            entries.reserve((size_t)beatCount);
            for (int i = 1; i <= beatCount; ++i)
            {
                uint32_t ts = (uint32_t)(beatMs * (double)(i - 1) + 62.0);
                bool isDownbeat = ((i - 2) % 4 == 0) && (i >= 2);
                entries.push_back({ ts, (uint8_t)(isDownbeat ? 0x14 : 0x0a) });
            }
            totalBeats = beatCount;
        }

        // Total entries to send = 1 (zero entry) + totalBeats.
        int totalEntries = 1 + totalBeats;
        int totalDataSize = totalEntries * kEntrySize;
        int totalPackets = (totalDataSize + kClusterSize - 1) / kClusterSize;
        if (totalPackets < 1) totalPackets = 1;

        // Emit each packet in the multi-packet sequence.
        for (int pktNo = 0; pktNo < totalPackets; ++pktNo)
        {
            int bytesIntoData = pktNo * kClusterSize;
            int bytesRemaining = totalDataSize - bytesIntoData;
            int thisChunkSize = std::min(bytesRemaining, kClusterSize);
            int thisEntryCount = thisChunkSize / kEntrySize;
            int packetSize = 42 + thisChunkSize;

            std::vector<uint8_t> p((size_t)packetSize, 0);
            hdr(p.data(), kMsgData, 5);

            p[24] = 8;                                // DataType = Beat Grid
            p[25] = (uint8_t)(layerIdx + 1);          // Layer ID
            w32(p.data() + 26, (uint32_t)totalDataSize);   // Total data size
            w32(p.data() + 30, (uint32_t)totalPackets);    // Total packets
            w32(p.data() + 34, (uint32_t)pktNo);           // Packet No (0-based)
            w32(p.data() + 38, (uint32_t)kClusterSize);    // Cluster size

            // Starting entry index in the flattened [entry 0 zero + entries[]].
            int startEntry = pktNo * kMaxEntriesPerPacket;
            for (int i = 0; i < thisEntryCount; ++i)
            {
                int flatIdx = startEntry + i;
                int off = 42 + i * kEntrySize;
                if (flatIdx == 0)
                {
                    // Entry 0: all zeros (Bridge convention).
                    continue;
                }
                int entryIdx = flatIdx - 1;  // into entries[]
                if (entryIdx >= (int)entries.size()) break;
                uint16_t beatNum = (uint16_t)(entryIdx + 1);  // 1-based beat number
                w16(p.data() + off, beatNum);
                p[off + 2] = entries[(size_t)entryIdx].second;  // type
                p[off + 3] = 0;
                w32(p.data() + off + 4, entries[(size_t)entryIdx].first);  // timeMs
            }

            unicastSocket->write(ip, (int)port, p.data(), packetSize);
        }
    }

    // Synthesize a Small Waveform Data packet. If we have real CDJ waveform
    // data cached (set via setLayerSmallWaveform), use that; otherwise send
    // a packet of zeros with valid headers so MagicQ considers the node
    // compliant.
    void sendSmallWaveformUnicast(const juce::String& ip, uint16_t port, int layerIdx)
    {
        if (!unicastSocket || layerIdx < 0 || layerIdx >= kPacketLayers) return;
        auto& L = layers[layerIdx];

        constexpr int kWfDataSize = 2400;
        constexpr int kWfPacketSize = 42 + kWfDataSize;  // 2442

        uint8_t p[kWfPacketSize] = {};
        hdr(p, kMsgData, 5);

        p[24] = 16;                           // DataType = Small Waveform
        p[25] = (uint8_t)(layerIdx + 1);      // Layer ID
        w32(p + 26, kWfDataSize);             // Data Size
        w32(p + 30, 1);                       // Total Packets
        w32(p + 34, 1);                       // Packet No (1-based, per Bridge)
        w32(p + 38, 0);                       // Data Cluster Size (Bridge sends 0 here)
        // [42..2441] waveform samples: use cached data if available.
        if (L.smallWaveform.size() == (size_t)kWfDataSize)
        {
            std::memcpy(p + 42, L.smallWaveform.data(), kWfDataSize);
        }

        unicastSocket->write(ip, (int)port, p, kWfPacketSize);
    }

    void handleTimeSync(const juce::String& srcIp, const uint8_t* buf, int len)
    {
        if (len < 32 || !unicastSocket) return;

        // Parse request
        uint8_t  step          = buf[24];
        uint16_t initiatorPort = (uint16_t)(buf[26] | (buf[27] << 8));
        uint32_t initiatorTs   = (uint32_t)buf[28]
                               | ((uint32_t)buf[29] << 8)
                               | ((uint32_t)buf[30] << 16)
                               | ((uint32_t)buf[31] << 24);
        if (initiatorPort < 65023) return;  // invalid listener port per spec

        // Build response. The spec says:
        //   Step 1: initiator sends with STEP=0, timestamp=own current timer
        //   Step 2: remote responds with STEP=1, timestamp=remote's current
        //           timer, Remote Timestamp=initiator's original timestamp
        // In practice we see the initiator sending STEP=1 (MagicQ) -- we just
        // echo back STEP incremented, our timestamp, and their timestamp
        // in the Remote Timestamp field, so the initiator can compute the
        // round-trip delay.
        uint8_t p[32] = {};
        hdr(p, kMsgTimeSync, 5);

        // Timestamp: an accumulating microsecond counter. TCNet spec
        // describes this as "microseconds within a second" (0-999999) but
        // observed traffic from ChamSys MagicQ uses an accumulating
        // microsecond counter (the values grow monotonically into the
        // billions). Emit one to match: the hi-res counter in microseconds
        // -- the system's uptime on every platform, not STC's -- truncated
        // to uint32_t, so it wraps every 71.6 minutes; that's fine for sync
        // -- both sides just need consistent time bases to compute relative
        // delay.
        uint32_t nowUs = (uint32_t) hiResMicros();
        w32(p + 20, nowUs);

        p[24] = (uint8_t)(step + 1);  // advance step
        p[25] = 0;                     // reserved
        w16(p + 26, (uint16_t)kListenerPort);
        w32(p + 28, initiatorTs);      // echo initiator's timestamp

        unicastSocket->write(srcIp, (int)initiatorPort, p, 32);
    }

    void handleApplication(const juce::String& srcIp, int srcPort, const uint8_t* /*buf*/, int /*len*/)
    {
        // Bridge responds with Application + then Error(255). We just send Error.
        const uint16_t dstPort = replyPortFor(srcIp, srcPort);
        if (dstPort == 0 || !unicastSocket) return;

        // Error packet (30 bytes): "not supported"
        uint8_t p[30] = {};
        hdr(p, kMsgError, 5);
        p[24] = 0xFF;  // datatype = 255
        p[25] = 0xFF;  // layer = 255
        p[26] = 0xFF; p[27] = 0x00;  // code = 255
        p[28] = kMsgApp; p[29] = 0x00;  // rejected msg type = 30
        unicastSocket->write(srcIp, (int)dstPort, p, 30);
    }

    // ============================================================
    // Unicast Metrics (122 bytes, type 200 datatype 2)
    // Sent continuously at 30Hz to each slave -- this is what
    // Resolume uses for play/pause, track loaded, position.
    // ============================================================
    void sendMetricsUnicast(const juce::String& ip, uint16_t port, int layerIdx)
    {
        if (!unicastSocket || layerIdx < 0 || layerIdx >= kPacketLayers) return;

        uint8_t p[122] = {};
        hdr(p, kMsgData, 5);

        auto& L = (layerIdx < kMaxLayers) ? layers[layerIdx] : emptyLayer;

        p[24] = 2;                           // DataType = Metrics
        p[25] = (uint8_t)(layerIdx + 1);     // Layer ID (1-based)
        // [26] reserved
        p[27] = L.layerState;                // Layer State
        // [28] reserved
        // Sync Master: 0 if this layer is not master, or the player number
        // (1-8) of the master if this layer holds master status. Observed
        // Bridge traffic sets this to the Layer ID of the master (e.g.
        // CDJ-3 on air → Sync Master = 3). MagicQ uses this field to
        // identify which layer's beat to follow.
        p[29] = L.masterPlayerNum;
        // [30] reserved
        p[31] = L.beatMarker;                // Beat Marker
        w32(p + 32, L.trackLenMs);           // Track Length ms
        w32(p + 36, L.currentTimeMs);        // Current Position ms
        w32(p + 40, L.speed);                // Speed (2^20 fixed-point, 1048576=100%)
        // Byte 45 = SMPTE framerate. Bridge observed sending 30 here in what
        // the spec calls "reserved [44-56]". Apparently not fully reserved.
        p[45] = L.smpteMode;
        // [46-56] reserved
        w32(p + 57, L.beatNumber);           // Beat Number
        // [61-111] reserved
        w32(p + 112, L.bpm100);              // BPM * 100
        // Pitch Bend: observed Bridge sends ~0 for neutral (e.g. 95 for tiny
        // variation), NOT 32768. The spec says "16-bit 0-FFFF*" but 32768 as
        // "neutral" is wrong -- that would look like a 50% pitch adjustment
        // to consumers using the Bridge convention.
        w16(p + 116, 0);                     // Pitch Bend (neutral = 0)
        w32(p + 118, L.trackId);             // Track ID

        unicastSocket->write(ip, (int)port, p, 122);
    }

    void sendMetricsToSlaves()
    {
        for (auto& s : slaves)
        {
            if (!s.active) continue;
            // Only emit Metrics for layers that are currently active
            // (Playing/Paused). Idle layers stop emitting -- this matches
            // historical behaviour and keeps Resolume's transport indicator
            // responsive (Resolume reads Time Packet TC State which can get
            // confused if multiple layers report state simultaneously).
            for (int i = 0; i < kMaxLayers; ++i)
            {
                if (layers[i].layerState != kStateIdle)
                    sendMetricsUnicast(s.ip, s.listenerPort, i);
            }
        }
    }

    // ============================================================
    // Unicast Metadata (548 bytes, type 200 datatype 4)
    // Sent on track change and in response to Requests.
    // Bridge uses UTF-32LE for strings (4 bytes per char).
    // ============================================================
    void sendMetadataUnicast(const juce::String& ip, uint16_t port, int layerIdx)
    {
        if (!unicastSocket || layerIdx < 0 || layerIdx >= kPacketLayers) return;

        uint8_t p[548] = {};
        hdr(p, kMsgData, 5);

        p[24] = 4;                           // DataType = Metadata
        p[25] = (uint8_t)(layerIdx + 1);     // Layer ID

        auto& L = (layerIdx < kMaxLayers) ? layers[layerIdx] : emptyLayer;

        // Artist at offset 29, up to 128 chars in UTF-32LE (128*4=512 max, but field is 256 bytes)
        // Actually from capture: fields are 256 bytes each, UTF-32LE encoded
        writeUtf32LE(p + 29, L.artist, 64);    // 64 chars * 4 bytes = 256 bytes
        writeUtf32LE(p + 285, L.title, 64);    // 64 chars * 4 bytes = 256 bytes
        // [541-542] Track Key
        w32(p + 543, L.trackId);               // Track ID

        unicastSocket->write(ip, (int)port, p, 548);
    }

    void sendMetadataToSlaves(int layerIdx)
    {
        for (auto& s : slaves)
            if (s.active)
                sendMetadataUnicast(s.ip, s.listenerPort, layerIdx);
    }

    // ============================================================
    // Unicast Artwork (type 204, datatype 128, JPEG in chunks)
    // Spec page 29: max 4800 bytes per chunk, header at offset 42.
    // ============================================================
    static constexpr uint8_t  kMsgFile        = 204;
    static constexpr uint8_t  kDataArtwork    = 128;
    static constexpr uint32_t kArtClusterSize = 4800;

    void sendArtworkUnicast(const juce::String& ip, uint16_t port, int layerIdx)
    {
        if (!unicastSocket || layerIdx < 0 || layerIdx >= kPacketLayers) return;

        // Choose JPEG source: layer artwork if available, else STC logo
        const uint8_t* jpegData;
        size_t jpegSize;
        auto& L = (layerIdx < kMaxLayers) ? layers[layerIdx] : emptyLayer;
        if (!L.artworkJpeg.empty())
        {
            jpegData = L.artworkJpeg.data();
            jpegSize = L.artworkJpeg.size();
        }
        else
        {
            jpegData = kStcLogoJpeg;
            jpegSize = kStcLogoJpegSize;
        }

        uint32_t totalPackets = (uint32_t)((jpegSize + kArtClusterSize - 1) / kArtClusterSize);

        for (uint32_t pktNo = 0; pktNo < totalPackets; ++pktNo)
        {
            size_t offset = (size_t)pktNo * kArtClusterSize;
            size_t chunkSize = std::min((size_t)kArtClusterSize, jpegSize - offset);
            size_t pktSize = 42 + chunkSize;

            std::vector<uint8_t> p(pktSize, 0);
            hdr(p.data(), kMsgFile, 5);

            p[24] = kDataArtwork;                        // DataType = 128
            p[25] = (uint8_t)(layerIdx + 1);             // Layer ID (1-based)
            w32(p.data() + 26, (uint32_t)jpegSize);      // Total Data Size
            w32(p.data() + 30, totalPackets);             // Total Packets
            w32(p.data() + 34, pktNo);                    // Packet No
            w32(p.data() + 38, kArtClusterSize);          // Data Cluster Size
            std::memcpy(p.data() + 42, jpegData + offset, chunkSize);  // File Data

            unicastSocket->write(ip, (int)port, p.data(), (int)pktSize);
        }
    }

    void sendArtworkToSlaves(int layerIdx)
    {
        for (auto& s : slaves)
            if (s.active)
                sendArtworkUnicast(s.ip, s.listenerPort, layerIdx);
    }

    // ============================================================
    // Unicast OptIn to each slave (Bridge does this ~every second)
    // ============================================================
    void sendOptInToSlaves()
    {
        if (!unicastSocket) return;
        uint8_t p[68] = {};
        hdr(p, kMsgOptIn, 5);  // Real Bridge uses 3.5
        w16(p + 24, 1);
        w16(p + 26, kListenerPort);
        w16(p + 28, (uint16_t)(uptimeSeconds & 0xFFFF));
        wstr(p + 32, "Fiverecords", 16);
        wstr(p + 48, "STC", 16);
        p[64] = 1; p[65] = 7; p[66] = 0;   // application version 1.7.0, never bumped (see sendOptIn)
        for (auto& s : slaves)
            if (s.active)
                unicastSocket->write(s.ip, (int)s.listenerPort, p, 68);
    }

    // ============================================================
    // Broadcast packets (same as before)
    // ============================================================
    void hdr(uint8_t* p, uint8_t msg, uint8_t minor)
    {
        w16(p, nodeId);
        p[2] = 3; p[3] = minor;
        p[4] = 'T'; p[5] = 'C'; p[6] = 'N';
        p[7] = msg;
        std::memcpy(p + 8, nodeName, 8);
        p[16] = seq++;
        p[17] = 2;  // Master
        w16(p + 18, 0x0007);  // NodeOptions (matches Bridge)

        // Timestamp: microseconds within the current second (0-999999) per
        // spec -- of the hi-res counter, whose seconds are not aligned to
        // any clock a receiver has (AUDIT B11). This is what receivers use
        // to compute network latency and to discriminate "live" nodes from
        // stale ones. Was previously 0 which may cause some consoles
        // (ChamSys MagicQ) to treat the node as not active.
        uint32_t nowUs = (uint32_t)(hiResMicros() % 1000000);
        w32(p + 20, nowUs);
    }

    /// The hi-res counter in microseconds.  Computed as ticks * 1000000 /
    /// ticksPerSecond, the product overflowed int64 once the counter passed
    /// 9.2e12 ticks: 2.6 hours after boot with a 1 GHz counter (Intel Macs),
    /// 4.4 days at 24 MHz (Apple Silicon), 10.7 days at 10 MHz (Windows),
    /// 107 days at 1 MHz (Linux) -- undefined behaviour, and garbage in both
    /// timestamps from then on (AUDIT NET-1).  Whole seconds and the
    /// remainder separately give the same value with no overflow.
    static int64_t hiResMicros()
    {
        return ticksToMicros(juce::Time::getHighResolutionTicks(),
                             juce::Time::getHighResolutionTicksPerSecond());
    }

    static int64_t ticksToMicros(int64_t ticks, int64_t ticksPerSecond)
    {
        return (ticks / ticksPerSecond) * 1000000
             + ((ticks % ticksPerSecond) * 1000000) / ticksPerSecond;
    }

    void sendOptIn()
    {
        if (!broadcastSocket) return;
        uint8_t p[68] = {};
        hdr(p, kMsgOptIn, 5);  // Real Bridge uses 3.5, not spec's 3.6
        w16(p + 24, 1);
        w16(p + 26, kListenerPort);
        w16(p + 28, (uint16_t)(uptimeSeconds & 0xFFFF));
        wstr(p + 32, "Fiverecords", 16);
        wstr(p + 48, "STC", 16);
        // Application version 1.7.0: a constant since 1.7, never bumped.
        // Left as the receivers saw it working rather than changed without
        // knowing what they do with it -- the same choice DESIGN D35 made
        // for StageLinQ's 1.7.0 (AUDIT NET-10, deferred).
        p[64] = 1; p[65] = 7; p[66] = 0;
        broadcastSocket->write(broadcastIp, kPortBroadcast, p, 68);
    }

    void sendOptOut()
    {
        if (!broadcastSocket) return;
        uint8_t p[28] = {};
        hdr(p, kMsgOptOut, 5);
        w16(p + 24, 1);
        w16(p + 26, kListenerPort);
        broadcastSocket->write(broadcastIp, kPortBroadcast, p, 28);
    }

    void sendStatus()
    {
        if (!broadcastSocket) return;
        uint8_t p[300] = {};
        hdr(p, kMsgStatus, 5);
        w16(p + 24, 1);
        w16(p + 26, kListenerPort);
        static const char* nm[4] = {
            "STC Layer 1", "STC Layer 2", "STC Layer 3", "STC Layer 4"
        };
        for (int i = 0; i < kMaxLayers; ++i)
        {
            auto& L = layers[i];
            if (L.hasEverBeenActive)
                p[34 + i] = (uint8_t)(i + 1);
            // Layer Status per spec: pure enum (same as Time Packet byte 96).
            // Resolume reads this for play/pause display.
            p[42 + i] = L.layerState;
            w32(p + 50 + i * 4, L.trackId);
            wstr(p + 172 + i * 16, nm[i], 16);
        }
        p[83] = generalSmpteMode();
        broadcastSocket->write(broadcastIp, kPortBroadcast, p, 300);
    }

    void sendTime()
    {
        if (!timeSocket) return;
        // Time Packet size: 162 bytes (includes V3-3-3 Layer OnAir bytes
        // 154-161 for DJM fader data). The PRO DJ LINK Bridge omits these
        // when no DJM is on the network (size 154), but we keep them so
        // real DJ setups can get fader/crossfader position. Receivers that
        // don't care can just ignore the extra 8 bytes.
        uint8_t p[162] = {};
        hdr(p, kMsgTime, 5);
        for (int i = 0; i < kPacketLayers; ++i)
        {
            auto& L = layers[i];
            w32(p + 24 + i*4, L.currentTimeMs);
            w32(p + 56 + i*4, L.trackLenMs);  // Total Time (track length) in ms
            p[88 + i]  = L.beatMarker;
            // Layer State per spec: pure enum (0=IDLE, 3=PLAYING, 4=LOOPING,
            // 5=PAUSED, 6=STOPPED, ...). Resolume reads this byte to drive
            // its play/pause indicator -- it expects literal enum values, so
            // no bit-OR with master flag.
            p[96 + i]  = L.layerState;

            // Per-layer time code block: 6 bytes starting at byte 106.
            // [0] SMPTE Mode: 0 = "use general SMPTE mode from byte 105"
            // [1] TC State:   0=Stopped, 1=Running, 2=Force Resync
            // [2..5] HH:MM:SS:FF
            const int tcBase = 106 + i * 6;
            p[tcBase + 0] = L.hasEverBeenActive ? L.smpteMode : 0;  // 0 = defer to general SMPTE mode
            p[tcBase + 1] = (L.layerState == kStatePlaying) ? 1 : 0;
            p[tcBase + 2] = L.tcHours;
            p[tcBase + 3] = L.tcMinutes;
            p[tcBase + 4] = L.tcSeconds;
            p[tcBase + 5] = L.tcFrames;

            p[154 + i] = L.onAir;  // fader position 0-255 (spec V3.3.3+)
        }
        // p[104] is RESERVED per spec; leave at 0.
        p[105] = generalSmpteMode();
        timeSocket->write(broadcastIp, kPortTime, p, 162);
    }

    // ============================================================
    // Helpers
    // ============================================================
    static void setBroadcast(juce::DatagramSocket* s)
    {
        auto h = s->getRawSocketHandle();
        if (h >= 0) {
            int f = 1;
#ifdef _WIN32
            setsockopt(h, SOL_SOCKET, SO_BROADCAST, (const char*)&f, sizeof(f));
#else
            setsockopt(h, SOL_SOCKET, SO_BROADCAST, &f, sizeof(f));
#endif
        }
    }

    static void w16(uint8_t* p, uint16_t v) { p[0]=(uint8_t)v; p[1]=(uint8_t)(v>>8); }
    static void w32(uint8_t* p, uint32_t v) { p[0]=(uint8_t)v; p[1]=(uint8_t)(v>>8); p[2]=(uint8_t)(v>>16); p[3]=(uint8_t)(v>>24); }
    static void wstr(uint8_t* p, const char* s, int m) { int n=(int)std::strlen(s); if(n>m)n=m; std::memcpy(p,s,(size_t)n); }

    static void writeUtf32LE(uint8_t* dst, const juce::String& str, int maxChars)
    {
        int written = 0;
        for (auto it = str.begin(); it != str.end() && written < maxChars; ++it, ++written)
        {
            uint32_t cp = (uint32_t)(*it);
            dst[written * 4 + 0] = (uint8_t)(cp);
            dst[written * 4 + 1] = (uint8_t)(cp >> 8);
            dst[written * 4 + 2] = (uint8_t)(cp >> 16);
            dst[written * 4 + 3] = (uint8_t)(cp >> 24);
        }
    }

    static uint32_t tcToMs(const Timecode& tc, FrameRate fps)
    {
        // Shared conversion (drop-frame aware, exact rates).
        return (uint32_t) juce::jmax(0.0, timecodeToMs(tc, fps));
    }

    // ============================================================
    juce::Array<NetworkInterface> availableInterfaces;
    std::unique_ptr<juce::DatagramSocket> broadcastSocket, timeSocket;
    std::unique_ptr<juce::DatagramSocket> listenerSocket;     // receives Requests on kListenerPort
    std::unique_ptr<juce::DatagramSocket> discoverySocket;    // receives OptIns on port 60000
    std::unique_ptr<juce::DatagramSocket> unicastSocket;      // sends Metrics/Metadata to slaves
    juce::String broadcastIp = "255.255.255.255", bindIp = "0.0.0.0";
    int selectedInterface = -1;
    bool running = false;
    int globalOffsetMs = 0;  // venue-wide latency comp, see setGlobalOffsetMs
    LayerData layers[kPacketLayers] = {};
    LayerData emptyLayer;
    SlaveNode slaves[kMaxSlaves] = {};
    // Fixed: two STCs on one network (a main and a backup) send the same
    // NodeID and NodeName, and each takes the other's OptIn for its own
    // (pollDiscovery).  Left as is: what receivers do with two nodes of one
    // ID is not known without a capture (AUDIT NET-8, deferred).
    char nodeName[9] = {};
    uint16_t nodeId = 0x5443;
    uint8_t seq = 0;
    uint32_t uptimeSeconds = 0, tickCount = 0;

    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(TCNetOutput)
};