TimecodeEngine.h

// Super Timecode Converter
// Copyright (c) 2026 Fiverecords -- MIT License
// https://github.com/fiverecords/SuperTimecodeConverter

#pragma once
#include <JuceHeader.h>
#include "TimecodeCore.h"
#include "MtcInput.h"
#include "MtcOutput.h"
#include "ArtnetInput.h"
#include "ArtnetOutput.h"
#include "LANetTimecodeInput.h"
#include "LANetTimecodeOutput.h"
#include "LtcInput.h"
#include "LtcOutput.h"
#include "ProDJLinkInput.h"
#include "StageLinQInput.h"
#include "OnAirFollow.h"
#include "HippotizerInput.h"
#include "HippotizerOutput.h"
#include "WinampInput.h"
#include <cmath>
#include "DbServerClient.h"
#include "TriggerOutput.h"
#include "LinkBridge.h"
#include "AudioThru.h"
#include "AudioBpmInput.h"
#include "GeneratorAudioPlayer.h"
#include "AppSettings.h"
#include "MixerMap.h"
#include <memory>

//==============================================================================
// TimecodeEngine -- one independent routing pipeline
//
// Each engine owns: 1 input source -> N output destinations.
// AudioThru is only available on the primary engine (index 0).
//==============================================================================
// All public methods of TimecodeEngine are designed to be called exclusively
// from the JUCE message thread, which also runs tick(); the engine's own
// state needs no lock.  The protocol handlers run on their own threads
// (MIDI, network, audio) and publish what the engine reads through atomics,
// sequence locks (LTC, Art-Net and LA-Net in, the Pro DJ Link position) or
// short locks of their own, taken by the getters the engine calls (e.g.
// MtcInput's spin lock, WinampInput's position anchor, HippotizerInput's
// channel lock, a Pro DJ Link player's identity, DbServerClient's cache,
// StageLinQ's strings under a mutex).
inline constexpr int kPrimaryEngineIndex = 0;
inline constexpr int kMaxEngines = 8;

class TimecodeEngine
{
public:
    enum class InputSource { MTC, ArtNet, SystemTime, LTC, ProDJLink, StageLinQ, Hippotizer, Winamp, LANetTC };

    //--------------------------------------------------------------------------
    explicit TimecodeEngine(int index, const juce::String& name = {})
        : engineIndex(index),
          engineName(name.isEmpty() ? ("ENGINE " + juce::String(index + 1)) : name)
    {
        std::fill(std::begin(lastSentMixer), std::end(lastSentMixer), -1); lastMixerPktCount = 0;

        // Named in "IN USE BY <name>" when another engine's MTC is refused on
        // the port this engine streams on (DESIGN D32).
        mtcOutput.setOwnerName(engineName);

        // Only the primary engine (index 0) gets AudioThru
        if (index == kPrimaryEngineIndex)
            audioThru = std::make_unique<AudioThru>();

        // Re-seek the audio transport to the engine's current playhead
        // after every settled load, unless the generator is Stopped.
        // While Playing: attachReaderToTransport() sets
        // transport.setPosition(0) the moment the source is wired, but the
        // engine has been ticking forward for the duration of the load --
        // the audio played "late" until the operator paused and played;
        // the seek also starts the transport.  While Paused it only
        // positions the transport (seekSeconds does not start a paused
        // player): a click on the timeline while a load is pending turns
        // Stopped into Paused, and its own seek was dropped (AUDIT LTC-4),
        // and a play from Paused does not seek, so the audio started at 0
        // in the new file, or at the old position, while the timecode ran
        // from the click.  Stopped needs nothing: a play from Stopped
        // seeks first (generatorPlay).  Captured by juce::WeakReference so
        // a load completing after this engine has been destroyed (engines
        // can be removed at runtime) is a no-op rather than a
        // use-after-free.  Runs on the message thread (callAsync
        // dispatch), same context that owns genState and genCurrentMs, so
        // no atomics or locks needed.
        //
        // First the player's own loop is settled against the timecode loop
        // (#24): the request could only guess it, the file's length being
        // unknown until now (syncGeneratorPlayerLooping).  The seek is
        // seekGeneratorAudioToTimecode's: on the timecode loop's gapless path
        // a timecode before Start TC (an OSC jog there while the load was
        // pending) puts the audio at the file's tail, folded into the loop.
        generatorAudioPlayer.onLoadCompleted =
            [weak = juce::WeakReference<TimecodeEngine>(this)]()
            {
                auto* self = weak.get();
                if (self == nullptr) return;
                self->syncGeneratorPlayerLooping();
                if (self->genState == GeneratorState::Stopped) return;
                self->seekGeneratorAudioToTimecode();
            };
    }

    ~TimecodeEngine()
    {
        // Stop MIDI clock timer first (runs on HighResolutionTimer thread)
        setMidiClockEnabled(false);
        triggerOutput.stopMidi();
        triggerOutput.disconnectOsc();

        // Shutdown order: outputs first, then inputs
        stopMtcOutput();
        stopArtnetOutput();
        stopLANetTCOutput();
        stopLtcOutput();
        stopHippotizerOutput();
        stopThruOutput();
        stopMtcInput();
        stopArtnetInput();
        stopLANetTCInput();
        stopLtcInput();
        stopHippotizerInput();
        stopWinampInput();
        stopAudioBpm();
        // ProDJLink is shared -- not stopped per-engine
        // StageLinQ is shared -- not stopped per-engine
    }

    //==========================================================================
    // Identity
    //==========================================================================
    int getIndex() const { return engineIndex; }
    juce::String getName() const { return engineName; }
    void setName(const juce::String& name) { engineName = name; mtcOutput.setOwnerName(name); }
    bool isPrimary() const { return engineIndex == kPrimaryEngineIndex; }

    // Called after engine deletion to fix indices so isPrimary() stays correct
    // and AudioThru is created for the new primary engine if needed.
    // NOTE: The caller (MainComponent::removeEngine) is responsible for
    // restarting AudioThru on the new primary engine after reindexing,
    // because that requires UI state (device combos) that the engine doesn't own.
    void reindex(int newIndex)
    {
        // If we were the primary engine and are being moved away, destroy AudioThru
        // to avoid a stale handler referencing a deleted LtcInput.
        if (engineIndex == kPrimaryEngineIndex && newIndex != kPrimaryEngineIndex)
        {
            stopThruOutput();
            audioThru.reset();
            outputThruEnabled = false;
        }

        engineIndex = newIndex;

        // Create AudioThru if we just became the primary engine
        if (newIndex == kPrimaryEngineIndex && !audioThru)
            audioThru = std::make_unique<AudioThru>();
    }

    //==========================================================================
    // Input source
    //==========================================================================
    InputSource getActiveInput() const { return activeInput; }
    FrameRate getCurrentFps() const { return currentFps; }
    /// Message thread, like the tick() that writes it.  (A spin lock taken
    /// here and nowhere else guarded nothing and is gone, AUDIT ENG-16.)
    Timecode getCurrentTimecode() const { return currentTimecode; }
    bool isSourceActive() const { return sourceActive; }
    bool getUserOverrodeLtcFps() const { return userOverrodeLtcFps; }

    void setInputSource(InputSource source)
    {
        // Stop current input
        switch (activeInput)
        {
            case InputSource::MTC:    stopMtcInput();    break;
            case InputSource::ArtNet: stopArtnetInput(); break;
            case InputSource::LTC:    stopLtcInput();    break;
            case InputSource::ProDJLink: stopProDJLinkInput(); break;
            case InputSource::StageLinQ: stopStageLinQInput(); break;
            case InputSource::Hippotizer: stopHippotizerInput(); break;
            case InputSource::Winamp:     stopWinampInput();     break;
            case InputSource::LANetTC: stopLANetTCInput(); break;
            default: break;
        }

        userOverrodeLtcFps = false;
        mtcParkedValid = false;
        forwardParkedLocate = false;
        // The generator's parked locate starts afresh with the new source:
        // nothing is told for the switch itself (updateGeneratorParkedLocate).
        genParkedPending = false;
        genParkedGivenValid = false;
        activeInput = source;
        sourceActive = false;
        // Switching the input source is an explicit user transition; any
        // pending natural-EOF marker from the Generator path is no longer
        // relevant and must not survive the round-trip.
        genEndedAtEof = false;

        // Releasing the Generator audio output device when the engine
        // switches to a non-Generator input is important for shows where
        // multiple engines might want to share the same physical output.
        // Without this, an engine that previously had AUDIO PLAYBACK on
        // would keep its device open even after the user switched its
        // input to MTC / LTC / etc., effectively locking that device out
        // of any other engine's selector even though no playback is or
        // ever could be happening on this engine again.
        //
        // The toggle button state and persisted settings are NOT touched:
        // if the user switches the input back to the Generator later, the
        // device opens again exactly as it was, transparent to them.
        if (source != InputSource::SystemTime && generatorAudioPlayer.isDeviceOpen())
            generatorAudioPlayer.closeDevice();

        // A millisecond source cannot have rate conversion (see
        // isMillisecondSource): drop it, and render at the user's chosen
        // output rate, which is the only rate such a source has.
        if (isMillisecondSource(source))
        {
            fpsConvertEnabled = false;
            currentFps = outputFps;
            setOutputFrameRate(outputFps);
        }

        // Reset the TrackMap cache on every source change: the track, its
        // offset and its BPM multiplier belong to the source that found
        // them.  It used to survive a switch to another DJ source or to
        // Winamp, so Winamp without a title went on applying the previous
        // DJ track's offset (AUDIT ENG-13).
        trackMapped = false;
        cachedTrackId = 0;
        cachedLoadedPlayer = cachedLoadedSlot = 0;
        cachedMediaChanges = 0;
        cachedOffH = cachedOffM = cachedOffS = cachedOffF = 0;
        cachedBpmMultiplier = 0;
        bpmPlayerOverride = kBpmNoOverride;
        cachedTrackArtist.clear();
        cachedTrackTitle.clear();
        cachedTrackDurationSec = 0;
        dbRequestIp.clear();
        // Disable Link to avoid publishing stale tempo on the network
        // (unless audio BPM is active -- it will keep feeding Link); the DJ
        // sources and Winamp keep it.
        if (source != InputSource::ProDJLink && source != InputSource::StageLinQ
            && source != InputSource::Winamp && !audioBpmEnabled)
            linkBridge.setEnabled(false);

        // The mixer forward's DMX frame and its send-once memory belong to
        // the source that filled them (AUDIT ENG-10): after StageLinQ, Pro DJ
        // Link went on sending the Denon faders every 100 ms in the channels
        // it did not write.  The next source starts from an empty frame and
        // sends every value again.
        resetMixerForward();

        // Clear armed cues whenever the input source changes.  The list
        // was populated by either a TrackMap entry (ProDJLink / StageLinQ)
        // or a Generator preset (SystemTime); leaving any of them, the old
        // entries are no longer valid and would fire spuriously against
        // unrelated playhead values.  MainComponent will repopulate via
        // setGeneratorCuePoints() when the new source is SystemTime with
        // a preset selected.
        armedCues.clear();
        rawGeneratorCues.clear();
        lastCueCheckMs = cueFlagsAtMs = cueStopRawMs = 0;
        cueArmPending = cueWasPlaying = cueRelocated = cueFlagsAtIncl = false;

        // Note: actual start is deferred to the caller (MainComponent),
        // which gathers device params from UI before calling startXxxInput().
        if (source == InputSource::SystemTime)
        {
            sourceActive = genClockMode;  // clock mode: always active; transport mode: wait for Play
            genLastTickTime = juce::Time::getMillisecondCounterHiRes();  // prevent time jump
            clockFollower.reset();        // clock mode starts exactly on the wall clock
        }
    }

    void setFrameRate(FrameRate fps)
    {
        const bool fpsChanged = (currentFps != fps);
        currentFps = fps;
        FrameRate outRate = getEffectiveOutputFps();
        mtcOutput.setFrameRate(outRate);
        artnetOutput.setFrameRate(outRate);
        laNetTCOutput.setFrameRate(outRate);
        ltcOutput.setFrameRate(outRate);
        hippotizerOutput.setFrameRate(outRate);

        // Re-derive Generator armed cues with the new fps so the frame
        // component of each cue's TC maps to the right absolute-ms.  Only
        // matters when there is an active Generator preset; the TrackMap
        // armed cues use ms directly and don't need rearming here.
        if (fpsChanged && ! rawGeneratorCues.empty())
            rearmGeneratorCues();
    }

    void setUserOverrodeLtcFps(bool v) { userOverrodeLtcFps = v; }

    //==========================================================================
    // FPS conversion
    //==========================================================================
    bool isFpsConvertEnabled() const { return fpsConvertEnabled; }
    FrameRate getOutputFps() const { return outputFps; }
    Timecode getOutputTimecode() const { return outputTimecode; }

    /// LTC output holes (#19) are counted on the audio thread; here, once per
    /// tick on the message thread, each new one is written to ltc_gaps.log
    /// next to settings.json: when it happened, on which engine and device,
    /// how long the callback was late and what the device period was.  A
    /// logic-analyser capture can then be lined up with STC's own view of
    /// the event -- @mungewell asked for exactly this.  Nothing is written
    /// while no gaps occur.  The file is bounded (AUDIT LTC-5, BENCH B32):
    /// see appendLtcGapLogLine.
    void logLtcOutputGaps()
    {
        const auto stamp = [] {
            const auto now = juce::Time::getCurrentTime();
            return now.formatted("%Y-%m-%d %H:%M:%S") + "." + juce::String(now.getMilliseconds()).paddedLeft('0', 3);
        };

        const int gaps = ltcOutput.getOutputGapCount();
        if (gaps != lastLoggedGapCount)
        {
            lastLoggedGapCount = gaps;
            juce::String line = stamp()
                              + "  " + engineName
                              + "  " + ltcOutput.getCurrentDeviceName()
                              + "  gap " + juce::String(ltcOutput.getLastGapMs(), 1) + " ms"
                              + "  period " + juce::String(ltcOutput.getActualBufferSize() * 1000.0
                                                           / juce::jmax(1.0, ltcOutput.getActualSampleRate()), 1) + " ms"
                              + (ltcOutput.getLastGapReseeded() ? "  hole, re-seeded" : "  late, absorbed")
                              + "  total " + juce::String(gaps) + "\n";
            appendLtcGapLogLine(line);
        }

        // Value corrections and re-seeds (DESIGN D30), same file, so a capture of a
        // skipped or repeated frame can be lined up with STC's own view.
        const int events = ltcOutput.getTrackEventCount();
        if (events != lastLoggedTrackCount)
        {
            lastLoggedTrackCount = events;
            const char* what = "?";
            switch (ltcOutput.getLastTrackKind())
            {
                case 1: what = "ahead or held: repeated a frame"; break;
                case 2: what = "behind: skipped a frame"; break;
                case 3: what = "seek: snapped"; break;
                case 4: what = "re-seed after hole"; break;
                case 5: what = "re-seed after snap"; break;
            }
            juce::String line = stamp()
                              + "  " + engineName
                              + "  track " + what
                              + "  d " + juce::String((int) ltcOutput.getLastTrackD())
                              + "  next " + ltcOutput.getLastTrackNext().toString()
                              + "  ref " + ltcOutput.getLastTrackRef().toString()
                              + "  total " + juce::String(events) + "\n";
            appendLtcGapLogLine(line);
        }
    }

private:
    /// One line into ltc_gaps.log (logLtcOutputGaps), the same text as
    /// always.  Every engine writes the same file, so its state is shared:
    /// message thread only (the audio thread only counts).  The path is
    /// worked out once -- AppSettings::getSettingsFile() creates the folder
    /// on every call -- and the size is followed from the bytes written.
    /// Past kLtcGapLogMaxBytes the file moves to ltc_gaps.log.1, replacing
    /// the previous one, and a new one starts: the two hold about twice that
    /// at most.  The "late, absorbed" lines BENCH B32 calls normal used to
    /// make it grow without bound on every machine (AUDIT LTC-5).  If the
    /// move fails (the .1 held open elsewhere), writing goes on and the move
    /// is tried again at the next line.
    static void appendLtcGapLogLine(const juce::String& line)
    {
        struct GapLog { juce::File file; juce::int64 bytes = -1; };
        static GapLog log;
        if (log.bytes < 0)
        {
            log.file  = AppSettings::getSettingsFile().getSiblingFile("ltc_gaps.log");
            log.bytes = log.file.getSize();   // 0 when there is none yet
        }
        if (log.bytes >= kLtcGapLogMaxBytes)
        {
            log.file.moveFileTo(log.file.getSiblingFile("ltc_gaps.log.1"));
            log.bytes = log.file.getSize();   // 0 unless the move failed
        }
        if (log.file.appendText(line))
            log.bytes += (juce::int64) line.getNumBytesAsUTF8() + 1;   // appendText writes the '\n' as "\r\n"
    }
    static constexpr juce::int64 kLtcGapLogMaxBytes = 5 * 1024 * 1024;

public:
    /// Playback speed of the source as a ratio (1.0 = nominal), for
    /// protocols that carry it (TCNet layer speed).  DJ sources: the PLL's
    /// pitch; everything else runs at 1.0.  0.0 while frozen or stopped.
    double getSourceSpeedRatio() const
    {
        if (activeInput == InputSource::ProDJLink || activeInput == InputSource::StageLinQ)
            return (activeInput == InputSource::ProDJLink && pdlTcFrozen) ? 0.0 : pll.pitch;
        return sourceActive ? 1.0 : 0.0;
    }

    /// Track position in ms of the followed deck, read from the input as it
    /// stands (UI cursor, cue-point editor, beat synthesis, TCNet layer
    /// position).  Despite the name, Pro DJ Link and StageLinQ give the
    /// latest packet's position (on an NXS2 the input's beat-derived
    /// estimate, not the engine's grid position), without the engine's
    /// interpolation and without the Track Map offset; Winamp gives its
    /// position as polled and interpolated by WinampInput.  0 for every
    /// other source.  So TCNet carries this raw position next to an
    /// interpolated, offset timecode (AUDIT ENG-14).  Message thread.
    uint32_t getSmoothedPlayheadMs() const
    {
        if (activeInput == InputSource::StageLinQ && sharedStageLinQ != nullptr)
        {
            int ep = getEffectivePlayer();
            return (ep >= 1) ? sharedStageLinQ->getPlayheadMs(ep) : 0;
        }
        if (activeInput == InputSource::Winamp)
        {
            int32_t p = winampInput.getPositionMs();
            return p > 0 ? (uint32_t)p : 0;
        }
        if (activeInput != InputSource::ProDJLink) return 0;  // non-DJ sources use tcToMs in TCNet
        if (sharedProDJLink == nullptr) return 0;
        int ep = getEffectivePlayer();
        if (ep < 1) return 0;
        return sharedProDJLink->getPlayheadMs(ep);
    }

    /// Play position as 0.0-1.0 ratio (for waveform cursor), from the same
    /// raw input position as getSmoothedPlayheadMs (AUDIT ENG-14).
    /// For Winamp this is position / duration as reported by the player.
    /// While the duration is still being decoded (very first ~1 s of a
    /// freshly loaded VBR file) the ratio is held at 0 to avoid jumping
    /// the cursor to a meaningless value.
    float getSmoothedPlayPositionRatio() const
    {
        if (activeInput == InputSource::StageLinQ && sharedStageLinQ != nullptr)
        {
            int ep = getEffectivePlayer();
            return (ep >= 1) ? sharedStageLinQ->getPlayPositionRatio(ep) : 0.0f;
        }
        if (activeInput == InputSource::Winamp)
        {
            int32_t posMs = winampInput.getPositionMs();
            int32_t durSec = winampInput.getDurationSec();
            if (durSec <= 0 || posMs <= 0) return 0.0f;
            float r = (float)posMs / (float)(durSec * 1000);
            return juce::jlimit(0.0f, 1.0f, r);
        }
        if (activeInput != InputSource::ProDJLink) return 0.0f;
        if (sharedProDJLink == nullptr) return 0.0f;
        int ep = getEffectivePlayer();
        if (ep < 1) return 0.0f;
        return sharedProDJLink->getPlayPositionRatio(ep);
    }

    FrameRate getEffectiveOutputFps() const
    {
        return fpsConvertEnabled ? outputFps : currentFps;
    }

    void setFpsConvertEnabled(bool enabled)
    {
        if (enabled && isMillisecondSource(activeInput))
            enabled = false;   // meaningless for a ms source; never allow the invariant to break
        fpsConvertEnabled = enabled;
        if (!enabled)
        {
            outputFps = currentFps;
            setOutputFrameRate(currentFps);
        }
    }

    /// Two output channel selections clash when they touch the same channel;
    /// -1 means the stereo pair (channels 0 and 1).
    static bool channelsOverlap(int a, int b)
    {
        auto touches = [](int sel, int ch) { return sel == -1 ? (ch == 0 || ch == 1) : sel == ch; };
        if (a == -1 && b == -1) return true;
        if (a == -1) return touches(a, b);
        if (b == -1) return touches(b, a);
        return a == b;
    }

    /// Sources that deliver a millisecond position rather than frames: the
    /// user's output rate IS their rate, so rate conversion has no meaning
    /// for them and currentFps must always equal outputFps.  The UI hides
    /// FPS CONVERT for these; the engine enforces it here regardless of what
    /// a settings file says (see setInputSource / setFpsConvertEnabled).
    static bool isMillisecondSource(InputSource src)
    {
        return src == InputSource::ProDJLink || src == InputSource::StageLinQ
            || src == InputSource::Winamp;
    }

    void setOutputFrameRate(FrameRate fps)
    {
        outputFps = fps;
        // A millisecond source has no inherent frame rate: the user's fps
        // choice IS the current fps.  (StageLinQ was missing from this list,
        // so a stale outputFps could disagree with currentFps and the
        // timecode was built at one rate and converted as if at the other.)
        if (isMillisecondSource(activeInput))
            currentFps = fps;
        FrameRate outRate = getEffectiveOutputFps();
        mtcOutput.setFrameRate(outRate);
        artnetOutput.setFrameRate(outRate);
        laNetTCOutput.setFrameRate(outRate);
        ltcOutput.setFrameRate(outRate);
        hippotizerOutput.setFrameRate(outRate);
    }

    //==========================================================================
    // Output enables & offsets
    //==========================================================================
    bool isOutputMtcEnabled() const     { return outputMtcEnabled; }
    bool isOutputArtnetEnabled() const  { return outputArtnetEnabled; }
    bool isOutputLtcEnabled() const     { return outputLtcEnabled; }
    bool isOutputThruEnabled() const    { return outputThruEnabled; }
    bool isOutputLANetTCEnabled() const { return outputLANetTCEnabled; }

    void setOutputMtcEnabled(bool e)    { outputMtcEnabled = e; }
    void setOutputArtnetEnabled(bool e) { outputArtnetEnabled = e; }
    void setOutputLtcEnabled(bool e)    { outputLtcEnabled = e; }
    void setOutputThruEnabled(bool e)   { outputThruEnabled = e; }
    void setOutputTcnetEnabled(bool e)  { outputTcnetEnabled = e; }
    void setOutputLANetTCEnabled(bool e) { outputLANetTCEnabled = e; }
    bool isOutputTcnetEnabled() const   { return outputTcnetEnabled; }
    void setOutputHippoEnabled(bool e)  { outputHippoEnabled = e; }
    bool isOutputHippoEnabled() const   { return outputHippoEnabled; }
    void setTcnetLayer(int l)           { tcnetLayer = juce::jlimit(0, 3, l); }
    int  getTcnetLayer() const          { return tcnetLayer; }

    int getMtcOutputOffset() const      { return mtcOutputOffset; }
    int getArtnetOutputOffset() const   { return artnetOutputOffset; }
    int getLtcOutputOffset() const      { return ltcOutputOffset; }
    int getLANetTCOutputOffset() const  { return laNetTCOutputOffset; }

    // Offsets are clamped to the +/-30 frame range the UI and the settings
    // loader use, so every entry point agrees.
    void setMtcOutputOffset(int v)      { mtcOutputOffset = juce::jlimit(-30, 30, v); }
    void setArtnetOutputOffset(int v)   { artnetOutputOffset = juce::jlimit(-30, 30, v); }
    void setLtcOutputOffset(int v)      { ltcOutputOffset = juce::jlimit(-30, 30, v); }

    // LTC user-bits source modes (issue #13 follow-up).
    static constexpr int kUserBitsManual     = 0;  // fixed operator-entered value
    static constexpr int kUserBitsFromLtcIn  = 1;  // passthrough from this engine's LTC input
    static constexpr int kUserBitsSystemDate = 2;  // current local date and time zone, SMPTE ST 309
    static constexpr int kUserBitsName       = 3;  // four ISO characters, SMPTE 12M-1 sec. 8.4.2
    static constexpr int kUserBitsDebugBuffers = 4; // DEBUG: audio buffer counter in every group (#19)

    /// Pack four characters into the 32-bit user-bits word per SMPTE
    /// ST 12-1 sec. 8.4.2: four ISO codes, each occupying two binary
    /// groups.  The FIRST character goes in binary groups 7 and 8, with its
    /// least significant nibble in group 7 and its most significant nibble
    /// in group 8; the remaining three characters go in groups 5/6, 3/4 and
    /// 1/2.  Combined with the group ordering used by the encoder (group 1
    /// is the most significant hex digit of the displayed word), character
    /// one therefore lands in the LOW nibbles of the word.
    /// Seven-bit ISO codes are converted to eight-bit by clearing bit 7,
    /// as the standard requires.  Short strings are padded with spaces.
    static uint32_t packNameUserBits(const juce::String& text)
    {
        juce::String t = text.substring(0, 4);
        while (t.length() < 4) t += " ";

        uint32_t word = 0;
        for (int i = 0; i < 4; ++i)
        {
            auto c = (uint32_t)(t[i]) & 0x7Fu;   // force to 8-bit ISO, bit 7 = 0
            // Character i occupies groups (7,8) for i=0, (5,6) for i=1,
            // (3,4) for i=2, (1,2) for i=3.  Group g holds hex digit
            // (8-g) counted from the low end of the word.
            const int lowGroup = 7 - i * 2;          // 7, 5, 3, 1
            const int shiftLow  = (lowGroup - 1) * 4; // group g = nibble g-1 of the word
            const int shiftHigh = lowGroup * 4;
            word |= (c & 0x0Fu) << shiftLow;         // LS nibble in lower group
            word |= ((c >> 4) & 0x0Fu) << shiftHigh; // MS nibble in next group
        }
        return word;
    }

    /// LTC user bits, set from an operator-entered hex string (up to 8 hex
    /// digits; blank or unparseable = 0).  Stores the normalised text and,
    /// in MANUAL mode, pushes the 32-bit value straight to the encoder.
    /// In the dynamic modes the stored text is kept but the encoder is fed
    /// by refreshDynamicUserBits() instead.
    void setLtcUserBitsHex(const juce::String& hex)
    {
        ltcUserBitsHex = normaliseUserBitsHex(hex);
        pushManualUserBits();
    }

    /// MANUAL mode only: send the typed digits in the opposite group order,
    /// for readers that print binary group 1 as the most significant digit
    /// (the GoPro convention, and STC's own until 2026-09).  ST 12 sets no
    /// order for free-form hex, so this is the operator matching the reader
    /// in front of them.  Meaningless in the other modes: DATE and NAME are
    /// addressed by group number as the standards specify, and FROM LTC IN
    /// passes the groups through unchanged.
    void setLtcUserBitsReversed(bool reversed)
    {
        ltcUserBitsReversed = reversed;
        pushManualUserBits();
    }
    bool isLtcUserBitsReversed() const { return ltcUserBitsReversed; }

    static uint32_t reverseNibbles(uint32_t v)
    {
        uint32_t r = 0;
        for (int i = 0; i < 8; ++i) r |= ((v >> (i * 4)) & 0xFu) << ((7 - i) * 4);
        return r;
    }

    void pushManualUserBits()
    {
        if (ltcUserBitsMode != kUserBitsManual) return;
        const uint32_t v = parseUserBitsHex(ltcUserBitsHex);
        ltcOutput.setUserBits(ltcUserBitsReversed ? reverseNibbles(v) : v);
    }

    /// Four-character label used by the NAME user-bits mode.  Blank falls
    /// back to STC<engine number>.
    void setLtcUserBitsName(const juce::String& n)
    {
        ltcUserBitsName = n.substring(0, 4);
        lastSystemDateCheckMs = 0.0;
    }
    juce::String getLtcUserBitsName() const { return ltcUserBitsName; }

    /// Output latency compensation currently applied to the LTC encoder, in
    /// ms.  Derived from the audio device, not a user setting.
    double getLtcLatencyCompMs() const { return ltcOutput.getLatencyCompensationMs(); }

    /// User-bits source mode.  Switching back to MANUAL immediately restores
    /// the operator's stored value so the field and the wire agree again.
    void setLtcUserBitsMode(int mode)
    {
        ltcUserBitsMode = juce::jlimit(kUserBitsManual, kUserBitsDebugBuffers, mode);
        pushManualUserBits();
        ltcOutput.setBufferCounterUserBits(ltcUserBitsMode == kUserBitsDebugBuffers);
        // Binary group flags say what the groups carry (12M-1 sec. 8.4.1):
        // NAME declares an eight-bit character set (BGF0), DATE declares
        // ST 309 date and time zone (BGF2, ST 309 Table 3, unspecified clock
        // reference); FROM LTC IN takes the input's from the next tick on
        // (refreshDynamicUserBits); the other modes are free-form data,
        // BGF 0/0/0.
        ltcOutput.setBinaryGroupFlags(ltcUserBitsMode == kUserBitsName       ? 0x1
                                    : ltcUserBitsMode == kUserBitsSystemDate ? 0x4
                                    : 0x0);
        lastSystemDateCheckMs = 0.0;   // force a recompute on the next tick
    }
    int getLtcUserBitsMode() const { return ltcUserBitsMode; }

    /// The value currently going out on the wire, whatever the mode.
    uint32_t getEffectiveLtcUserBits() const { return ltcOutput.getUserBits(); }

    /// SMPTE ST 309:2012 Table 2 -- time zone code (0-63) for a local offset
    /// from UTC in minutes, DST already included in the offset.  The code's
    /// two hex digits read as decimal for whole hours: 00 = UTC, 01-12 =
    /// UTC-01:00 .. UTC-12:00, 13-25 = UTC+13:00 down to UTC+01:00.  Half
    /// hours: 0A-0F = -00:30 .. -05:30, 1A-1F = -06:30 .. -11:30, 3F-3A =
    /// +00:30 .. +05:30, 2F-2A = +06:30 .. +11:30; 32 = +12:45 (Chatham).
    /// Anything the table has no code for is 39, "unknown".
    static uint8_t st309TimeZoneCode(int offsetMinutes)
    {
        const bool negative = offsetMinutes < 0;
        const int  absMin   = std::abs(offsetMinutes);
        const int  hours    = absMin / 60;
        const int  minutes  = absMin % 60;
        auto decimalAsHex = [](int n) -> uint8_t { return (uint8_t)(((n / 10) << 4) | (n % 10)); };

        if (minutes == 0)
        {
            if (hours == 0) return 0x00;
            if (negative)  { if (hours <= 12) return decimalAsHex(hours); }
            else           { if (hours <= 13) return decimalAsHex(26 - hours); }
        }
        else if (minutes == 30)
        {
            if (negative)  { if (hours <= 5) return (uint8_t)(0x0A + hours);
                             if (hours <= 11) return (uint8_t)(0x1A + hours - 6); }
            else           { if (hours <= 5) return (uint8_t)(0x3F - hours);
                             if (hours <= 11) return (uint8_t)(0x2F - (hours - 6)); }
        }
        else if (minutes == 45 && !negative && hours == 12)
            return 0x32;
        return 0x39;
    }

    /// Inverse of st309TimeZoneCode.  Returns false for codes the table
    /// leaves undefined, deprecated, user-defined or unknown.
    static bool st309OffsetMinutesForCode(uint8_t code, int& offsetMinutes)
    {
        for (int m = -12 * 60; m <= 13 * 60; m += 15)
            if (st309TimeZoneCode(m) == code && code != 0x39)
            {
                offsetMinutes = m;
                return true;
            }
        return false;
    }

    static juce::String st309ZoneText(uint8_t code)
    {
        int m = 0;
        if (!st309OffsetMinutesForCode(code, m))
            return code == 0x38 ? "user-defined zone"
                 : code == 0x39 ? "zone unknown"
                 : "zone code " + juce::String::toHexString(code).paddedLeft('0', 2).toUpperCase();
        if (m == 0) return "UTC";
        const int a = std::abs(m);
        return "UTC" + juce::String(m < 0 ? "-" : "+")
             + juce::String(a / 60).paddedLeft('0', 2) + ":" + juce::String(a % 60).paddedLeft('0', 2);
    }

    /// Current local date and time zone packed per SMPTE ST 309:2012 (Table
    /// 1 and Table 4): binary groups 1-6 carry the date as YYMMDD with units
    /// before tens in ascending group order (3 September 2026 = groups 3 0 9
    /// 0 6 2), group 7 the low four bits of the zone code, group 8 its high
    /// two bits plus the DST flag (bit 2) and the MJD flag (bit 3, 0 = YYMMDD
    /// with the time address in local time).  Group 1 is the least
    /// significant hex digit of the 32-bit word, as everywhere else in STC,
    /// so the word reads "<zone><date>" in hex: 3 September 2026 in Central
    /// European summer time is 0x64260903.
    /// Emitted with BGF2 = 1 (ST 309 Table 3, unspecified clock reference).
    static uint32_t systemDateUserBits()
    {
        const auto now = juce::Time::getCurrentTime();
        const int  yy  = juce::jlimit(0, 99, now.getYear() % 100);
        const int  mm  = now.getMonth() + 1;      // JUCE months are 0-based
        const int  dd  = now.getDayOfMonth();
        const uint8_t tz  = st309TimeZoneCode(now.getUTCOffsetSeconds() / 60);
        const bool    dst = now.isDaylightSavingTime();

        const uint32_t bg1 = (uint32_t)(dd % 10), bg2 = (uint32_t)(dd / 10);
        const uint32_t bg3 = (uint32_t)(mm % 10), bg4 = (uint32_t)(mm / 10);
        const uint32_t bg5 = (uint32_t)(yy % 10), bg6 = (uint32_t)(yy / 10);
        const uint32_t bg7 = (uint32_t)(tz & 0x0F);
        const uint32_t bg8 = (uint32_t)((tz >> 4) & 0x03) | (dst ? 0x4u : 0u);   // MJD flag 0
        return  bg1 | (bg2 << 4) | (bg3 << 8) | (bg4 << 12)
             | (bg5 << 16) | (bg6 << 20) | (bg7 << 24) | (bg8 << 28);
    }
    /// Normalised user-bits hex ("" when zero/unset), for the UI and saving.
    juce::String getLtcUserBitsHex() const { return ltcUserBitsHex; }

    /// Parse up to 8 hex digits into a 32-bit user-bits word (0 on empty).
    static uint32_t parseUserBitsHex(const juce::String& hex)
    {
        juce::String h = hex.retainCharacters("0123456789abcdefABCDEF");
        if (h.isEmpty()) return 0;
        if (h.length() > 8) h = h.getLastCharacters(8);  // low 32 bits win
        return (uint32_t) h.getHexValue64();
    }
    /// Canonical form: hex chars only, upper-case, no leading zeros ("" if 0).
    static juce::String normaliseUserBitsHex(const juce::String& hex)
    {
        uint32_t v = parseUserBitsHex(hex);
        if (v == 0) return {};
        return juce::String::toHexString((juce::int64) v).toUpperCase();
    }

    /// Human reading of a user-bits word for the UI, always with the raw 8
    /// hex digits.  With the binary group flags from the decoder it can say
    /// what the sender declared: ST 309 date and zone (BGF2 = 1, BGF0 = 0),
    /// or four eight-bit characters (BGF0 = 1).  With no flags it falls back
    /// to the BCD heuristics: user bits are conventionally BCD, one decimal
    /// digit per 4-bit group, so when every group holds 0-9 the hex string
    /// IS the decimal reading, shown as a date when it parses as a plausible
    /// YYYYMMDD.  (A binary decimal integer would render 0x20260724 as
    /// 539300644, meaningless for the date/reel conventions these bits
    /// carry.)
    static juce::String describeUserBits(uint32_t v, uint8_t bgf = 0)
    {
        juce::String hex = juce::String::toHexString((juce::int64) v)
                               .paddedLeft('0', 8).toUpperCase();
        auto group = [v](int g) -> int { return (int)((v >> ((g - 1) * 4)) & 0xF); };   // g = 1..8, BG1 = low nibble

        if ((bgf & 0x5) == 0x4)   // ST 309 (Table 3): BGF2 = 1, BGF0 = 0
        {
            const uint8_t tz  = (uint8_t)(group(7) | ((group(8) & 0x3) << 4));
            const bool    dst = (group(8) & 0x4) != 0;
            const bool    mjd = (group(8) & 0x8) != 0;
            juce::String date;
            if (!mjd)
            {
                const int dd = group(2) * 10 + group(1), mm = group(4) * 10 + group(3), yy = group(6) * 10 + group(5);
                if (mm >= 1 && mm <= 12 && dd >= 1 && dd <= 31)
                    date = "20" + juce::String(yy).paddedLeft('0', 2) + "-"
                         + juce::String(mm).paddedLeft('0', 2) + "-" + juce::String(dd).paddedLeft('0', 2);
            }
            else
            {
                // Six BCD digits, ascending magnitude in groups 1-6 (Table 5).
                long mjdDays = 0;
                for (int g = 6; g >= 1; --g) mjdDays = mjdDays * 10 + group(g);
                date = "MJD " + juce::String((juce::int64) mjdDays) + " = " + civilDateFromMjd(mjdDays) + " UTC,";
            }
            if (date.isEmpty()) return hex + "  (ST 309, invalid date)";
            return hex + "  (" + date + " " + st309ZoneText(tz) + (dst ? " DST" : "") + ")";
        }

        if ((bgf & 0x1) == 0x1)   // eight-bit character set (12M-1 sec. 8.4.2)
        {
            juce::String text;
            for (int i = 0; i < 4; ++i)
            {
                const int lowGroup = 7 - i * 2;                 // same layout as packNameUserBits
                const int c = group(lowGroup) | (group(lowGroup + 1) << 4);
                text += (c >= 0x20 && c < 0x7F) ? juce::String::charToString((juce::juce_wchar) c) : juce::String(".");
            }
            return hex + "  (\"" + text + "\")";
        }

        bool allDecimal = true;
        for (int g = 0; g < 8; ++g)
            if (((v >> (g * 4)) & 0xF) > 9) { allDecimal = false; break; }
        if (!allDecimal || v == 0)
            return hex;

        const int yyyy = (int) hex.substring(0, 4).getIntValue();
        const int mm   = (int) hex.substring(4, 6).getIntValue();
        const int dd   = (int) hex.substring(6, 8).getIntValue();
        if (yyyy >= 1900 && yyyy <= 2099 && mm >= 1 && mm <= 12 && dd >= 1 && dd <= 31)
            return hex + "  (" + hex.substring(0, 4) + "-"
                       + hex.substring(4, 6) + "-" + hex.substring(6, 8) + ")";
        return hex + "  (dec " + hex.trimCharactersAtStart("0") + ")";
    }

    /// Civil date (YYYY-MM-DD) for a modified Julian date (Fliegel and Van
    /// Flandern, via JD = MJD + 2400001 for the noon integer day).
    static juce::String civilDateFromMjd(long mjd)
    {
        long l = mjd + 2400001 + 68569;
        const long n = 4 * l / 146097;
        l = l - (146097 * n + 3) / 4;
        const long i = 4000 * (l + 1) / 1461001;
        l = l - 1461 * i / 4 + 31;
        const long j = 80 * l / 2447;
        const long d = l - 2447 * j / 80;
        l = j / 11;
        const long m = j + 2 - 12 * l;
        const long y = 100 * (n - 49) + i + l;
        return juce::String((juce::int64) y) + "-" + juce::String((juce::int64) m).paddedLeft('0', 2)
             + "-" + juce::String((juce::int64) d).paddedLeft('0', 2);
    }
    void setTcnetOutputOffsetMs(int v)  { tcnetOutputOffsetMs = juce::jlimit(-1000, 1000, v); }
    void setLANetTCOutputOffset(int v)  { laNetTCOutputOffset = juce::jlimit(-30, 30, v); }

    int getTcnetOutputOffsetMs() const  { return tcnetOutputOffsetMs; }

    // On-air gate (requires CDJ on-air flag from DJM for engine to be active)
    bool isOnAirGateEnabled() const     { return onAirGateEnabled; }
    void setOnAirGateEnabled(bool e)    { onAirGateEnabled = e; }

    // ON AIR on StageLinQ, OFF AIR AT (DESIGN D34): the level at or below which a
    // deck counts as quiet -- 0 SILENCE (default), 1 -80 dB, 2 -60 dB,
    // 3 -40 dB (StageLinQ::onAirQuietLevel).  Pro DJ Link has no level:
    // the DJM decides on-air there.
    int  getOnAirQuietStep() const      { return onAirQuietStep; }
    void setOnAirQuietStep(int step)    { onAirQuietStep = juce::jlimit(0, 3, step); }

    /// Returns true if the on-air gate allows the engine to be active.
    /// If the gate is disabled, always returns true. Otherwise consults the
    /// CDJ's on-air flag -- this reflects the DJM mixer's full gating logic
    /// (channel fader + cross-fader + EQ kill + mute), computed by the mixer
    /// itself and transmitted to the CDJs. The DJ sees the same "ON AIR"
    /// indicator light on the CDJ display.
    bool isOnAirGateOpen() const
    {
        if (!onAirGateEnabled) return true;
        if (activeInput != InputSource::ProDJLink) return true;
        if (sharedProDJLink == nullptr) return true;
        // If no DJM is active on the network, the on-air flag is meaningless
        // (CDJs default to false without a DJM broadcast). Keep the gate open
        // so the engine isn't silenced just because the DJ unplugged the mixer.
        if (!sharedProDJLink->hasMixerFaderData()) return true;
        int ep = getEffectivePlayer();
        // If XF mode hasn't resolved yet (ep == 0), or the player has no
        // channel on this mixer, don't block the engine.  A DJM-V10 reports
        // channels 5 and 6; they stopped at 4 here while ON AIR follow
        // scans all six (AUDIT ENG-9).
        if (ep < 1 || ep > sharedProDJLink->getMixerChannelCount()) return true;
        return sharedProDJLink->isPlayerOnAir(ep);
    }

    //==========================================================================
    // Protocol handlers -- direct access for device queries
    //==========================================================================
    MtcInput&     getMtcInput()     { return mtcInput; }
    MtcOutput&    getMtcOutput()    { return mtcOutput; }
    ArtnetInput&  getArtnetInput()  { return artnetInput; }
    ArtnetOutput& getArtnetOutput() { return artnetOutput; }
    LtcInput&     getLtcInput()     { return ltcInput; }
    LtcOutput&    getLtcOutput()    { return ltcOutput; }
    ProDJLinkInput& getProDJLinkInput()   { jassert(sharedProDJLink != nullptr); return *sharedProDJLink; }
    void setSharedProDJLinkInput(ProDJLinkInput* shared) { sharedProDJLink = shared; }
    StageLinQInput& getStageLinQInput()   { jassert(sharedStageLinQ != nullptr); return *sharedStageLinQ; }
    LANetTimecodeInput&   getLANetTCInput()   { return laNetTCInput; }
    LANetTimecodeOutput&  getLANetTCOutput()  { return laNetTCOutput; }
    void setSharedStageLinQInput(StageLinQInput* shared) { sharedStageLinQ = shared; }
    void setDbServerClient(DbServerClient* client) { dbClient = client; }
    int  getProDJLinkPlayer() const     { return proDJLinkPlayer; }
    /// Returns the physical player (1-6) actually being followed.
    /// Fixed mode: same as proDJLinkPlayer.
    /// XF / MASTER mode: the dynamically resolved player.
    int  getEffectivePlayer() const
    {
        return isAutoMode() ? resolvedXfPlayer : proDJLinkPlayer;
    }
    void setProDJLinkPlayer(int p)
    {
        proDJLinkPlayer = juce::jlimit(1, kPlayerOnAir, p);
        resolvedXfPlayer = 0;  // force re-resolve on next tick
        resetProDJLinkCache();
        bpmPlayerOverride = kBpmNoOverride;
        lastSentClockBpm = -1.0f;
        lastSentOscBpm   = -1.0f;
    }

    AudioThru*    getAudioThru()    { return audioThru.get(); }

    //==========================================================================
    // Start / Stop input protocols
    //==========================================================================
    /// MTC input on device `deviceIndex` of the MIDI input list as it is
    /// now.  A negative index -- the operator's device is not listed, or
    /// none was picked -- opens nothing: STC never opens a MIDI port the
    /// operator did not pick.  It used to open the first device, and the
    /// next save then named that one in the settings (AUDIT UI-6).
    /// Message thread.
    bool startMtcInput(int deviceIndex)
    {
        stopMtcInput();
        mtcInput.refreshDeviceList();
        if (deviceIndex >= 0 && mtcInput.start(deviceIndex))
        {
            inputStatusText = "RX: " + mtcInput.getCurrentDeviceName();
            return true;
        }
        inputStatusText = (deviceIndex < 0) ? "NO MIDI DEVICE AVAILABLE" : "FAILED TO OPEN DEVICE";
        return false;
    }

    void stopMtcInput() { mtcInput.stop(); }

    bool startArtnetInput(int interfaceIndex)
    {
        stopArtnetInput();
        if (interfaceIndex < 0) interfaceIndex = 0;
        artnetInput.refreshNetworkInterfaces();
        if (artnetInput.start(interfaceIndex, 6454))
        {
            inputStatusText = "RX ON " + artnetInput.getBindInfo();
            if (artnetInput.didFallBackToAllInterfaces())
                inputStatusText += " [FALLBACK]";
            return true;
        }
        inputStatusText = "FAILED TO BIND PORT 6454";
        return false;
    }

    void stopArtnetInput() { artnetInput.stop(); }

    bool startLANetTCInput(int interfaceIndex)
    {
        stopLANetTCInput();
        if (interfaceIndex < 0) interfaceIndex = 0;
        laNetTCInput.refreshNetworkInterfaces();
        if (laNetTCInput.start(interfaceIndex, 8201))
        {
            inputStatusText = "RX ON " + laNetTCInput.getBindInfo();
            if (laNetTCInput.didFallBackToAllInterfaces())
                inputStatusText += " [FALLBACK]";
            return true;
        }
        inputStatusText = "FAILED TO BIND PORT 8201";
        return false;
    }

    void stopLANetTCInput() { laNetTCInput.stop(); }

    bool startLtcInput(const juce::String& typeName, const juce::String& devName,
                       int ltcChannel, int thruChannel = -1,
                       double sampleRate = 0, int bufferSize = 0)
    {
        stopLtcInput();
        if (devName.isEmpty()) { inputStatusText = "NO AUDIO DEVICE AVAILABLE"; return false; }

        if (ltcInput.start(typeName, devName, ltcChannel, thruChannel, sampleRate, bufferSize))
        {
            inputStatusText = "RX: " + ltcInput.getCurrentDeviceName()
                            + " Ch " + juce::String(ltcChannel + 1)
                            + " " + describeAudioFormat(ltcInput.getActualSampleRate(), ltcInput.getActualBufferSize());
            return true;
        }
        inputStatusText = "FAILED TO OPEN AUDIO DEVICE";
        return false;
    }

    void stopLtcInput()
    {
        stopThruOutput();
        ltcInput.stop();
    }

    //==========================================================================
    // Audio BPM detection (for non-DJ input sources)
    //==========================================================================
    bool startAudioBpm(const juce::String& typeName, const juce::String& devName,
                       int channel, double sampleRate = 0, int bufferSize = 0)
    {
        stopAudioBpm();
        if (devName.isEmpty()) return false;
        if (audioBpmInput.start(typeName, devName, channel, sampleRate, bufferSize))
        {
            audioBpmEnabled = true;
            return true;
        }
        return false;
    }

    void stopAudioBpm()
    {
        audioBpmEnabled = false;
        audioBpmInput.stop();
        lastSentClockBpm = -1.0f;
        lastSentOscBpm   = -1.0f;
    }

    bool isAudioBpmRunning() const { return audioBpmEnabled && audioBpmInput.getIsRunning(); }
    double getAudioBpm() const { return audioBpmInput.getBpm(); }
    double getAudioBpmConfidence() const { return audioBpmInput.getConfidence(); }
    bool hasAudioBpm() const { return isAudioBpmRunning() && audioBpmInput.hasBpm(); }
    float getAudioBpmPeakLevel() const { return audioBpmInput.getPeakLevel(); }

    AudioBpmInput& getAudioBpmInput() { return audioBpmInput; }
    const AudioBpmInput& getAudioBpmInput() const { return audioBpmInput; }

    //==========================================================================
    // Pro DJ Link input (shared across engines)
    //==========================================================================
    void resetProDJLinkCache()
    {
        trackMapped = false;
        cachedTrackId = 0;
        cachedLoadedPlayer = cachedLoadedSlot = 0;
        cachedMediaChanges = 0;
        dbRequestIp.clear();
        lastSeenTrackVersion = 0;
        cachedOffH = cachedOffM = cachedOffS = cachedOffF = 0;
        cachedTrackArtist.clear();
        cachedTrackTitle.clear();
        cachedTrackDurationSec = 0;
        armedCues.clear();
        lastCueCheckMs = cueFlagsAtMs = cueStopRawMs = 0;
        cueArmPending = cueWasPlaying = cueRelocated = cueFlagsAtIncl = false;
        pll.reset(); clearBeatGrid(); pdlTcFrozen = false; pdlLastPlayheadMs = 0; pdlLastAbsPosTs = 0.0;
        pdlSnapMs = 0.0; pdlSnapTime = 0.0; pdlSnapSpeed = 1.0;
        ltcOutput.setPitchMultiplier(1.0);
        std::memset(trigDmxBuffer, 0, sizeof(trigDmxBuffer));
        trigDmxHighWater = 0;
    }

    bool startProDJLinkInput(int player = 1)
    {
        resetProDJLinkCache();

        // Reset forward dedup
        lastSentClockBpm = -1.0f;
        lastSentOscBpm = -1.0f;

        // NOTE: do NOT overwrite currentFps here. The user's fps choice is
        // already set via setFrameRate() from settings load or the FPS buttons.
        // Previously this was "currentFps = outputFps" which would overwrite
        // a user-selected 25fps with outputFps=30 (the default) when loading
        // settings, because startProDJLinkInput runs after the initial load.

        proDJLinkPlayer = juce::jlimit(1, kPlayerOnAir, player);
        resolvedXfPlayer = 0;  // force resolve on first tick

        // NOTE: lastSeenTrackVersion stays at 0 (set by resetProDJLinkCache).
        // This forces the first tick to detect the current track as "changed"
        // and re-run metadata request + TrackMap lookup + cue point loading.
        // Without this, switching away from ProDJLink and back would leave
        // cachedTrackId=0 permanently because lastSeenTrackVersion already
        // matched the CDJ's current value, so "track changed" never fired.

        if (sharedProDJLink != nullptr && sharedProDJLink->getIsRunning())
        {
            inputStatusText = "LISTENING | " + sharedProDJLink->getBindInfo();
            return true;
        }
        inputStatusText = "WAITING FOR PRO DJ LINK...";
        return sharedProDJLink != nullptr;
    }

    void stopProDJLinkInput()
    {
        // Reset PLL and LTC encoder state so other sources start clean.
        pll.reset(); clearBeatGrid(); pdlTcFrozen = false; pdlLastPlayheadMs = 0; pdlLastAbsPosTs = 0.0;
        pdlSnapMs = 0.0; pdlSnapTime = 0.0; pdlSnapSpeed = 1.0;
        ltcOutput.setPitchMultiplier(1.0);
    }

    //==========================================================================
    // StageLinQ input (shared across engines)
    //==========================================================================
    bool startStageLinQInput(int player = 1)
    {
        resetProDJLinkCache();

        // Reset forward dedup
        lastSentClockBpm = -1.0f;
        lastSentOscBpm = -1.0f;
        std::fill(std::begin(lastSentSlqMixer), std::end(lastSentSlqMixer), -1);

        // Reset DMX buffer to avoid broadcasting stale Pioneer data
        std::memset(dmxBuffer, 0, sizeof(dmxBuffer));
        dmxHighWaterMark = 0;
        lastDmxSendTime = 0.0;

        // NOTE: do NOT overwrite currentFps here (see startProDJLinkInput).

        proDJLinkPlayer = sanitiseStageLinQPlayer(player);
        resolvedXfPlayer = 0;

        // NOTE: lastSeenTrackVersion stays at 0 (set by resetProDJLinkCache).
        // Same rationale as startProDJLinkInput -- forces track rediscovery
        // on the first tick after switching back to StageLinQ.

        if (sharedStageLinQ != nullptr && sharedStageLinQ->getIsRunning())
        {
            inputStatusText = "LISTENING | " + sharedStageLinQ->getBindInfo();
            return true;
        }
        inputStatusText = "WAITING FOR STAGELINQ...";
        return sharedStageLinQ != nullptr;
    }

    void stopStageLinQInput()
    {
        // Reset PLL and LTC encoder state so other sources start clean.
        pll.reset(); clearBeatGrid(); pdlTcFrozen = false; pdlLastPlayheadMs = 0; pdlLastAbsPosTs = 0.0;
        pdlSnapMs = 0.0; pdlSnapTime = 0.0; pdlSnapSpeed = 1.0;
        ltcOutput.setPitchMultiplier(1.0);
    }

    //==========================================================================
    // Hippotizer input (per-engine)
    //==========================================================================
    HippotizerInput& getHippotizerInput() { return hippotizerInput; }
    HippotizerOutput& getHippotizerOutput() { return hippotizerOutput; }

    bool startHippotizerInput(int interfaceIndex = 0, int port = 6091)
    {
        stopHippotizerInput();
        hippotizerInput.refreshNetworkInterfaces();
        if (interfaceIndex < 0) interfaceIndex = 0;
        if (hippotizerInput.start(interfaceIndex, port))
        {
            inputStatusText = "RX ON " + hippotizerInput.getBindInfo();
            if (hippotizerInput.didFallBackToAllInterfaces())
                inputStatusText += " [FALLBACK]";
            return true;
        }
        inputStatusText = "FAILED TO BIND PORT " + juce::String(port);
        return false;
    }

    void stopHippotizerInput() { hippotizerInput.stop(); }

    //==========================================================================
    // Winamp input (per-engine, Windows-only -- the stub class on macOS makes
    // these methods harmless no-ops without scattering #ifdefs at every call
    // site).  Winamp has no IP / interface concept of its own; the input
    // attaches to whatever local Winamp / WACUP / Winamp Origins window
    // exists on the desktop the moment start() is called and keeps polling
    // it until stop().
    //==========================================================================
    WinampInput& getWinampInput() { return winampInput; }

    bool startWinampInput()
    {
        stopWinampInput();
        if (winampInput.start())
        {
            inputStatusText = "WAITING FOR WINAMP...";
            return true;
        }
        inputStatusText = "FAILED TO START WINAMP INPUT";
        return false;
    }

    void stopWinampInput() { winampInput.stop(); }

    //==========================================================================
    // TrackMap -- track-to-timecode-offset mapping
    //==========================================================================

    /// Set the TrackMap pointer (owned by AppSettings, not by the engine).
    /// Must be called before enabling track mapping. Pass nullptr to disconnect.
    void setTrackMap(TrackMap* map)
    {
        trackMapPtr = map;
    }

    /// The per-engine override layer (see TrackMapOverrides).  Owned here so
    /// it follows the engine through re-indexing; EngineSettings holds a copy
    /// for persistence.  After editing, call refreshTrackMapLookup().
    TrackMapOverrides&       getTrackMapOverrides()       { return trackMapOverrides; }
    const TrackMapOverrides& getTrackMapOverrides() const { return trackMapOverrides; }
    void setTrackMapOverrides(const TrackMapOverrides& ovr) { trackMapOverrides = ovr; }

    void setMixerMap(MixerMap* map)
    {
        mixerMapPtr = map;
        std::fill(std::begin(lastSentMixer), std::end(lastSentMixer), -1); lastMixerPktCount = 0;
    }

    void setSlqMixerMap(MixerMap* map)
    {
        slqMixerMapPtr = map;
        std::fill(std::begin(lastSentSlqMixer), std::end(lastSentSlqMixer), -1);
    }

    /// Enable or disable TrackMap offset application.
    /// Triggers fire independently of this setting.
    void setTrackMapEnabled(bool enabled)
    {
        trackMapEnabled = enabled;
        if (!enabled)
        {
            // Reset offset state only -- keep cachedTrackId for trigger use
            trackMapped = false;
            cachedOffH = cachedOffM = cachedOffS = cachedOffF = 0;
            cachedBpmMultiplier = 0;
            lastSentClockBpm = -1.0f;
            lastSentOscBpm   = -1.0f;
        }
        else if (trackMapPtr && activeInput == InputSource::ProDJLink
                 && sharedProDJLink != nullptr && sharedProDJLink->getIsRunning())
        {
            lastSeenTrackVersion = sharedProDJLink->getTrackVersion(getEffectivePlayer());

            uint32_t id = (cachedTrackId != 0) ? cachedTrackId : sharedProDJLink->getTrackID(getEffectivePlayer());
            if (id != 0)
            {
                if (cachedTrackId == 0)
                {
                    cachedLoadedPlayer = sharedProDJLink->getLoadedPlayer(getEffectivePlayer());
                    cachedLoadedSlot   = sharedProDJLink->getLoadedSlot(getEffectivePlayer());
                    cachedMediaChanges = sharedProDJLink->getMediaChangeCount(cachedLoadedPlayer, cachedLoadedSlot);
                }
                cachedTrackId = id;
                auto tinfo = sharedProDJLink->getTrackInfo(getEffectivePlayer());
                cachedTrackArtist = tinfo.artist;
                cachedTrackTitle  = tinfo.title;
                cachedTrackDurationSec = (int)sharedProDJLink->getTrackLengthSec(getEffectivePlayer());

                // Phase 2: check dbClient cache or request if missing
                if (dbClient != nullptr && dbClient->getIsRunning())
                {
                    auto meta = getTrackDbMetadata();
                    if (meta.isValid())
                    {
                        if (meta.artist.isNotEmpty()) cachedTrackArtist = meta.artist;
                        if (meta.title.isNotEmpty())  cachedTrackTitle  = meta.title;
                        if (meta.durationSeconds > 0)
                        {
                            cachedTrackDurationSec = meta.durationSeconds;
                            if (sharedProDJLink != nullptr)
                                sharedProDJLink->setTrackLengthSec(getEffectivePlayer(),
                                    (uint32_t)meta.durationSeconds);
                        }
                    }
                    else
                    {
                        requestDbMetadata(id);
                    }
                }

                lookupTrackInMap();
            }
        }
        else if (trackMapPtr && activeInput == InputSource::StageLinQ && cachedTrackId != 0)
        {
            // StageLinQ parallel of the ProDJLink branch above (AUDIT ENG-6):
            // without it, TRACK MAP off and on with a track loaded read
            // NO MAP until the next track.  The map is looked up for the
            // identity the tick already holds: the tick takes each load the
            // deck publishes whether TRACK MAP is on or off, and keeps the
            // identity, its version and its length.  None of them is read
            // from the deck here: artist and title change at once on a load
            // but the version goes up only when they have settled
            // (StageLinQInput::publishSettledTracks, up to 1 s later), so a
            // live read here would hold the new track under the old version
            // and its publication would then look like the same track.
            lookupTrackInMap();
        }
        else if (trackMapPtr && activeInput == InputSource::Winamp
                 && winampInput.getIsRunning() && winampInput.isConnected())
        {
            // Winamp parallel of the ProDJLink branch above: the user has
            // toggled TrackMap on while a track is already loaded, so we
            // need to refresh the cache from the input and run the lookup
            // immediately instead of waiting for the next track change.
            //
            // Winamp has no numeric track ID, so the key is purely
            // (artist, title, durationSec) -- which the input has already
            // captured on the last track-change event in run().
            juce::String winArtist = winampInput.getArtist();
            juce::String winTitle  = winampInput.getTitle();
            int          winDur    = winampInput.getDurationSec();

            if (winTitle.isNotEmpty())
            {
                cachedTrackArtist      = winArtist;
                cachedTrackTitle       = winTitle;
                cachedTrackDurationSec = winDur;
                cachedTrackId          = 0;
                lookupTrackInMap();
            }
        }
    }

    bool isTrackMapEnabled() const { return trackMapEnabled; }

    /// Whether the currently playing track has a mapping in the TrackMap
    bool isTrackMapped() const { return trackMapped; }

    /// Get the Track ID currently being tracked (0 if none)
    uint32_t getActiveTrackId() const { return cachedTrackId; }

    /// Get the cached TrackMap entry info for the current track (for UI display).
    /// Returns empty strings and zero offset if no track is mapped.
    struct ActiveTrackInfo
    {
        uint32_t trackId = 0;
        juce::String artist;
        juce::String title;
        juce::String offset = "00:00:00:00";
        bool mapped = false;
        // Phase 2 -- extended metadata from dbserver (empty if not yet resolved)
        juce::String album;
        juce::String genre;
        juce::String key;
        int bpmTimes100 = 0;
        uint32_t artworkId = 0;
        int durationSec = 0;
    };

    ActiveTrackInfo getActiveTrackInfo() const
    {
        ActiveTrackInfo info;
        info.trackId = cachedTrackId;
        info.artist  = cachedTrackArtist;
        info.title   = cachedTrackTitle;
        info.durationSec = cachedTrackDurationSec;
        info.mapped  = trackMapped;

        // Generator: the preset is the track.  Its name is what the operator
        // called this part of the show, so it is what the outputs that carry
        // metadata (TCNet to Resolume, #20) should show; the loaded file
        // supplies the artist (tags or the "Artist - " half of its name) and,
        // when no preset is selected, the title too.  Clock mode has no
        // track and keeps "Generator / <engine name>".
        if (activeInput == InputSource::SystemTime && !genClockMode)
        {
            const bool hasFile = generatorAudioPlayer.hasFileLoaded();
            if (genPresetName.isNotEmpty())
            {
                info.title  = genPresetName;
                info.artist = hasFile ? generatorAudioPlayer.getTrackArtist() : juce::String();
            }
            else if (hasFile)
            {
                info.artist = generatorAudioPlayer.getTrackArtist();
                info.title  = generatorAudioPlayer.getTrackTitle();
            }
            if (hasFile)
                info.durationSec = (int) std::lround(generatorAudioPlayer.getFileLengthSeconds());
        }
        if (trackMapped)
            info.offset = TrackMapEntry::formatTimecodeString(
                              cachedOffH, cachedOffM, cachedOffS, cachedOffF);

        // Phase 2: enrich with dbClient cache if available -- Pro DJ Link
        // only, by the exact (player, slot, ID) key (getTrackDbMetadata).
        // Uses the lightweight lookup to avoid copying waveform data (~3600B)
        // every frame at 60Hz.
        if (dbClient != nullptr && cachedTrackId != 0)
        {
            auto meta = getTrackDbMetadata();
            if (meta.isValid())
            {
                info.album      = meta.album;
                info.genre      = meta.genre;
                info.key        = meta.key;
                info.bpmTimes100 = meta.bpmTimes100;
                info.artworkId  = meta.artworkId;
                // Ensure artist/title are from dbClient if available
                if (info.artist.isEmpty() || info.title.startsWith("Track #"))
                {
                    if (meta.artist.isNotEmpty()) info.artist = meta.artist;
                    if (meta.title.isNotEmpty())  info.title  = meta.title;
                }
            }
        }
        return info;
    }

    /// Info about the next upcoming (unfired) cue point for UI display.
    struct NextCueInfo
    {
        bool     valid = false;         // true if a next cue exists
        juce::String name;             // cue name ("DROP", "LIGHTS ON", etc.)
        uint32_t positionMs = 0;       // absolute position in track (ms)
        int32_t  remainingMs = 0;      // ms until the cue fires (negative = overdue)
    };

    /// Returns info about the next unfired cue point relative to the current playhead.
    /// Called from UI thread (timerCallback) for countdown display.
    NextCueInfo getNextCueInfo() const
    {
        NextCueInfo info;
        if (armedCues.empty()) return info;

        uint32_t playhead = lastCueCheckMs;  // last known playhead position

        // armedCues is sorted by positionMs -- find the first unfired cue
        for (const auto& ac : armedCues)
        {
            if (!ac.fired)
            {
                info.valid       = true;
                info.name        = ac.cue.name;
                info.positionMs  = ac.cue.positionMs;
                info.remainingMs = (int32_t)ac.cue.positionMs - (int32_t)playhead;
                return info;
            }
        }
        return info;  // all cues fired
    }

    /// Force a re-lookup of the current track (e.g., after editing TrackMap)
    void refreshTrackMapLookup()
    {
        if (!trackMapPtr || cachedTrackTitle.isEmpty()) return;
        const auto* entry = lookupTrackInMap();
        // Reload cue points (user may have added/edited/deleted cues),
        // armed where the deck's cues were checked up to: cues behind it
        // stay passed (DESIGN D36), the ones ahead fire when crossed.
        reloadCuePointsForTrack(entry);
    }

    /// Re-request metadata for the current track (used when waveform data
    /// hasn't arrived yet but metadata is already cached -- triggers the
    /// waveform-only retry path in DbServerClient).
    void retryWaveformRequest()
    {
        if (cachedTrackId != 0)
            requestDbMetadata(cachedTrackId);
    }

    /// Always false: the engine does not fill the TrackMap in.  An auto-fill
    /// in tick() once marked the map dirty, saved it (AUDIT C8) and set the
    /// flag this returned, so MainComponent refreshed the TrackMap editor;
    /// the auto-fill is gone (nothing sets the flags anywhere in this
    /// repository's history, back to 1.9.12-dev), and the save and the flag
    /// went with it (AUDIT ENG-18).  The cue auto-populate that fills
    /// entries today is in ProDJLinkView and MainComponent.  Kept so
    /// MainComponent's call still compiles.  Message thread.
    bool consumeTrackMapAutoFilled() { return false; }

    //==========================================================================
    // Track change triggers (MIDI / OSC)
    //==========================================================================
    TriggerOutput& getTriggerOutput() { return triggerOutput; }

    //==========================================================================
    // Start / Stop output protocols
    //==========================================================================
    /// MTC output on device `deviceIndex` of the MIDI output list as it is
    /// now; a negative index opens nothing, as for startMtcInput (AUDIT
    /// UI-6).  Message thread.
    bool startMtcOutput(int deviceIndex)
    {
        stopMtcOutput();
        mtcOutput.refreshDeviceList();
        if (deviceIndex >= 0 && mtcOutput.start(deviceIndex))
        {
            mtcOutput.setFrameRate(getEffectiveOutputFps());
            mtcOutStatusText = "TX: " + mtcOutput.getCurrentDeviceName();
            return true;
        }
        // One MTC stream per MIDI port (DESIGN D32): a port already carrying another
        // engine's MTC refuses this one and names it.
        mtcOutStatusText = (deviceIndex < 0) ? "NO MIDI DEVICE"
                         : mtcOutput.getBlockedBy().isNotEmpty() ? "IN USE BY " + mtcOutput.getBlockedBy()
                         : "FAILED TO OPEN";
        return false;
    }

    void stopMtcOutput() { mtcOutput.stop(); mtcOutStatusText = ""; }

    bool startArtnetOutput(int interfaceIndex)
    {
        stopArtnetOutput();
        artnetOutput.refreshNetworkInterfaces();
        if (artnetOutput.start(interfaceIndex, 6454))
        {
            artnetOutput.setFrameRate(getEffectiveOutputFps());
            artnetOutStatusText = "TX: " + artnetOutput.getBroadcastIp() + ":6454";
            return true;
        }
        artnetOutStatusText = "FAILED TO BIND";
        return false;
    }

    void stopArtnetOutput() { artnetOutput.stop(); artnetOutStatusText = ""; }

    bool startLANetTCOutput(int interfaceIndex)
    {
        stopLANetTCOutput();
        laNetTCOutput.refreshNetworkInterfaces();
        if (laNetTCOutput.start(interfaceIndex, 8201))
        {
            laNetTCOutput.setFrameRate(getEffectiveOutputFps());
            laNetTCOutStatusText = "TX: " + laNetTCOutput.getBroadcastIp() + ":8201";
            return true;
        }
        laNetTCOutStatusText = "FAILED TO BIND";
        return false;
    }

    void stopLANetTCOutput() { laNetTCOutput.stop(); laNetTCOutStatusText = ""; }

    bool startLtcOutput(const juce::String& typeName, const juce::String& devName,
                        int channel, double sampleRate = 0, int bufferSize = 0)
    {
        stopLtcOutput();
        if (devName.isEmpty()) { ltcOutStatusText = "NO AUDIO DEVICE AVAILABLE"; return false; }

        // Audio Thru on the same interface is fine now (one shared device,
        // outputs summed); the only conflict is the same output CHANNEL.
        if (audioThru && audioThru->getIsRunning()
            && audioThru->getCurrentDeviceName() == devName
            && audioThru->getCurrentTypeName() == typeName
            && channelsOverlap(audioThru->getSelectedChannel(), channel))
        {
            stopThruOutput();
            thruOutStatusText = "CONFLICT: same channel as LTC OUT";
        }

        if (ltcOutput.start(typeName, devName, channel, sampleRate, bufferSize))
        {
            ltcOutput.setFrameRate(getEffectiveOutputFps());
            juce::String chName = (channel == -1) ? "Ch 1 + Ch 2" : ("Ch " + juce::String(channel + 1));
            ltcOutStatusText = "TX: " + ltcOutput.getCurrentDeviceName() + " " + chName;
            return true;
        }
        ltcOutStatusText = "FAILED TO OPEN AUDIO DEVICE";
        return false;
    }

    void stopLtcOutput() { ltcOutput.stop(); ltcOutStatusText = ""; }

    bool startHippotizerOutput(const juce::String& targetIp, int interfaceIndex = -1)
    {
        stopHippotizerOutput();
        hippotizerOutput.refreshNetworkInterfaces();
        if (hippotizerOutput.start(targetIp, interfaceIndex, 6091))
        {
            hippotizerOutput.setFrameRate(getEffectiveOutputFps());
            hippoOutStatusText = "TX: " + hippotizerOutput.getDestination();
            return true;
        }
        hippoOutStatusText = "FAILED TO BIND";
        return false;
    }

    void stopHippotizerOutput() { hippotizerOutput.stop(); hippoOutStatusText = ""; }

    bool startThruOutput(const juce::String& typeName, const juce::String& devName,
                         int channel, double sampleRate = 0, int bufferSize = 0)
    {
        stopThruOutput();
        if (!audioThru) return false;  // not primary engine
        if (!ltcInput.getIsRunning() || !ltcInput.hasPassthruChannel())
        {
            thruOutStatusText = "WAITING FOR LTC INPUT";
            return false;
        }

        ltcInput.resetPassthruCounters();
        ltcInput.syncPassthruReadPosition();

        if (devName.isEmpty()) { thruOutStatusText = "NO AUDIO DEVICE"; return false; }

        // Same interface as LTC OUT is fine (shared device); the same output
        // channel is not.
        if (outputLtcEnabled && ltcOutput.getIsRunning()
            && ltcOutput.getCurrentDeviceName() == devName
            && ltcOutput.getCurrentTypeName() == typeName
            && channelsOverlap(ltcOutput.getSelectedChannel(), channel))
        {
            thruOutStatusText = "CONFLICT: same channel as LTC OUT";
            return false;
        }

        if (audioThru->start(typeName, devName, channel, &ltcInput, sampleRate, bufferSize))
        {
            juce::String chName = (channel == -1) ? "Ch 1 + Ch 2" : ("Ch " + juce::String(channel + 1));
            thruOutStatusText = "THRU: " + audioThru->getCurrentDeviceName() + " " + chName;

            double inRate  = ltcInput.getActualSampleRate();
            double outRate = audioThru->getActualSampleRate();
            if (std::abs(inRate - outRate) > 1.0)
                thruOutStatusText += " [RATE MISMATCH: " + juce::String((int)inRate) + "/" + juce::String((int)outRate) + "]";

            return true;
        }
        thruOutStatusText = "FAILED TO OPEN";
        return false;
    }

    void stopThruOutput()
    {
        if (audioThru) audioThru->stop();
        thruOutStatusText = "";
    }

    //==========================================================================
    // tick() -- called from timerCallback each frame
    //==========================================================================
    void tick()
    {
        // Housekeeping: safely destroy MidiInput devices that were retired
        // by MtcInput::stop().  See MtcInput.h for why this is deferred.
        mtcInput.drainRetiredDevices();

        logLtcOutputGaps();

        switch (activeInput)
        {
            case InputSource::SystemTime:
                updateGenerator();
                if (genClockMode)
                {
                    sourceActive = true;
                    if (statusTextVisible)
                        inputStatusText = "SYSTEM CLOCK";
                }
                else
                {
                    sourceActive = (genState == GeneratorState::Playing);
                    // A position changed while paused or stopped is told to
                    // the paused outputs once it has rested (#24).
                    updateGeneratorParkedLocate();
                    if (statusTextVisible)
                    {
                        switch (genState)
                        {
                            case GeneratorState::Playing: inputStatusText = "PLAYING"; break;
                            case GeneratorState::Paused:  inputStatusText = "PAUSED"; break;
                            case GeneratorState::Stopped: inputStatusText = "STOPPED"; break;
                        }
                    }
                }
                break;

            case InputSource::MTC:
                if (mtcInput.getIsRunning())
                {
                    // Value and phase from one clock reading and one sync
                    // point (DESIGN D29): two separate getters took two clock
                    // readings against a sync instant that is dated a
                    // quarter frame ahead, and disagreed by a frame for the
                    // first 10 ms after every sequence.
                    {
                        double phase = 0.0;
                        currentTimecode = mtcInput.getCurrentTimecode(
                            juce::Time::getMillisecondCounterHiRes(), phase);
                        framePhaseMs = phase;
                        framePhaseValid = true;
                    }
                    bool rx = mtcInput.isReceiving();
                    if (rx)
                    {
                        // Rate code 0 is 24 and 23.976 alike: a 23.976 the
                        // user chose stays, as for LTC (AUDIT NET-4).
                        followDetectedRate(mtcInput.getDetectedFrameRate(), false);
                        if (statusTextVisible)
                            inputStatusText = "RX: " + mtcInput.getCurrentDeviceName();
                    }
                    else
                    {
                        if (statusTextVisible)
                            inputStatusText = "PAUSED - " + mtcInput.getCurrentDeviceName();
                        // A locate while the sender is stopped (a Full Frame)
                        // moves the frozen value without making the source
                        // present (AUDIT LTC-13).  Passed on once to the
                        // digital outputs, which stay paused
                        // (routeTimecodeToOutputs); the tick that ends a run
                        // is the clean stop's.  Not without a sync point:
                        // a device (re)started reads 00:00:00:00 until then.
                        if (mtcParkedValid && !outputsWereActive && mtcInput.getLastFrameArrivalMs() > 0.0
                            && !sameTimecode(currentTimecode, mtcParkedTc))
                            forwardParkedLocate = true;
                        mtcParkedTc = currentTimecode;
                        mtcParkedValid = true;
                    }
                    sourceActive = rx;
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "WAITING FOR DEVICE..."; }
                break;

            case InputSource::ArtNet:
                if (artnetInput.getIsRunning())
                {
                    // Value and arrival as one record (AUDIT LTC-8): with two
                    // getters a packet stored in between paired a new value
                    // with the previous arrival.
                    const auto frame = artnetInput.getLastFrame();
                    currentTimecode = frame.tc;
                    // ArtTimeCode goes out once per frame at the sender's frame
                    // boundary, so the packet's arrival is this frame's start.
                    setFramePhaseFromArrival(frame.arrivalMs, currentFps);
                    bool rx = artnetInput.isReceiving();
                    if (rx)
                    {
                        // Rate code 0 is 24 and 23.976 alike: a 23.976 the
                        // user chose stays, as for LTC (AUDIT NET-4).
                        followDetectedRate(artnetInput.getDetectedFrameRate(), false);
                        if (statusTextVisible)
                            inputStatusText = "RX ON " + artnetInput.getBindInfo();
                    }
                    else if (statusTextVisible)
                        inputStatusText = "PAUSED - " + artnetInput.getBindInfo();
                    sourceActive = rx;
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "NOT LISTENING"; }
                break;

            case InputSource::LANetTC:
                if (laNetTCInput.getIsRunning())
                {
                    // Value and arrival as one record (AUDIT LTC-8), as for Art-Net.
                    const auto frame = laNetTCInput.getLastFrame();
                    currentTimecode = frame.tc;
                    setFramePhaseFromArrival(frame.arrivalMs, currentFps);
                    bool rx = laNetTCInput.isReceiving();
                    if (rx)
                    {
                        // LA-Net carries 24, 25 or 30: 23.976 and 29.97 the
                        // user chose stay, as for LTC (AUDIT NET-4).
                        followDetectedRate(laNetTCInput.getDetectedFrameRate(), true);
                        if (statusTextVisible)
                            inputStatusText = "RX ON " + laNetTCInput.getBindInfo();
                    }
                    else if (statusTextVisible)
                        inputStatusText = "PAUSED - " + laNetTCInput.getBindInfo();
                    sourceActive = rx;
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "NOT LISTENING"; }
                break;

            case InputSource::LTC:
                if (ltcInput.getIsRunning())
                {
                    // The decoder delivers a frame when its sync word -- the
                    // last 16 bits -- has gone by, i.e. at the instant the NEXT
                    // frame begins on the wire.  The live value is therefore
                    // the frame after the one decoded (DESIGN D19), aged by
                    // the source's whole frames since it arrived -- a device
                    // period plus the input latency can be several frames --
                    // with the phase the remainder and the receive verdict
                    // from the same snapshot and clock reading (AUDIT LTC-10;
                    // DESIGN D29's principle, there for MTC).  A source
                    // holding a static frame is not aged.
                    const auto live = ltcInput.getLiveTimecode(juce::Time::getMillisecondCounterHiRes(), currentFps);
                    currentTimecode = live.tc;
                    if (live.phaseValid)
                    {
                        framePhaseMs = live.phaseMs;
                        framePhaseValid = true;
                    }
                    bool rx = live.receiving;
                    if (rx)
                    {
                        // The decoder reads 23.976 as 24 and 29.97 as 30.
                        followDetectedRate(ltcInput.getDetectedFrameRate(), true);
                        if (statusTextVisible)
                            inputStatusText = "RX: " + ltcInput.getCurrentDeviceName()
                                            + " Ch " + juce::String(ltcInput.getSelectedChannel() + 1)
                                            + " " + describeAudioFormat(ltcInput.getActualSampleRate(),
                                                                        ltcInput.getActualBufferSize());
                    }
                    else if (statusTextVisible)
                        inputStatusText = "PAUSED - " + ltcInput.getCurrentDeviceName()
                                        + " " + describeAudioFormat(ltcInput.getActualSampleRate(),
                                                                    ltcInput.getActualBufferSize());
                    sourceActive = rx;
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "WAITING FOR DEVICE..."; }
                break;

            case InputSource::ProDJLink:
                if (sharedProDJLink != nullptr && sharedProDJLink->getIsRunning())
                {
                    // --- XF / MASTER / ON AIR auto-follow: resolve physical player ---
                    if (isXfMode())          resolveXfPlayer();
                    else if (isMasterMode()) resolveMasterPlayer();
                    else if (isOnAirMode())  resolveOnAirPlayer();
                    const int ep = getEffectivePlayer();
                    if (ep < 1 || ep > ProDJLink::kMaxPlayers)
                    {
                        sourceActive = false;
                        if (statusTextVisible)
                        {
                            inputStatusText = juce::String(autoModeLabel())
                                + (isMasterMode() ? ": NO MASTER PLAYER"
                                   : isOnAirMode() ? ": NO PLAYER ON AIR"
                                                   : ": NO PLAYER ON SIDE");
                        }
                        break;
                    }

                    // The PLL gives the pitch (LTC bit rate), the speed the
                    // source-active test reads, and the seek verdict
                    // (PlayheadPLL).  It does NOT drive the timecode -- that
                    // comes from the CDJ's playhead, interpolated below.
                    // Position and packet time from the same packet (AUDIT
                    // PDL-8): two getters could pair one packet's position
                    // with the next one's time, which the PLL takes for "a
                    // new packet at this position".
                    double cdjSpeed = sharedProDJLink->getActualSpeed(ep);
                    const auto pdlPos = sharedProDJLink->getPositionSnapshot(ep);
                    // The beat count, read right after the snapshot: on the
                    // beat fallback it is what the position was derived from
                    // (the grid lookup and the cue dispatch below).
                    const uint32_t pdlBeatCount = sharedProDJLink->getBeatCount(ep);
                    pll.tick(pdlPos.playheadMs, pdlPos.packetTs, cdjSpeed,
                             sharedProDJLink->isPositionMoving(ep));

                    // This engine's own beat grid for its player (AUDIT ENG-4).
                    refreshBeatGridFromDb();

                    // Beat grid nudge of the PLL position (see beatGridCorrect:
                    // without effect on anything sent).
                    if (!pdlBeatGrid.empty())
                        pll.beatGridCorrect(pdlBeatGrid);

                    // Smooth timecode display using interpolation between CDJ packets.
                    uint32_t rawPlayheadMs = pdlPos.playheadMs;
                    double now = juce::Time::getMillisecondCounterHiRes();
                    bool hasAbs = sharedProDJLink->playerHasAbsolutePosition(ep);

                    // Beat grid precision for NXS2: replace the rough position
                    // (beatCount x 60000/BPM) with the exact ms from the rekordbox
                    // beat grid.  This handles variable-BPM tracks and non-zero
                    // first-beat offsets that the simple formula misses.
                    // CDJ-3000 already provides precise ms via abspos packets.
                    // What goes on the wire therefore depends on this grid,
                    // which is why every engine fetches its own (it used to
                    // be pushed only to the engine shown on screen, so two
                    // engines on one NXS2 could send different positions).
                    if (!hasAbs && !pdlBeatGrid.empty())
                    {
                        const uint32_t bc = pdlBeatCount;
                        if (bc > 0 && bc <= (uint32_t)pdlBeatGrid.size())
                            rawPlayheadMs = pdlBeatGrid[(size_t)(bc - 1)].timeMs;
                    }

                    // Detect new data from the CDJ.
                    // CDJ-3000: position changes with every abspos packet (~30Hz)
                    //   → simple position comparison works.
                    // NXS2 with beat grid: position only changes at beat boundaries
                    //   (~2Hz at 120BPM), but status packets arrive at 5Hz.
                    //   Use absPositionTs to detect all packets so the snap point
                    //   refreshes at 5Hz (prevents interpolation freeze between beats).
                    double latestTs = pdlPos.packetTs;
                    bool isNewPacket;
                    if (hasAbs)
                    {
                        isNewPacket = (rawPlayheadMs != pdlLastPlayheadMs);
                    }
                    else
                    {
                        isNewPacket = (latestTs != pdlLastAbsPosTs);
                        pdlLastAbsPosTs = latestTs;
                    }

                    // ALWAYS start from raw playhead to prevent double-offset application.
                    // The offset is applied later and must start from a clean base.
                    currentTimecode = ProDJLink::playheadToTimecode(rawPlayheadMs, getEffectiveOutputFps());
                    // The millisecond position currentTimecode was derived from,
                    // kept alongside it so the sub-frame phase published to the
                    // LTC encoder (DESIGN D5) is that of the value actually on the wire.
                    // Truncated exactly like playheadToTimecode's argument, so the
                    // two cannot disagree at a frame boundary.
                    double tcSourceMs = (double)rawPlayheadMs;

                    if (isNewPacket)
                    {
                        // Detect if the grid-corrected position actually changed
                        // (new beat or seek) vs same beat with a new timestamp.
                        // Compare against pdlLastPlayheadMs (previous grid value),
                        // NOT pdlSnapMs (which drifts forward from interpolation
                        // advancement between beats).
                        bool positionChanged = (rawPlayheadMs != pdlLastPlayheadMs);
                        pdlLastPlayheadMs = rawPlayheadMs;

                        if (positionChanged)
                        {
                            // New beat or seek -- reset the interpolation anchor.
                            // NXS2 guard: if interpolation overshot the grid position
                            // by a small amount (<50ms), hold the interpolated position
                            // for this tick rather than snapping backward. The anchor
                            // resets to grid so future interpolation aligns naturally.
                            // Defense-in-depth alongside the encoder auto-increment
                            // (MtcOutput/ArtnetOutput).
                            // Large jumps (seek, track change) pass through normally.
                            // CDJ-3000 always snaps -- abspos IS the ground truth.
                            if (!hasAbs && pdlSnapMs > (double)rawPlayheadMs
                                && (pdlSnapMs - (double)rawPlayheadMs) < 50.0)
                            {
                                currentTimecode = ProDJLink::playheadToTimecode(
                                    (uint32_t)pdlSnapMs, getEffectiveOutputFps());
                                tcSourceMs = (double)(uint32_t)pdlSnapMs;
                            }
                            pdlSnapMs = (double)rawPlayheadMs;
                            pdlSnapTime = now;
                        }
                        else if (pdlSnapSpeed > 0.01)
                        {
                            // Same grid position (NXS2 same beat, new status
                            // packet).  Advance the anchor to the current
                            // interpolated position so elapsed stays small and
                            // doesn't hit the maxAdvance cap between beats.
                            double elapsed = now - pdlSnapTime;
                            if (elapsed > 0.0)
                                pdlSnapMs += elapsed * pdlSnapSpeed;
                            pdlSnapTime = now;
                            // Update currentTimecode to the advanced position --
                            // otherwise it stays at the grid value (line above)
                            // which is behind the interpolated position, causing
                            // a backward glitch at each 5Hz status packet.
                            currentTimecode = ProDJLink::playheadToTimecode(
                                (uint32_t)pdlSnapMs, getEffectiveOutputFps());
                            tcSourceMs = (double)(uint32_t)pdlSnapMs;
                        }
                        else
                        {
                            // Same grid position with the deck stopped at the
                            // last packet (NXS2 beat fallback): move the anchor
                            // to this packet and to the position shown while
                            // stopped -- the beat-derived position: the start
                            // of the current beat with the rekordbox grid, of
                            // the next one without it -- so that the first
                            // advance after play starts from there.  Left at
                            // the last packet before the stop, the second
                            // status after play advanced it by the whole pause
                            // at the new speed: the timecode leapt ahead by the
                            // pause length, the cues in between fired at once,
                            // and the next beat snapped it back (AUDIT ENG-2).
                            // Where in the beat the deck stopped is not known
                            // here; the position is corrected at the next beat,
                            // and the cues it moves across then fire (the
                            // one-beat rule at the cue dispatch below).
                            pdlSnapMs = (double)rawPlayheadMs;
                            pdlSnapTime = now;
                        }
                        // Always refresh speed -- the DJ may have moved the
                        // pitch fader between beats, and the interpolation
                        // should use the latest velocity immediately.
                        pdlSnapSpeed = cdjSpeed;
                    }
                    else if (pdlSnapSpeed > 0.01
                            && (sharedProDJLink->isPlayerPlaying(ep)
                                || cdjSpeed > PlayheadPLL::kDeadZone))
                    {
                        // Between packets: interpolate forward using CDJ speed.
                        // Interpolate when PLAYING, or when the motor is still
                        // decelerating (pause ramp: playState=PAUSED but
                        // actualSpeed > 0).  Without this, NXS2 timecode stutters
                        // at 5Hz during the 4-5 second pause deceleration because
                        // only isNewPacket refreshes the timecode.
                        // The cap is wall time since the anchor, because the
                        // packets come at a fixed rate whatever the speed:
                        // CDJ-3000 abspos every 30 ms (kInterpolationCapMs
                        // bridges one late or lost packet), NXS2 status at
                        // 5 Hz, ~200 ms (kNxs2InterpolationCapMs).  The CDJ-3000
                        // cap was 50 ms x speed -- wall time against a figure
                        // that scales with speed -- so below about 0.66x the
                        // interpolation stopped before the next packet and the
                        // value fell back to it (AUDIT ENG-17).
                        double elapsed = now - pdlSnapTime;
                        double interpMs = pdlSnapMs + elapsed * pdlSnapSpeed;
                        double maxAdvance = hasAbs ? kInterpolationCapMs : kNxs2InterpolationCapMs;
                        if (elapsed <= maxAdvance)
                        {
                            currentTimecode = ProDJLink::playheadToTimecode((uint32_t)interpMs, getEffectiveOutputFps());
                            tcSourceMs = (double)(uint32_t)interpMs;
                        }
                    }

                    // Freeze timecode on end-of-track only.
                    // The CDJ freezes actualSpeed at the last playing value on END_TRACK,
                    // so the PLL keeps advancing while position correction fights back,
                    // causing frame flicker.  Snapshot the timecode and hold it stable.
                    // Pause is NOT frozen: actualSpeed ramps 0.88->0 in ~4-5s and the
                    // PLL follows that deceleration smoothly.
                    bool isEOT = sharedProDJLink->isEndOfTrack(ep);
                    if (!isEOT)
                    {
                        pdlTcFrozen = false;
                    }
                    else if (!pdlTcFrozen)
                    {
                        pdlFrozenTc = currentTimecode;
                        pdlTcFrozen = true;
                    }
                    if (pdlTcFrozen)
                        currentTimecode = pdlFrozenTc;

                    // Feed pitch to LTC output -- scales bit-rate so the audio
                    // timecode stream runs faster/slower matching the CDJ.
                    // MTC and ArtNet don't need pitch scaling -- they send at
                    // nominal rate and the timecode values advance naturally.
                    // When timecode is frozen (end-of-track) the pitch reads 0;
                    // the encoder takes any pitch <= 0 as nominal (the output
                    // is paused then, and HOLD ON PAUSE keeps the held value
                    // at the normal bit rate).  PlayheadPLL's pitch also
                    // reads 0 on its initialising tick and while the deck is
                    // stopped.
                    ltcOutput.setPitchMultiplier(pdlTcFrozen ? 0.0 : pll.pitch);

                    // Always auto-increment: encoder goes N->N+1->N+2 at actualSpeed.
                    // CDJ status packets (offset 152) report real motor speed including
                    // ramps, so the encoder rate naturally matches the CDJ. No direct
                    // mode needed -- auto-increment produces perfectly monotonic output
                    // during both acceleration and deceleration ramps.
                    // Resync only on seek (handled by packFrame's >1 frame check).

                    // --- Track change detection ---
                    // A track is its rekordbox ID AND where it was loaded
                    // from: the same ID from another player or slot is
                    // another track (ProDJLinkInput bumps the version for it,
                    // AUDIT PDL-7).  A new version alone is not a change:
                    // reset() zeroes the version on the 10 s timeout and the
                    // next status bumps it again for the same track and
                    // source.  The version is read first (acquire): the ID,
                    // player and slot read after it are that change's or
                    // newer.  (Tr, the track type, is not exposed.)  A
                    // rekordbox ID is unique only within one medium, so the
                    // count of media changes in that player's slot is part
                    // of the identity too: the same ID from the same player
                    // and slot after a USB or SD swap is another track
                    // (AUDIT META-4).  It is read only here, on a new
                    // version: between the unmount and the next load the
                    // deck may still play the old track (emergency loop),
                    // and asking then would fetch the new medium's track
                    // with that ID.  A deck that loads the same ID from the
                    // new medium straight from that emergency loop, with no
                    // unload in between, bumps no version (ProDJLinkInput
                    // bumps it for a new ID, player, slot or type only), so
                    // that load is not seen; a stopped deck unloads at the
                    // swap (ID 0), and its next load is.
                    uint32_t pdlTrackVer = sharedProDJLink->getTrackVersion(ep);
                    if (pdlTrackVer != lastSeenTrackVersion)
                    {
                        lastSeenTrackVersion = pdlTrackVer;
                        uint32_t newId = sharedProDJLink->getTrackID(ep);
                        const uint8_t newDr = sharedProDJLink->getLoadedPlayer(ep);
                        const uint8_t newSr = sharedProDJLink->getLoadedSlot(ep);
                        const uint32_t newMc = sharedProDJLink->getMediaChangeCount(newDr, newSr);
                        if (newId != 0 && (newId != cachedTrackId
                                           || newDr != cachedLoadedPlayer || newSr != cachedLoadedSlot
                                           || newMc != cachedMediaChanges))
                        {
                            cachedTrackId = newId;
                            cachedLoadedPlayer = newDr;
                            cachedLoadedSlot = newSr;
                            cachedMediaChanges = newMc;
                            auto tinfo = sharedProDJLink->getTrackInfo(ep);
                            cachedTrackArtist = tinfo.artist;
                            cachedTrackTitle  = tinfo.title;
                            cachedTrackDurationSec = (int)sharedProDJLink->getTrackLengthSec(ep);

                            DBG("TimecodeEngine: track changed -- "
                                + cachedTrackArtist + " - " + cachedTrackTitle
                                + " (cdj_id=" + juce::String(newId) + ")"
                                + " player=" + juce::String(ep));

                            // Request metadata from dbserver (async) -- needed to resolve
                            // "Track #12345" into real artist/title for TrackMap lookup
                            requestDbMetadata(newId);

                            // Attempt TrackMap lookup (succeeds immediately if CDJ provides
                            // real artist/title; deferred until dbserver resolves if not)
                            const auto* entry = lookupTrackInMap();

                            // Reset session override on track change
                            bpmPlayerOverride = kBpmNoOverride;
                            lastSentClockBpm = -1.0f;
                            lastSentOscBpm   = -1.0f;
                            clearBeatGrid();
                            fireTrackTrigger(entry);
                            loadCuePointsForTrack(entry);
                        }
                    }

                    // The player holding the track's media moved to another
                    // address, or was lost and came back: ask once at the new
                    // address, as nothing else asks again for a track that
                    // did not change (AUDIT PDL-3).  A move keeps what
                    // DbServerClient cached (onPlayerMoved -> movePlayer
                    // re-keys it to the new address; an entry still missing
                    // analysis is fetched again there); a player lost and
                    // found again lost it (onPlayerLost).
                    if (cachedTrackId != 0)
                    {
                        juce::String srcIp;
                        uint8_t srcSlot = 0;
                        if (!getDbSource(srcIp, srcSlot))
                            dbRequestIp.clear();
                        else if (srcIp != dbRequestIp)
                            requestDbMetadata(cachedTrackId);
                    }

                    // Phase 2: poll dbClient cache for async metadata results.
                    // When "Track #12345" resolves to real artist/title, update cache
                    // and re-run TrackMap lookup (the first attempt on track change would
                    // have failed because we didn't have real metadata yet).
                    if (dbClient != nullptr && cachedTrackId != 0
                        && cachedTrackTitle.startsWith("Track #"))
                    {
                        auto meta = getTrackDbMetadata();
                        if (meta.isValid() && meta.title.isNotEmpty())
                        {
                            if (meta.artist.isNotEmpty()) cachedTrackArtist = meta.artist;
                            cachedTrackTitle  = meta.title;
                            if (meta.durationSeconds > 0)
                            {
                                cachedTrackDurationSec = meta.durationSeconds;
                                if (sharedProDJLink != nullptr)
                                    sharedProDJLink->setTrackLengthSec(ep,
                                        (uint32_t)meta.durationSeconds);
                            }

                            // NOW we have real artist+title -- do the TrackMap lookup
                            const auto* entry = lookupTrackInMap();
                            fireTrackTrigger(entry);
                            reloadCuePointsForTrack(entry);   // same track: armed where the deck is (DESIGN D36)
                        }
                    }

                    // Deferred duration pickup: NXS2 doesn't report duration in
                    // protocol packets.  If we missed it at track-change time,
                    // check ProDJLinkInput (CDJ-3000 abspos) or dbClient cache.
                    if (cachedTrackDurationSec == 0 && trackMapPtr != nullptr)
                    {
                        int nowDur = (int)sharedProDJLink->getTrackLengthSec(ep);
                        if (nowDur == 0 && dbClient != nullptr && cachedTrackId != 0)
                        {
                            auto meta = getTrackDbMetadata();
                            if (meta.isValid() && meta.durationSeconds > 0)
                                nowDur = meta.durationSeconds;
                        }
                        if (nowDur > 0)
                        {
                            cachedTrackDurationSec = nowDur;
                            const auto* entry = lookupTrackInMap();
                            reloadCuePointsForTrack(entry);   // same track: armed where the deck is (DESIGN D36)
                        }
                    }

                    // Track-relative position the cue points are compared
                    // against: the interpolated one, not the raw packet value
                    // (a cue used to fire up to a packet interval late, a whole
                    // beat on the NXS2 beat fallback).
                    const uint32_t cuePlayheadMs = (uint32_t) tcSourceMs;

                    // --- Apply timecode offset ---
                    if (trackMapEnabled && trackMapped)
                    {
                        currentTimecode = applyTimecodeOffset(
                            currentTimecode, currentFps,
                            cachedOffH, cachedOffM, cachedOffS, cachedOffF,
                            currentFps);
                        tcSourceMs += timecodeToMs(Timecode { cachedOffH, cachedOffM, cachedOffS, cachedOffF },
                                                   currentFps);
                    }

                    // Publish the sub-frame phase of the value on the wire (DESIGN D5).
                    // Not while frozen at end-of-track: the value is a snapshot
                    // and the encoder is paused anyway.
                    if (!pdlTcFrozen)
                        setFramePhaseFromPosition(tcSourceMs, currentFps);

                    // --- Fire cue point triggers ---
                    // Only during actual playback: scrub, jog and cue preview
                    // move the playhead but fire nothing (DJs preview
                    // constantly), and what they moved past does not fire at
                    // the next play either (DESIGN D36).
                    // On the beat fallback (no 0x0b) a step of exactly one
                    // beat in the beat count is the next beat, not a seek,
                    // for the cue dispatch.  After a pause the playhead
                    // resumes from the beat-derived position, which does not
                    // move within a beat, so the next beat moves it forward
                    // by as far as the deck had played into its beat before
                    // the pause: more than 500 ms late in a beat below
                    // 120 BPM, which PlayheadPLL reports as a seek, and the
                    // cues between the pause point and that beat -- which
                    // the deck plays across -- were passed without firing
                    // (AUDIT ENG-2).  They fire at that beat, up to a beat
                    // late, as DESIGN D17 allows on this fallback.  Any
                    // forward relocation that moves the beat count by
                    // exactly one is the same step -- a beat jump of one
                    // beat, or a hot cue, memory cue or needle search into
                    // the next beat, up to almost two beats ahead: while
                    // the deck plays, the cues jumped over fire at the
                    // jump, as they always did at 120 BPM and above, where
                    // such a step stays within the 500 ms seek test.  While
                    // it is paused nothing fires and the step raises no
                    // seek verdict, so the cues it passed are passed at
                    // play (DESIGN D36) and a paused hot cue of one beat
                    // count forward does not re-arm.  A step back in the beat
                    // count is still a seek.  ProDJLinkInput counts its own
                    // up at every beat packet and takes the player's status
                    // count, forward or back, except a count 1-4 beats lower
                    // that may predate the latest beat packet (handled within
                    // ProDJLink::kStatusAfterBeatMs, 50 ms, of it and not
                    // below the count before it; AUDIT ENG-2).  So a jump
                    // back, a loop or a paused jog reaches here as a step
                    // back at the player's first status after it: when the
                    // player sends a beat packet at the landing, likely
                    // within about 70 ms (on the CDJ-2000nexus captures its
                    // first status after a beat packet came 0-70 ms after it,
                    // also after a hot-cue landing); otherwise at its next
                    // regular status, up to about 200 ms.  Until then the
                    // beat-derived position runs on past the point the deck
                    // left (a loop's out point), from one beat on after a
                    // landing beat packet, and a cue in that stretch fires
                    // early, at every loop pass, and again when the deck
                    // reaches it.  It lasts until the first status 50 ms or
                    // more after the packet (up to about 0.25 s on those
                    // captures) when the lower count equals the one
                    // ProDJLinkInput held before the latest beat packet --
                    // a one-beat loop or one-beat jump back landing on the
                    // beat, a step back just after a beat, or the deck
                    // crossing a beat before the player's first status after
                    // the step: that status is refused as possibly stale.
                    // The outputs' resync keeps PlayheadPLL's verdict.
                    const bool cueSeek = pll.seekDetected
                        && ! (! hasAbs && pdlBeatCount == pdlPrevBeatCount + 1);
                    pdlPrevBeatCount = pdlBeatCount;
                    dispatchTrackCues(cuePlayheadMs, rawPlayheadMs, sharedProDJLink->isPlayerPlaying(ep), cueSeek);

                    bool pdlRx = sharedProDJLink->isReceiving();
                    if (statusTextVisible)
                    {
                        if (pdlRx)
                        {
                            // Note: no fps auto-detection for ProDJLink -- CDJ sends ms,
                            // not frames. The user's fps selection IS the frame rate.

                            bool pdlHasTC = sharedProDJLink->hasTimecodeData(ep);
                            if (pdlHasTC)
                            {
                                juce::String pdlModel = sharedProDJLink->getPlayerModel(ep);
                                if (isAutoMode())     // "MASTER P2", "XF-A P1", "ON AIR P3"
                                    inputStatusText = juce::String(autoModeLabel())
                                                      + " P" + juce::String(ep);
                                else
                                    inputStatusText = "RX P" + juce::String(ep);
                                if (pdlModel.isNotEmpty())
                                    inputStatusText += " " + pdlModel;

                                // The play state while the deck is not moving,
                                // and EMERGENCY always: an emergency loop counts
                                // as moving since AUDIT PDL-10, and the media
                                // pulled from the followed deck must still show.
                                if (!sharedProDJLink->isPositionMoving(ep) || sharedProDJLink->isEmergencyLoop(ep))
                                    inputStatusText += " " + sharedProDJLink->getPlayStateString(ep);

                                double pdlBpm = sharedProDJLink->getBPM(ep);
                                if (pdlBpm > 0.0)
                                    inputStatusText += " | " + juce::String(pdlBpm, 1) + " BPM";
                            }
                            else
                            {
                                inputStatusText = "P" + juce::String(ep)
                                    + " " + sharedProDJLink->getPlayStateString(ep)
                                    + " - NO POSITION DATA";
                            }

                            if (pdlHasTC && trackMapEnabled
                                && cachedTrackTitle.isNotEmpty())
                            {
                                if (trackMapped)
                                    inputStatusText += " | MAP: " + cachedTrackTitle;
                                else
                                    inputStatusText += " | NO MAP";
                            }

                            inputStatusText += " | " + sharedProDJLink->getBindInfo();
                        }
                        else
                        {
                            inputStatusText = "WAITING";
                            auto discP = sharedProDJLink->getDiscoveredPlayers();
                            if (discP.isEmpty())
                                inputStatusText += " | NO PLAYERS";
                            else
                                inputStatusText += " | " + juce::String(discP.size()) + " PLAYER(S)";
                            inputStatusText += " | " + sharedProDJLink->getBindInfo();
                        }
                    }

                    // --- MIDI Clock ---
                    if (pdlRx && midiClockEnabled && triggerOutput.isMidiClockRunning())
                    {
                        double pdlClkBpm = sharedProDJLink->getMasterBPM();
                        if (pdlClkBpm <= 0.0) pdlClkBpm = sharedProDJLink->getBPM(ep);
                        pdlClkBpm = applyBpmMultiplier(pdlClkBpm, getEffectiveBpmMultiplier());
                        if (pdlClkBpm > 0.0 && std::abs((float)pdlClkBpm - lastSentClockBpm) > 0.05f)
                        {
                            triggerOutput.updateMidiClockBpm(pdlClkBpm);
                            lastSentClockBpm = (float)pdlClkBpm;
                        }
                    }

                    // --- Ableton Link ---
                    if (pdlRx && linkBridge.isEnabled())
                    {
                        double pdlLnkBpm = sharedProDJLink->getMasterBPM();
                        if (pdlLnkBpm <= 0.0) pdlLnkBpm = sharedProDJLink->getBPM(ep);
                        pdlLnkBpm = applyBpmMultiplier(pdlLnkBpm, getEffectiveBpmMultiplier());
                        if (pdlLnkBpm > 0.0)
                            linkBridge.setTempo(pdlLnkBpm);
                    }

                    // --- OSC BPM Forward ---
                    if (pdlRx && oscForwardEnabled && triggerOutput.isOscConnected())
                    {
                        double pdlOscBpm = sharedProDJLink->getMasterBPM();
                        if (pdlOscBpm <= 0.0) pdlOscBpm = sharedProDJLink->getBPM(ep);
                        pdlOscBpm = applyBpmMultiplier(pdlOscBpm, getEffectiveBpmMultiplier());
                        sendBpmOsc(pdlOscBpm);
                    }

                    // --- Mixer Fader Forward (OSC + MIDI CC) ---
                    // Requires DJM type-0x39 packets (Pioneer bridge on network).
                    // OSC: normalised float 0.0-1.0 on /mixer/ch1..4, /mixer/crossfader, /mixer/master
                    // MIDI CC: ch1=CC1, ch2=CC2, ch3=CC3, ch4=CC4, crossfader=CC5, master=CC7
                    if (sharedProDJLink->hasMixerFaderData()
                        && mixerMapPtr != nullptr
                        && (oscMixerForwardEnabled || midiMixerForwardEnabled || artnetMixerForwardEnabled))
                    {
                        forwardMixerParams();
                    }

                    // sourceActive: determined directly from CDJ playState + actualSpeed.
                    //
                    //   PLAYING/LOOPING/CUE_PLAY: active while actualSpeed >= minimum
                    //     (includes acceleration ramp -- output starts as speed ramps up)
                    //   PAUSED: actualSpeed ramps target->0 in ~4-5s. Output naturally
                    //     stops when speed drops below kMinEncodingPitch. No special case.
                    //   END_TRACK: CDJ freezes actualSpeed (never ramps to 0).
                    //     playState == END_TRACK tells us directly -> force inactive.
                    //   NO_TRACK/LOADING/SEEKING: no useful timecode -> inactive.
                    //
                    // Model-specific wrinkle (NXS2 and older, CDJ mode):
                    //   These players have NO deceleration ramp in CDJ mode --
                    //   pressing pause clears the PLAYING flag (F byte bit 0x40)
                    //   instantly, while actualSpeed remains frozen at its last
                    //   value (e.g. 1.0025x, the pitch-fader setting).  The
                    //   speed-only gate would keep sourceActive=true forever and
                    //   LTC would continue streaming while the disc is paused.
                    //
                    //   CDJ-3000 uses a ~4-5s deceleration ramp even in CDJ mode,
                    //   so its actualSpeed decays to zero naturally and the speed
                    //   gate closes on its own.  Applying the flag gate there
                    //   would cut LTC at the start of the ramp -- we must not.
                    //
                    //   Vinyl-mode pause on NXS2 briefly drops actualSpeed to 0
                    //   for ~200-400ms before the flag clears, so the speed gate
                    //   closes first -- the additional flag gate is harmless.
                    //
                    //   Decision: for non-3000 players, require BOTH speed above
                    //   threshold AND the F-bit PLAYING flag set.  Beat-link
                    //   treats this F bit as the authoritative playing signal
                    //   in CdjStatus.isPlaying().
                    bool pdlHasData = sharedProDJLink->hasTimecodeData(ep);
                    double speed = (pll.actualSpeed > pll.kDeadZone)
                                 ? pll.actualSpeed
                                 : std::abs(pll.smoothVelocity);

                    // Model-aware playing check.  CDJ-3000 ramp decays speed on
                    // pause, so speed alone is enough.  Everything else needs
                    // the F-flag to discriminate pause-with-frozen-speed from
                    // real playback.
                    bool motorGateOpen = true;
                    const juce::String model = sharedProDJLink->getPlayerModel(ep);
                    if (!model.contains("3000"))
                        motorGateOpen = sharedProDJLink->isPlayingFlagSet(ep);

                    sourceActive = pdlRx && pdlHasData
                                && (speed >= PlayheadPLL::kMinEncodingPitch)
                                && motorGateOpen
                                && !isEOT
                                && isOnAirGateOpen();

                    // (The LTC reseed on pause -> active now happens for every
                    // source in routeTimecodeToOutputs.)
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "NOT CONNECTED"; }
                break;

            case InputSource::StageLinQ:
                if (sharedStageLinQ != nullptr && sharedStageLinQ->getIsRunning())
                {
                    // XF-A/XF-B auto-follow (same logic as ProDJLink), ON AIR (DESIGN D34)
                    if (isXfMode())
                        resolveXfPlayerStageLinQ();
                    else if (isOnAirMode())
                        resolveOnAirPlayer();
                    const int ep = getEffectivePlayer();
                    if (ep < 1 || ep > StageLinQ::kMaxDecks)
                    {
                        sourceActive = false;
                        if (statusTextVisible)
                        {
                            if (isXfMode())
                                // A PRIME 4+ never sends the crossfader
                                // assignment (#23), so XF cannot know sides.
                                inputStatusText = juce::String(autoModeLabel())
                                    + ((sharedStageLinQ->hasMixerData() && !sharedStageLinQ->hasChannelAssignment())
                                           ? ": DEVICE SENDS NO SIDES - USE ON AIR"
                                           : ": NO DECK ON SIDE");
                            else if (isOnAirMode())
                                inputStatusText = juce::String(autoModeLabel()) + ": NO DECK ON AIR";
                            else
                                inputStatusText = "INVALID DECK";
                        }
                        break;
                    }

                    // The playhead and the time its BeatInfo message was read.
                    // StageLinQInput stores the position, then the time
                    // (release); reading the time, the position and the time
                    // again pairs them unless this falls between the two
                    // stores of one message -- a window of a few instructions
                    // every ~35 ms, where the position is a message newer than
                    // the time for one snap (it has no sequence lock).
                    double slqSpeed = sharedStageLinQ->getActualSpeed(ep);
                    double rawTs = sharedStageLinQ->getAbsPositionTs(ep);
                    uint32_t rawPlayheadMs = sharedStageLinQ->getPlayheadMs(ep);
                    for (int retry = 0; retry < 4; ++retry)
                    {
                        const double ts2 = sharedStageLinQ->getAbsPositionTs(ep);
                        if (ts2 == rawTs) break;
                        rawTs = ts2;
                        rawPlayheadMs = sharedStageLinQ->getPlayheadMs(ep);
                    }

                    // Drive PLL from StageLinQ deck data
                    pll.tick(rawPlayheadMs, rawTs, slqSpeed, sharedStageLinQ->isPositionMoving(ep));

                    // Smooth timecode display using interpolation between BeatInfo messages
                    double now = juce::Time::getMillisecondCounterHiRes();

                    bool isNewPacket = (rawPlayheadMs != pdlLastPlayheadMs);

                    // ALWAYS start from raw playhead to prevent double-offset application.
                    currentTimecode = StageLinQ::playheadToTimecode(rawPlayheadMs, getEffectiveOutputFps());
                    // Millisecond position behind currentTimecode, for the phase
                    // publication below (see the Pro DJ Link branch).
                    double tcSourceMs = (double)rawPlayheadMs;

                    // The position is interpolated from the moment its message
                    // was read, not from the tick that first saw it -- up to a
                    // tick later, a lag that changed from message to message --
                    // and for up to kInterpolationCapMs of wall time: BeatInfo
                    // comes about every 35 ms whatever the deck's speed.  The cap
                    // was 50 ms x speed, wall time against a number that scales
                    // with speed: 40 ms at a deck synced to 0.8x, so on the #23
                    // capture interpolation stopped before the next message and
                    // the value fell back a frame now and then (AUDIT SLQ-4,
                    // ENG-17).
                    if (isNewPacket)
                    {
                        pdlLastPlayheadMs = rawPlayheadMs;
                        pdlSnapMs = (double)rawPlayheadMs;
                        pdlSnapTime = (rawTs > 0.0) ? rawTs : now;
                        pdlSnapSpeed = slqSpeed;
                    }
                    if (pdlSnapSpeed > 0.01 && sharedStageLinQ->isPlayerPlaying(ep))
                    {
                        const double elapsed = now - pdlSnapTime;
                        if (elapsed > 0.0 && elapsed <= kInterpolationCapMs)
                        {
                            const double interpMs = pdlSnapMs + elapsed * pdlSnapSpeed;
                            currentTimecode = StageLinQ::playheadToTimecode((uint32_t)interpMs, getEffectiveOutputFps());
                            tcSourceMs = (double)(uint32_t)interpMs;
                        }
                    }

                    // Feed pitch to LTC output.
                    // Use pll.pitch directly -- same as ProDJLink.  The speed is
                    // measured from BeatInfo (StageLinQInput::getActualSpeed): it
                    // follows the deck through play, pause and SYNC, and the PLL
                    // and LTC follow it.  The previous code gated on isPlaying
                    // which cut LTC to zero the instant Play=false arrived -- before
                    // the speed had come down -- causing an audible click
                    // in the LTC audio stream.
                    // No end-of-track freeze needed: Denon does not have the CDJ
                    // frozen-actualSpeed quirk.  sourceActive below gates on
                    // speed >= kMinEncodingPitch, which handles the stopped state.
                    ltcOutput.setPitchMultiplier(pll.pitch);

                    // --- Track change detection ---
                    // StageLinQInput raises the version once per load, when the
                    // identity has settled, and not for the track it last
                    // published (AUDIT ENG-7).  The identity is read
                    // live here, so a track loaded between one publication and
                    // the tick that sees it is taken under that version; its
                    // own publication then finds the identity this engine
                    // already holds (artist, title, and the length when both
                    // are known), and, as Pro DJ Link's branch does for its
                    // ID, only takes the new version: the trigger does not
                    // fire again and the cues are not reloaded.
                    uint32_t slqTrackVer = sharedStageLinQ->getTrackVersion(ep);
                    if (slqTrackVer != lastSeenTrackVersion)
                    {
                        lastSeenTrackVersion = slqTrackVer;
                        auto tinfo = sharedStageLinQ->getTrackInfo(ep);
                        const int newLenSec = (int) sharedStageLinQ->getTrackLengthSec(ep);
                        const bool sameTrack = cachedTrackId != 0
                            && tinfo.artist == cachedTrackArtist && tinfo.title == cachedTrackTitle
                            && (newLenSec == cachedTrackDurationSec || newLenSec == 0 || cachedTrackDurationSec == 0);
                        if (sameTrack)
                        {
                            cachedTrackId = slqTrackVer;
                        }
                        else if (tinfo.artist.isNotEmpty() || tinfo.title.isNotEmpty())
                        {
                            cachedTrackArtist = tinfo.artist;
                            cachedTrackTitle  = tinfo.title;
                            cachedTrackId = slqTrackVer;  // StageLinQ has no numeric ID; use version
                            cachedTrackDurationSec = newLenSec;

                            DBG("TimecodeEngine: StageLinQ track changed -- "
                                + cachedTrackArtist + " - " + cachedTrackTitle
                                + " deck=" + juce::String(ep));

                            const auto* entry = lookupTrackInMap();
                            bpmPlayerOverride = kBpmNoOverride;
                            lastSentClockBpm = -1.0f;
                            lastSentOscBpm   = -1.0f;
                            fireTrackTrigger(entry);
                            loadCuePointsForTrack(entry);
                        }
                    }

                    // Deferred duration pickup: TrackLength may arrive after
                    // SongName/SongLoaded in the StateMap stream.  If we missed
                    // it at track-change time, pick it up now and re-lookup.
                    if (cachedTrackDurationSec == 0 && trackMapPtr != nullptr)
                    {
                        int nowDur = (int)sharedStageLinQ->getTrackLengthSec(ep);
                        if (nowDur > 0)
                        {
                            cachedTrackDurationSec = nowDur;
                            const auto* entry = lookupTrackInMap();
                            reloadCuePointsForTrack(entry);   // same track: armed where the deck is (DESIGN D36)
                        }
                    }

                    const uint32_t cuePlayheadMs = (uint32_t) tcSourceMs;   // see the Pro DJ Link branch

                    // Apply timecode offset from TrackMap
                    if (trackMapEnabled && trackMapped)
                    {
                        currentTimecode = applyTimecodeOffset(
                            currentTimecode, currentFps,
                            cachedOffH, cachedOffM, cachedOffS, cachedOffF,
                            currentFps);
                        tcSourceMs += timecodeToMs(Timecode { cachedOffH, cachedOffM, cachedOffS, cachedOffF },
                                                   currentFps);
                    }

                    // Publish the sub-frame phase of the value on the wire (DESIGN D5).
                    setFramePhaseFromPosition(tcSourceMs, currentFps);

                    // --- Fire cue point triggers ---
                    // Same rule as ProDJLink: only during playback (DESIGN D36).
                    dispatchTrackCues(cuePlayheadMs, rawPlayheadMs, sharedStageLinQ->isPlayerPlaying(ep), pll.seekDetected);

                    bool slqRx = sharedStageLinQ->isReceiving();
                    if (statusTextVisible)
                    {
                        if (slqRx)
                        {
                            bool slqHasTC = sharedStageLinQ->hasTimecodeData(ep);
                            if (slqHasTC)
                            {
                                juce::String slqModel = sharedStageLinQ->getPlayerModel(ep);
                                inputStatusText = isAutoMode()     // "XF-A D1", "ON AIR D2"
                                    ? (juce::String(autoModeLabel()) + " D" + juce::String(ep))
                                    : ("RX D" + juce::String(ep));
                                if (slqModel.isNotEmpty())
                                    inputStatusText += " " + slqModel;

                                if (!sharedStageLinQ->isPositionMoving(ep))
                                    inputStatusText += " " + sharedStageLinQ->getPlayStateString(ep);

                                double slqBpm = sharedStageLinQ->getBPM(ep);
                                if (slqBpm > 0.0)
                                    inputStatusText += " | " + juce::String(slqBpm, 1) + " BPM";
                            }
                            else
                            {
                                inputStatusText = "D" + juce::String(ep)
                                    + " " + sharedStageLinQ->getPlayStateString(ep)
                                    + " - NO POSITION DATA";
                            }

                            if (slqHasTC && trackMapEnabled
                                && cachedTrackTitle.isNotEmpty())
                            {
                                if (trackMapped)
                                    inputStatusText += " | MAP: " + cachedTrackTitle;
                                else
                                    inputStatusText += " | NO MAP";
                            }

                            inputStatusText += " | " + sharedStageLinQ->getBindInfo();
                        }
                        else
                        {
                            inputStatusText = "WAITING | " + sharedStageLinQ->getBindInfo();
                        }
                    }

                    // --- MIDI Clock ---
                    if (slqRx && midiClockEnabled && triggerOutput.isMidiClockRunning())
                    {
                        double slqClkBpm = sharedStageLinQ->getMasterBPM();
                        if (slqClkBpm <= 0.0) slqClkBpm = sharedStageLinQ->getBPM(ep);
                        slqClkBpm = applyBpmMultiplier(slqClkBpm, getEffectiveBpmMultiplier());
                        if (slqClkBpm > 0.0 && std::abs((float)slqClkBpm - lastSentClockBpm) > 0.05f)
                        {
                            triggerOutput.updateMidiClockBpm(slqClkBpm);
                            lastSentClockBpm = (float)slqClkBpm;
                        }
                    }

                    // --- Ableton Link ---
                    if (slqRx && linkBridge.isEnabled())
                    {
                        double slqLnkBpm = sharedStageLinQ->getMasterBPM();
                        if (slqLnkBpm <= 0.0) slqLnkBpm = sharedStageLinQ->getBPM(ep);
                        slqLnkBpm = applyBpmMultiplier(slqLnkBpm, getEffectiveBpmMultiplier());
                        if (slqLnkBpm > 0.0)
                            linkBridge.setTempo(slqLnkBpm);
                    }

                    // --- OSC BPM Forward ---
                    if (slqRx && oscForwardEnabled && triggerOutput.isOscConnected())
                    {
                        double slqOscBpm = sharedStageLinQ->getMasterBPM();
                        if (slqOscBpm <= 0.0) slqOscBpm = sharedStageLinQ->getBPM(ep);
                        slqOscBpm = applyBpmMultiplier(slqOscBpm, getEffectiveBpmMultiplier());
                        sendBpmOsc(slqOscBpm);
                    }

                    // --- Mixer fader forward (OSC/MIDI/ArtNet) ---
                    if (slqRx && (oscMixerForwardEnabled || midiMixerForwardEnabled || artnetMixerForwardEnabled))
                    {
                        forwardStageLinQMixer();
                    }

                    // sourceActive from direct play state
                    bool slqHasData = sharedStageLinQ->hasTimecodeData(ep);
                    double speed = (pll.actualSpeed > pll.kDeadZone)
                                 ? pll.actualSpeed
                                 : std::abs(pll.smoothVelocity);

                    sourceActive = slqRx && slqHasData
                                && (speed >= PlayheadPLL::kMinEncodingPitch);
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "NOT CONNECTED"; }
                break;

            case InputSource::Hippotizer:
                if (hippotizerInput.getIsRunning())
                {
                    bool rx = hippotizerInput.isReceiving();
                    if (rx)
                    {
                        uint32_t ms = hippotizerInput.getMsSinceMidnight();
                        currentTimecode = wallClockToTimecode((double)ms, currentFps);
                        setFramePhaseFromPosition((double)ms, currentFps);
                    }

                    if (statusTextVisible)
                    {
                        // Build discovery suffix: "GOHIPPO (4.8.4.23374) @ 192.168.0.2"
                        juce::String discInfo;
                        if (hippotizerInput.isDiscovered())
                        {
                            discInfo = hippotizerInput.getDiscoveredName();
                            auto fw = hippotizerInput.getDiscoveredFirmware();
                            if (fw.isNotEmpty())
                                discInfo += " (" + fw + ")";
                            discInfo += " @ " + hippotizerInput.getDiscoveredIp();
                        }

                        if (rx)
                        {
                            inputStatusText = "RX ON " + hippotizerInput.getBindInfo();
                            if (discInfo.isNotEmpty())
                                inputStatusText += " | " + discInfo;
                        }
                        else if (discInfo.isNotEmpty())
                        {
                            inputStatusText = "WAITING | " + discInfo;
                        }
                        else
                        {
                            inputStatusText = "PAUSED - " + hippotizerInput.getBindInfo();
                        }
                    }
                    sourceActive = rx;
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "NOT LISTENING"; }
                break;

            case InputSource::Winamp:
                if (winampInput.getIsRunning())
                {
                    const bool connected = winampInput.isConnected();
                    const auto winState = winampInput.getState();
                    const bool playing  = (winState == WinampInput::State::Playing);

                    if (connected)
                    {
                        // Detect track change by comparing artist + title (the
                        // identity of the track) to the engine's cached
                        // values.  Duration is treated as METADATA about the
                        // track, not part of its identity, because Winamp /
                        // WACUP / AIMP all decode the duration asynchronously
                        // -- IPC_GETOUTPUTTIME with wparam=1 returns -1 (or 0
                        // depending on the file type) for up to ~1 s after a
                        // new track loads, until the audio decoder has
                        // scanned the file enough to know its length.  If we
                        // counted that late duration arrival as a track
                        // change we would run the trigger + cue pipeline a
                        // SECOND time about a second into the track:
                        //   - MIDI / OSC / Art-Net DMX triggers would fire
                        //     twice for one track load,
                        //   - armedCues would be wiped and rebuilt, so any
                        //     cue we had already fired in the first second
                        //     would re-fire,
                        //   - the second lookupTrackInMap could match a
                        //     duration-keyed entry with a different offset
                        //     than the duration=0 fallback match found a
                        //     second earlier, making the output timecode
                        //     jump in front of the receiver.
                        // Instead, only the artist/title diff fires the
                        // pipeline; the duration is folded into the cache
                        // silently and the lookup re-runs so any TrackMap
                        // entry that was keyed on the real duration can
                        // start matching, without disturbing the triggers
                        // or cues that already ran.
                        juce::String winArtist = winampInput.getArtist();
                        juce::String winTitle  = winampInput.getTitle();
                        int          winDur    = winampInput.getDurationSec();

                        const bool trackChanged = (winTitle.isNotEmpty()
                            && (winArtist != cachedTrackArtist
                             || winTitle  != cachedTrackTitle));

                        const bool durationUpdated = (!trackChanged
                            && winTitle.isNotEmpty()
                            && winDur > 0
                            && winDur != cachedTrackDurationSec);

                        if (trackChanged)
                        {
                            cachedTrackArtist      = winArtist;
                            cachedTrackTitle       = winTitle;
                            cachedTrackDurationSec = winDur;
                            cachedTrackId          = 0;  // Winamp has no numeric track ID

                            const auto* entry = lookupTrackInMap();
                            bpmPlayerOverride = kBpmNoOverride;
                            lastSentClockBpm  = -1.0f;
                            lastSentOscBpm    = -1.0f;
                            fireTrackTrigger(entry);
                            loadCuePointsForTrack(entry);

                            DBG("TimecodeEngine: Winamp track changed -- "
                                + cachedTrackArtist + " - " + cachedTrackTitle
                                + " (" + juce::String(cachedTrackDurationSec) + "s)");
                        }
                        else if (durationUpdated)
                        {
                            cachedTrackDurationSec = winDur;
                            // Re-run the lookup quietly so a duration-keyed
                            // TrackMap entry can start matching.  Do NOT
                            // call fireTrackTrigger() or
                            // loadCuePointsForTrack() here -- those happen
                            // exactly once per real track change above.
                            lookupTrackInMap();
                            DBG("TimecodeEngine: Winamp duration arrived late -- "
                                + cachedTrackTitle + " = "
                                + juce::String(winDur) + "s");
                        }

                        // Position -> Timecode.  Winamp returns ms with single-ms
                        // resolution, polled at 20 Hz; for frame-accurate output
                        // between polls the upstream MTC/LTC/Art-Net senders run
                        // at their own configured frame rate against the same
                        // currentTimecode value, which moves forward by ~50 ms
                        // every poll.  Audible drift is bounded by the poll
                        // cadence (one frame at most).
                        const int32_t posMs = winampInput.getPositionMs();
                        currentTimecode = wallClockToTimecode((double)posMs, currentFps);
                        setFramePhaseFromPosition((double)posMs, currentFps);

                        // Apply TrackMap offset
                        if (trackMapEnabled && trackMapped)
                        {
                            currentTimecode = applyTimecodeOffset(
                                currentTimecode, currentFps,
                                cachedOffH, cachedOffM, cachedOffS, cachedOffF,
                                currentFps);
                        }

                        // Fire cue points only during playback; what a seek
                        // while paused or stopped moved past does not fire at
                        // the next play (DESIGN D36).  No PLL here: Winamp's
                        // position is continuous (50 ms polls, interpolated),
                        // so a step of over 500 ms either way is taken as a
                        // seek: a real one, or the end of an IPC stall.
                        // WinampInput's position runs on at most 1 s past its
                        // last answer and then holds, so when the answers
                        // resume it jumps to where the player is: forward by
                        // over 500 ms after a stall of over about 1.5 s with
                        // the audio playing on, back by up to 1 s when the
                        // audio froze too (getPositionMs, AUDIT UI-13).
                        const uint32_t playheadMs = (uint32_t) juce::jmax(0, (int)posMs);
                        const bool winSeeked = playheadMs > lastCueCheckMs + 500
                                            || playheadMs + 500 < lastCueCheckMs;
                        dispatchTrackCues(playheadMs, playheadMs, playing, winSeeked);
                    }

                    sourceActive = playing;

                    if (statusTextVisible)
                    {
                        if (!connected)
                            inputStatusText = "WAITING FOR WINAMP...";
                        else if (playing)
                            inputStatusText = "PLAYING";
                        else if (winState == WinampInput::State::Paused)
                            inputStatusText = "PAUSED";
                        else
                            inputStatusText = "STOPPED";
                    }
                }
                else { sourceActive = false; if (statusTextVisible) inputStatusText = "NOT LISTENING"; }
                break;
        }

        // --- Audio BPM forwarding (non-DJ sources only) ---
        // ProDJLink and StageLinQ have their own precise BPM from the CDJs/Denon;
        // audio detection serves every other source (generator, MTC, LTC,
        // Art-Net, LA-Net, HippoNet, Winamp).
        if (audioBpmEnabled && audioBpmInput.getIsRunning()
            && activeInput != InputSource::ProDJLink
            && activeInput != InputSource::StageLinQ)
        {
            double abpm = audioBpmInput.getBpm();
            bool hasBpm = audioBpmInput.hasBpm();

            if (hasBpm)
            {
                double bpm = applyBpmMultiplier(abpm, getEffectiveBpmMultiplier());

                // MIDI Clock
                if (midiClockEnabled && triggerOutput.isMidiClockRunning() && bpm > 0.0)
                {
                    if (std::abs((float)bpm - lastSentClockBpm) > 0.05f)
                    {
                        triggerOutput.updateMidiClockBpm(bpm);
                        lastSentClockBpm = (float)bpm;
                    }
                }

                // Ableton Link
                if (linkBridge.isEnabled() && bpm > 0.0)
                    linkBridge.setTempo(bpm);

                // OSC BPM Forward
                sendBpmOsc(bpm);
            }

            // Append BPM to status text
            if (statusTextVisible && abpm > 0.0)
                inputStatusText += " | " + juce::String(abpm, 1) + " BPM";
        }

        routeTimecodeToOutputs();
        updateVuMeters();
    }

    //==========================================================================
    // Status text (read by MainComponent for UI)
    //==========================================================================
    juce::String getInputStatusText() const { return inputStatusText; }
    juce::String getMtcOutStatusText() const { return mtcOutStatusText; }
    juce::String getArtnetOutStatusText() const { return artnetOutStatusText; }
    /// "48k/512": the sample rate and buffer size the driver actually
    /// settled on, which is what the operator needs to see when a driver
    /// ignores the requested values (ASIO interfaces set theirs in their own
    /// control panel) -- the combos show the request, the status the truth.
    static juce::String describeAudioFormat(double sampleRate, int bufferSize)
    {
        if (sampleRate <= 0.0) return {};
        juce::String sr = (std::fmod(sampleRate, 1000.0) == 0.0) ? juce::String((int)(sampleRate / 1000.0)) + "k"
                                                                  : juce::String(sampleRate / 1000.0, 1) + "k";
        return bufferSize > 0 ? sr + "/" + juce::String(bufferSize) : sr;
    }

    /// LTC output status line.  When the audio device reports an output
    /// latency, the compensation being applied to the frame phase is shown
    /// alongside it -- visible for anyone measuring the signal, without
    /// being a control the operator has to understand or set.
    juce::String getLtcOutStatusText() const
    {
        if (ltcOutStatusText.isEmpty()) return ltcOutStatusText;
        juce::String text = ltcOutStatusText;
        if (ltcOutput.getIsRunning())
        {
            const auto fmt = describeAudioFormat(ltcOutput.getActualSampleRate(), ltcOutput.getActualBufferSize());
            if (fmt.isNotEmpty()) text += " " + fmt;
        }
        const double comp = getLtcLatencyCompMs();
        if (comp > 0.05)
            text += " (+" + juce::String(comp, 1) + " ms)";
        // Output holes the device left in the stream (re-aligned each time,
        // #19): an interface that keeps doing this is worth knowing about.
        const int gaps = ltcOutput.getOutputGapCount();
        if (gaps > 0)
            text += " " + juce::String(gaps) + (gaps == 1 ? " gap" : " gaps");
        return text;
    }
    juce::String getThruOutStatusText() const { return thruOutStatusText; }
    juce::String getHippoOutStatusText() const { return hippoOutStatusText; }
    juce::String getLANetTCOutStatusText() const { return laNetTCOutStatusText; }

    /// Only the currently displayed engine needs to build status text strings.
    /// Call with true for the selected engine, false for background engines.
    /// Avoids ~25 juce::String heap allocations per tick on non-visible engines.
    void setStatusTextVisible(bool visible) { statusTextVisible = visible; }

    //==========================================================================
    // Generator (internal timecode source, replaces old SystemTime)
    //==========================================================================
    enum class GeneratorState { Stopped, Playing, Paused };

    GeneratorState getGeneratorState() const { return genState; }

    void generatorPlay()
    {
        if (genState == GeneratorState::Playing) return;

        // Explicit user transition; any pending natural-EOF marker is no
        // longer relevant to the next click on the timeline.
        genEndedAtEof = false;

        const bool wasStopped = (genState == GeneratorState::Stopped);
        if (wasStopped)
        {
            // Standard DAW / Pioneer CDJ loop semantics: when an A/B loop is
            // armed, pressing Play always starts at loopInMs regardless of
            // where the playhead was (the loop range defines the play
            // region).  Without the loop, fall back to genStartMs -- also
            // for an A/B the generator does not follow (#24,
            // generatorAbLoopFollowed): one the timecode loop ignores, which
            // would otherwise start the first pass at its In and skip Start
            // TC's cue, and one past where the generator stops without that
            // loop, which would stop it at once.  The loop's end and the
            // file's are taken with the length of the file the player holds,
            // also while a load is pending (GO, or OSC /gen/preset,
            // re-applying the preset whose file is loaded plays while its
            // request is in flight).  setGeneratorAudioFile keeps an A/B only
            // for the file the player holds; MainComponent also keeps one for
            // a file it does not hold yet -- after a restart, or while the
            // load of a GO before is pending -- and GO arms it only once this
            // has started (MainComponent::goGenPresetOnEngine), while a PLAY
            // in the meantime decides with the file the player holds, or
            // with none.
            double loopEndMs = 0.0;
            bool loopGapless = false;
            const bool loopTimecode = loopTimecodeEnd(loopEndMs, loopGapless, true);
            const double playFromMs = generatorAbLoopFollowed(loopTimecode, loopEndMs, loopGapless)
                                        ? genLoopInMs : genStartMs;
            const double fromMs = genCurrentMs;
            genCurrentMs = playFromMs;
            // A move made while the outputs are paused: the first playing
            // tick drops the mark, but a PAUSE before any tick (OSC play,
            // then pause) leaves the outputs paused on the old value, and
            // the mark then gives them this one (#24).
            markGeneratorParkedLocate(fromMs);
            // Sync the cue cursor too: the (prev, now] window for the very
            // first cue check after play-from-stopped should begin at the
            // play-from position, otherwise a leftover lastCueCheckMs from
            // a previous session could either skip cues or produce a
            // backward-jump false positive.
            lastCueCheckMs = (uint32_t) juce::jmax(0.0, playFromMs);
            cueCursorInclusive = true;   // a cue exactly at the play-from position fires
        }
        genLastTickTime = juce::Time::getMillisecondCounterHiRes();
        genState = GeneratorState::Playing;

        // Sync attached audio file with the generator position.  Skip the
        // seek when resuming from Pause: the audio transport already paused
        // at exactly this position, and seeking would invalidate the audio
        // reader's read-ahead buffer (a noticeable delay with MP3 because
        // the decoder has to re-decode frames from scratch).  Seeking is
        // only needed when coming back from Stop (position has been reset
        // to Start TC) or after an explicit setGeneratorPosition().
        if (wasStopped)
        {
            const double audioPosSec = juce::jmax(0.0, (genCurrentMs - genStartMs) / 1000.0);
            generatorAudioPlayer.seekSeconds(audioPosSec);
        }
        generatorAudioPlayer.play();
    }

    void generatorPause()
    {
        if (genState == GeneratorState::Playing)
        {
            genState = GeneratorState::Paused;
            generatorAudioPlayer.pause();
        }
    }

    /// Stop: back to Start TC.  From playing, the next tick's clean stop
    /// gives the outputs Start TC (routeTimecodeToOutputs).  Already paused
    /// or stopped elsewhere -- STOP after PAUSE, or after a stop at Stop TC
    /// or at the file's end -- the outputs are paused and get Start TC as a
    /// parked locate (markGeneratorParkedLocate, #24).  Message thread.
    void generatorStop()
    {
        const double fromMs = genCurrentMs;
        genState = GeneratorState::Stopped;
        // Explicit user transition; clear the natural-EOF marker so a
        // subsequent click on the timeline does NOT auto-resume.
        genEndedAtEof = false;
        genAudioLoopLastPassEndMs = 0.0;
        genCurrentMs = genStartMs;
        // Reset the crossing-based cue cursor too -- the next play will
        // start from genStartMs and we want the first tick's (prev, now]
        // window to begin at startMs, not at the position the previous
        // play session ended at.
        lastCueCheckMs = (uint32_t) juce::jmax(0.0, genStartMs);
        if (activeInput == InputSource::SystemTime)
        {
            currentTimecode = wallClockToTimecode(genCurrentMs, currentFps);
            setFramePhaseFromPosition(genCurrentMs, currentFps);
        }
        generatorAudioPlayer.stopAndReset();
        markGeneratorParkedLocate(fromMs);
    }

    /// Freewheel (AUDIT D10): how long the signal inputs (LTC, Art-Net,
    /// LA-Net, HippoNet) keep counting as present after the last frame or
    /// packet.  MTC stays present this long after the last quarter frame; a
    /// Full Frame does not refresh it and keeps the source present for two
    /// frames at most (MtcInput::setTimeoutMs, AUDIT LTC-13).  Operator's
    /// choice per engine; the senders count on their own through it, so a
    /// dropout shorter than this never reaches the wire.
    void setInputFreewheelMs(int ms)
    {
        inputFreewheelMs = juce::jlimit(50, 5000, ms);
        mtcInput.setTimeoutMs(inputFreewheelMs);
        ltcInput.setTimeoutMs(inputFreewheelMs);
        artnetInput.setTimeoutMs(inputFreewheelMs);
        laNetTCInput.setTimeoutMs(inputFreewheelMs);
        hippotizerInput.setTimeoutMs(inputFreewheelMs);
    }
    int getInputFreewheelMs() const { return inputFreewheelMs; }

    /// Name of the generator preset in use (empty when the fields were set
    /// by hand or no preset is selected).  Reported as the active track's
    /// title for the outputs that carry metadata.
    void setGeneratorPresetName(const juce::String& name) { genPresetName = name.trim(); }
    juce::String getGeneratorPresetName() const           { return genPresetName; }

    /// Set start timecode in ms from midnight.
    ///
    /// With the timecode loop (#24) Start TC is where each pass begins and
    /// what places the audio against the timecode (audio position =
    /// timecode - Start TC; on the gapless path modulo the length, where
    /// Start TC also places the end, Start TC + the file's length).  A
    /// change while the loop runs, on either path, seeks the audio here to
    /// where the timecode now is in the loop (seekGeneratorAudioIntoLoop),
    /// instead of leaving DESIGN D18 to drag the timecode towards the old
    /// relation (under a second apart) or leave the two apart (a second or
    /// more) -- until the next wrap on the seek path, for good on the
    /// gapless path, where no wrap seeks the audio.  Without the loop
    /// nothing is sought, as in 1.9.14, but for the player's loop held by
    /// syncGeneratorPlayerLooping (the timecode loop's last pass after it
    /// was turned off with the timecode before Start TC, or "Loop audio"
    /// turned off with the audio a whole pass ahead and in step): there the
    /// audio is folded the same way, Start TC + the file's length as the
    /// end, so it stays a whole pass ahead and in step with the new Start
    /// TC, the hold goes on and the pass is heard.  Left where it was, the
    /// audio would be as far out of step as Start TC moved, and the hold,
    /// which keeps only audio in step, would let go: the file would play to
    /// its end before the new Start TC and the pass would be silent.
    /// Stopped, the position moves to the new Start TC, and the paused
    /// outputs get it as a parked locate (markGeneratorParkedLocate, #24).
    /// Message thread.
    void setGeneratorStartMs(double ms)
    {
        const double prevStartMs = genStartMs;
        const bool wasHeld = generatorPlayerLoopHeld();
        genStartMs = juce::jmax(0.0, ms);
        if (genState == GeneratorState::Stopped && activeInput == InputSource::SystemTime)
        {
            const double fromMs = genCurrentMs;
            genCurrentMs = genStartMs;
            currentTimecode = wallClockToTimecode(genCurrentMs, currentFps);
            setFramePhaseFromPosition(genCurrentMs, currentFps);
            markGeneratorParkedLocate(fromMs);
        }

        if (genStartMs == prevStartMs)
            return;
        retargetGeneratorAudioLastPass();
        double endMs = 0.0;
        bool gapless = false;
        const bool loopActs = loopTimecodeEnd(endMs, gapless);
        if (wasHeld && ! loopActs)
            seekGeneratorAudioIntoLoop(genStartMs + generatorAudioPlayer.getFileLengthSeconds() * 1000.0, true);
        syncGeneratorPlayerLooping();
        if (genState != GeneratorState::Stopped && loopActs)
            seekGeneratorAudioIntoLoop(endMs, gapless);
    }

    /// Set stop timecode in ms from midnight. 0 = no stop (freerun).  With
    /// the timecode loop (#24) it may move the loop's end and switch its
    /// path (gapless at the file's end <-> seek at Stop TC); an end moved
    /// behind the playhead wraps at the next tick.  A switch to the gapless
    /// path while the loop runs also brings the audio to (timecode - Start
    /// TC) modulo the file's length (seekGeneratorAudioIntoLoop), when it
    /// is out of step: from then on no wrap seeks it and DESIGN D18
    /// compares the two modulo that length, so audio elsewhere when the
    /// path changed -- at the file's top under a timecode short of a Start
    /// TC moved past it, or still ahead of it after that -- would stay
    /// there on every pass.  Message thread.
    void setGeneratorStopMs(double ms)
    {
        double endMs = 0.0;
        bool gapless = false;
        const bool wasGapless = loopTimecodeEnd(endMs, gapless) && gapless;
        genStopMs = juce::jmax(0.0, ms);
        syncGeneratorPlayerLooping();
        if (genState != GeneratorState::Stopped && ! wasGapless && loopTimecodeEnd(endMs, gapless) && gapless)
            seekGeneratorAudioIntoLoop(endMs, true, true);
    }

    //==========================================================================
    // Generator timecode loop (#24): "Loop timecode" of a generator preset
    //==========================================================================
    //
    // The end is where the generator would stop without it: Stop TC, or
    // Start TC + the length of the audio file, whichever comes first (a Stop
    // TC beyond the file is the file's end, as the stop is today).  At the
    // end the timecode, the audio and the cues go back to Start TC instead
    // of stopping, for as long as it plays.  The end is exclusive: the pass
    // is exactly end - Start TC, and with the loop the Stop TC frame is not
    // published (without it, the stop still publishes it).  No end -- no
    // Stop TC and no file -- or a loop shorter than kMinLoopTimecodeMs: the
    // option does nothing and the generator stops as it does without it.
    //
    // Two ways round (loopTimecodeEnd):
    //  - gapless, when the end is the file's end (no Stop TC, or one less
    //    than a frame before the file's end, or past it): the player loops
    //    the file itself, sample-exact (setLooping), the timecode folds back
    //    by exactly the file's length with no seek, and DESIGN D18 compares
    //    the two modulo that length;
    //  - by seek, when the end is a Stop TC before the file's end, or there
    //    is no file: as the A/B loop, the audio is sought back to the top.
    // Both through wrapGenerator, which also fires the cues of the pass and
    // has the outputs told of the jump.
    //
    // An armed A/B loop inside it wins (checked first, and PLAY from
    // Stopped starts at its In).  One not inside it is ignored, PLAY
    // starting at Start TC (generatorAbLoopFollowed): In before Start TC,
    // Out past the end, or on the gapless path an Out within a tick
    // (kGenLoopTickMs) of the file's end, where the fold, or the player's
    // own loop, gets there before the A/B's seek.  "Loop audio only" and
    // this exclude each other, as the preset editor's two boxes untick
    // each other: set together (a preset file with both), this wins, and
    // turning this on (OSC) turns the engine's copy of the other off -- so
    // turning it off again always gives the last pass below, never a
    // return to "Loop audio".  Clock mode is untouched (updateGenerator
    // returns before any of this).
    //
    // The flag follows the audio file, not the preset selection: it is set
    // with the file (setGeneratorAudioFile), so the player's loop is carried
    // with the file in the same request; for the file that is loaded it is
    // also switched live, with "Loop audio" (setGeneratorLoopFlags: the
    // preset editor's Update; setGeneratorLoopTimecode: OSC looptc).  In
    // memory only; the preset holds it.  Everything here runs on the
    // message thread (the 60 Hz tick, the UI, OSC).

    /// The two end options of the file that is loaded, switched live (#24):
    /// "Loop audio only" (audioLoop) and "Loop timecode"
    /// (loopTimecode), with the rules they have at GO
    /// (setGeneratorAudioFile): they exclude each other and, both given,
    /// loopTimecode wins.  The preset editor's Update calls it with a
    /// preset's two boxes for the engine that has that preset loaded, so
    /// they take effect without GO.  Nothing else changes: the file, Start
    /// and Stop TC, the cues, the A/B loop and the transport state stay as
    /// they are.  Playing or paused (paused, from the next PLAY):
    ///  - none or Loop audio -> Loop timecode: the loop acts from the next
    ///    tick, as OSC looptc 1 does: a timecode past its end folds into it
    ///    (wrapGenerator); on the gapless path the player loops the file
    ///    (under Loop audio it already does), on the seek path it does not;
    ///  - Loop timecode -> none: its last pass, then a stop at its end, as
    ///    OSC looptc 0 does (syncGeneratorPlayerLooping holds the player's
    ///    loop while the audio finishes the pass before);
    ///  - Loop timecode -> Loop audio: the pass in progress plays on, and at
    ///    the file's end the audio goes round while the timecode counts on,
    ///    with no stop and no jump.  On the seek path -- a Stop TC set after
    ///    GO, before the file's end -- the player starts to loop and the
    ///    generator stops at that Stop TC, as Loop audio does with one;
    ///  - none -> Loop audio: the player loops the file from the pass in
    ///    progress on, and the generator no longer stops at its end;
    ///  - Loop audio -> none: the pass in progress ends at the file's end
    ///    and the generator stops there, as without the option.  In the
    ///    first pass, or before Start TC, the player stops looping at once,
    ///    unless the audio is then a whole pass ahead of the timecode and
    ///    in step with it: syncGeneratorPlayerLooping holds the loop until
    ///    the audio goes round, and the pass plays in step.  What decides is
    ///    where the audio is when the switch comes.  A jog before Start TC
    ///    under Loop audio (the audio then at the file's top), or a Start TC
    ///    moved later, leaves the audio ahead of the timecode and in general
    ///    out of step; DESIGN D18, comparing modulo the file's length in
    ///    Loop audio's first pass too, brings a remainder under a second
    ///    into step in the second or two after it, so a switch then is held
    ///    and the pass plays in step.  A switch soon after it, or with a
    ///    remainder of a second or more, finds the audio out of step: the
    ///    file plays on to its end, ahead of the timecode, and stops there,
    ///    as without the option.  From the second pass on
    ///    the timecode is past Start TC + the file's length, where the
    ///    generator would stop at once: the player keeps looping and the
    ///    generator stops at the end of the pass the timecode is in
    ///    (genAudioLoopLastPassEndMs), at the file's end of that pass.  A
    ///    seek, an A/B wrap or a Start TC change moves that end to the pass
    ///    the timecode is then in; into the first pass or before Start TC
    ///    there is none, as above (retargetGeneratorAudioLastPass).
    /// A switch that has the player loop the file -- onto the timecode
    /// loop's gapless path, or onto Loop audio with the timecode at or past
    /// Start TC -- brings audio more than kGenAudioInStepMs out of step to
    /// where the timecode puts it, (timecode - Start TC) modulo the file's
    /// length (seekGeneratorAudioIntoLoop), as a Stop TC that moves the loop
    /// to its gapless path does; audio in step is left where it is.  So
    /// audio left at the file's end by a jog past it while the file did not
    /// loop, or, onto the gapless path, at its top by a jog before Start TC,
    /// no longer stays apart from the timecode (DESIGN D18 pulls only a
    /// difference under a second).  The seek also takes a difference D18 is
    /// still closing, in the second or so after a jog or a Start TC change
    /// of under a second: the audio then jumps, repeating or skipping up to
    /// about a second, instead of D18 pulling the timecode, and the outputs
    /// with it, at up to 20 ms a tick.  Stopped, only the flags change and
    /// PLAY starts with them; the player's loop follows at once.  While a
    /// file load is pending the flags are set, there is no last pass (the
    /// length may still be the previous file's), the player's loop follows
    /// when the load completes (syncGeneratorPlayerLooping,
    /// onLoadCompleted), and meanwhile, with either option on, the end of
    /// the file being replaced does not stop the generator
    /// (updateGenerator).  Message thread.
    void setGeneratorLoopFlags(bool audioLoop, bool loopTimecode)
    {
        double endMs = 0.0;
        bool gapless = false;
        const bool wasGapless   = loopTimecodeEnd(endMs, gapless) && gapless;
        const bool wasAudioLoop = genAudioLoop;
        genLoopTimecode = loopTimecode;
        genAudioLoop    = audioLoop && ! loopTimecode;
        // Loop audio off, or still off with its last pass under way (the
        // same boxes pushed again): the last pass, if the timecode is past
        // the first.
        const bool lastPass = ! genAudioLoop && ! genLoopTimecode && genState != GeneratorState::Stopped
                              && (wasAudioLoop || genAudioLoopLastPassEndMs > 0.0);
        genAudioLoopLastPassEndMs = lastPass ? generatorAudioLastPassEndMs() : 0.0;
        syncGeneratorPlayerLooping();
        if (genState == GeneratorState::Stopped)
            return;
        if (! wasGapless && loopTimecodeEnd(endMs, gapless) && gapless)
            seekGeneratorAudioIntoLoop(endMs, true, true);
        else if (! wasAudioLoop && genAudioLoop && genCurrentMs >= genStartMs
                 && generatorAudioPlayer.hasFileLoaded() && ! generatorAudioPlayer.isLoadPending()
                 && generatorAudioPlayer.getFileLengthSeconds() > 0.0)
            seekGeneratorAudioIntoLoop(genStartMs + generatorAudioPlayer.getFileLengthSeconds() * 1000.0,
                                       true, true);
    }

    /// "Loop audio only" alone, live (setGeneratorLoopFlags).
    /// On, it turns the timecode loop off, as ticking its box in the preset
    /// editor unticks the other; off when it was not on changes nothing.
    /// Message thread.
    void setGeneratorAudioLoop(bool shouldLoop)
    {
        setGeneratorLoopFlags(shouldLoop, shouldLoop ? false : genLoopTimecode);
    }

    /// Turn the timecode loop on or off live (OSC /stc/N/gen/looptc;
    /// setGeneratorLoopFlags).  On, it also turns off the engine's copy of
    /// "Loop audio only" (the two exclude each other; this
    /// wins), so that off while it plays always gives a last pass, whatever
    /// the preset's "Loop audio" says: the pass in progress runs to the end
    /// and the generator stops there, as without the loop (the player stops
    /// looping and its position is folded back into the file,
    /// GeneratorAudioPlayer::setLoopingWhilePlaying).  "Loop audio" comes
    /// back with the next setGeneratorAudioFile (GO, the combo, OSC
    /// /gen/preset) or setGeneratorLoopFlags (the preset editor's Update).
    /// Off when it was not on changes nothing.  Message thread.
    void setGeneratorLoopTimecode(bool shouldLoop)
    {
        setGeneratorLoopFlags(shouldLoop ? false : genAudioLoop, shouldLoop);
    }

    /// The flag as last set (with the file, by OSC or by
    /// setGeneratorLoopFlags), whether or not the loop can act.
    bool getGeneratorLoopTimecode() const { return genLoopTimecode; }

    /// The engine's "Loop audio only" as last set (with the
    /// file or by setGeneratorLoopFlags; off while the timecode loop is on),
    /// whether or not a file is loaded.
    bool getGeneratorAudioLoop() const { return genAudioLoop; }

    /// True while "Loop audio only" runs: the flag is on and
    /// the player loops the loaded file, no load pending.  For the
    /// indicators, next to isGeneratorLoopTimecodeActive and
    /// isGeneratorAbLoopFollowed.  False with no file
    /// (a preset whose file is missing), while a load is pending, under the
    /// timecode loop (the two exclude each other), and after Loop audio is
    /// turned off live, where the player may still loop to the end of its
    /// last pass, or until the audio goes round (setGeneratorLoopFlags).
    /// Message thread.
    bool isGeneratorLoopAudioActive() const
    {
        return genAudioLoop && generatorAudioPlayer.hasFileLoaded()
            && ! generatorAudioPlayer.isLoadPending() && generatorAudioPlayer.isLooping();
    }

    /// True when the timecode loop acts: the flag is on and there is an end
    /// at least kMinLoopTimecodeMs after Start TC.  While a file load is
    /// pending, the file's end does not count yet (the length may still be
    /// the previous file's), so with no Stop TC this reads false until the
    /// load completes.  What the panel's STOP TC label and the waveform's
    /// LOOP TC show.
    bool isGeneratorLoopTimecodeActive() const
    {
        double endMs = 0.0;
        bool gapless = false;
        return loopTimecodeEnd(endMs, gapless);
    }

    /// The loop's end in ms from midnight (exclusive), or 0 when it does not
    /// act (isGeneratorLoopTimecodeActive).
    double getGeneratorLoopTimecodeEndMs() const
    {
        double endMs = 0.0;
        bool gapless = false;
        return loopTimecodeEnd(endMs, gapless) ? endMs : 0.0;
    }

    /// True when the loop acts and goes round gapless at the file's end
    /// (the player loops the file); false on the seek path or when it does
    /// not act.
    bool isGeneratorLoopTimecodeGapless() const
    {
        double endMs = 0.0;
        bool gapless = false;
        return loopTimecodeEnd(endMs, gapless) && gapless;
    }

    /// Shortest loop the option makes: below it, it does nothing.
    static constexpr double kMinLoopTimecodeMs = 1000.0;
    /// One tick of the 60 Hz generator timer: the margin before the file's
    /// end an A/B Out needs on the gapless path.
    static constexpr double kGenLoopTickMs = 1000.0 / 60.0;

    //==========================================================================
    // Generator A/B loop (programming aid: repeat a section of the track)
    //==========================================================================

    /// Set the loop In point.  Caller passes the absolute TC ms (same
    /// coordinate system as genCurrentMs).  No effect until
    /// setGeneratorLoopEnabled(true) is also called.
    void setGeneratorLoopInMs(double ms)  { genLoopInMs  = juce::jmax(0.0, ms); }

    /// Set the loop Out point.  Must be > loop In for the loop to be active.
    void setGeneratorLoopOutMs(double ms) { genLoopOutMs = juce::jmax(0.0, ms); }

    /// Enable / disable A/B loop.  When enabling and the loaded preset has
    /// no in/out set yet, the loop has no effect until points are placed.
    /// When the next Play after enabling fires, position snaps to loopInMs
    /// (standard DAW behaviour) -- caller does not need to seek manually.
    void setGeneratorLoopEnabled(bool e)  { genLoopEnabled = e; }

    double getGeneratorLoopInMs()    const { return genLoopInMs;    }
    double getGeneratorLoopOutMs()   const { return genLoopOutMs;   }
    bool   getGeneratorLoopEnabled() const { return genLoopEnabled; }

    /// True when a loop is currently in active use (enabled + valid range).
    bool isGeneratorLoopActive() const
    {
        return genLoopEnabled && genLoopOutMs > genLoopInMs;
    }

    /// True when the generator follows the A/B loop: armed
    /// (isGeneratorLoopActive) and not ignored (#24, generatorAbLoopFollowed:
    /// not inside the timecode loop, or, without it, past where the
    /// generator stops), as the tick decides.  What the waveform draws as
    /// armed.  Message thread.
    bool isGeneratorAbLoopFollowed() const
    {
        double endMs = 0.0;
        bool gapless = false;
        const bool loopTimecode = loopTimecodeEnd(endMs, gapless);
        return generatorAbLoopFollowed(loopTimecode, endMs, gapless);
    }

    /// Load Generator preset cues into the engine's armed-cue list.  Cue
    /// positions are converted from SMPTE TC strings to absolute ms (using
    /// the engine's current fps) so the existing tickCuePoints logic --
    /// originally written for TrackMap CDJ playhead in ms -- can be reused
    /// without modification.  Pass an empty vector to clear armed cues.
    ///
    /// The raw cue list is cached so a later setFrameRate() can rearm them
    /// with the new fps without the caller having to push the cues again.
    void setGeneratorCuePoints(const std::vector<GeneratorCuePoint>& cues)
    {
        rawGeneratorCues = cues;
        rearmGeneratorCues();
    }

private:
    /// Re-derive armedCues from rawGeneratorCues using currentFps.  Called
    /// by setGeneratorCuePoints (initial load, a preset applied again, the
    /// input switched back to the Generator) and setFrameRate (so a fps
    /// change recomputes the absolute-ms positions, which depend on fps in
    /// the frame component of HH:MM:SS:FF).
    ///
    /// The crossing cursor stays at the generator's position, so only the
    /// cues it crosses from there fire (DESIGN D36).  Setting it to 0, as
    /// this did, made the next tick fire every cue in (0, now] while the
    /// generator ran or was paused (AUDIT ENG-3).  From Stop, play moves the
    /// cursor to the play-from position anyway (generatorPlay).
    void rearmGeneratorCues()
    {
        armedCues.clear();
        lastCueCheckMs = (uint32_t) juce::jmax(0.0, genCurrentMs);
        if (rawGeneratorCues.empty()) return;

        armedCues.reserve(rawGeneratorCues.size());
        for (auto& gc : rawGeneratorCues)
        {
            ArmedCue ac;
            // Project the GeneratorCuePoint onto a plain CuePoint so the
            // shared dispatch code (triggerOutput.fireCuePoint, the
            // Art-Net path in tickCuePoints) doesn't need to know about
            // GeneratorCuePoint at all.
            ac.cue.positionMs  = gc.positionMs(frameRateToDouble(currentFps));
            ac.cue.name        = gc.name;
            ac.cue.midiChannel = gc.midiChannel;
            ac.cue.midiNoteNum = gc.midiNoteNum;
            ac.cue.midiNoteVel = gc.midiNoteVel;
            ac.cue.midiCCNum   = gc.midiCCNum;
            ac.cue.midiCCVal   = gc.midiCCVal;
            ac.cue.oscAddress  = gc.oscAddress;
            ac.cue.oscArgs     = gc.oscArgs;
            ac.cue.artnetCh    = gc.artnetCh;
            ac.cue.artnetVal   = gc.artnetVal;
            ac.fired = false;
            armedCues.push_back(std::move(ac));
        }
        std::sort(armedCues.begin(), armedCues.end(),
                  [](const ArmedCue& a, const ArmedCue& b)
                  { return a.cue.positionMs < b.cue.positionMs; });
    }

public:

    /// Seek the generator to a specific position (in ms from midnight) and
    /// resync the attached audio file.  State transitions:
    ///   Playing -> Playing (audio keeps playing from new pos)
    ///   Paused  -> Paused  (audio at new pos, not playing)
    ///   Stopped -> Paused  (preserves the seeked position; if we stayed in
    ///                       Stopped, the next generatorPlay() would reset
    ///                       genCurrentMs to genStartMs and discard the seek)
    ///   Stopped + genEndedAtEof -> Playing (the player just finished a
    ///                       track naturally; clicking the timeline is
    ///                       interpreted as "play from here", consistent
    ///                       with consumer media players)
    ///
    /// The caller is responsible for any clamping (e.g. against Stop TC or
    /// the audio file's length); this method only enforces newMs >= 0.
    /// The audio goes where the timecode puts it
    /// (seekGeneratorAudioToTimecode): timecode - Start TC, folded into the
    /// file while the player loops it, and on the timecode loop's gapless
    /// path also before Start TC (#24).
    ///
    /// A jump of kGenSeekAnnounceMs or more is told to the outputs as a
    /// seek (genJumpAnnounce, consumed by the next tick's
    /// routeTimecodeToOutputs): a click on the waveform or an OSC jog that
    /// far while the generator plays gives the MTC Full Frame, the
    /// immediate Art-Net / LA-Net / HippoNet frame and the LTC re-seed a
    /// CDJ hot cue gives (#24).  A shorter step -- each event of a drag on
    /// the waveform, a stream of small OSC jogs -- is not: announced on
    /// every event, the Full Frames and re-seeds would follow each other
    /// faster than an MTC quarter-frame cycle (2 frames) or an LTC frame
    /// lasts, and nothing whole would go out for as long as the gesture
    /// lasts; the senders' own value tracking follows such steps, as in
    /// 1.9.14.  While the generator is paused or stopped the outputs are
    /// paused and the flag is dropped there, as a DJ source's seek is; the
    /// new position goes to them instead as a parked locate, once it has
    /// rested for kGenParkedSettleMs, so a drag or a stream of jogs is told
    /// once, where it ends (markGeneratorParkedLocate, #24).
    /// Only for the generator in transport mode: an OSC jog reaches an
    /// engine whatever its input, and another source's outputs have
    /// nothing to announce.  Message thread.
    void setGeneratorPosition(double newMs)
    {
        const double fromMs = genCurrentMs;
        genCurrentMs    = juce::jmax(0.0, newMs);
        genLastTickTime = juce::Time::getMillisecondCounterHiRes();
        if (activeInput == InputSource::SystemTime && ! genClockMode
            && std::abs(genCurrentMs - fromMs) >= kGenSeekAnnounceMs)
            genJumpAnnounce = true;

        // Sync the cue check cursor to the seek destination so the next
        // crossing-based tick treats anything <= newMs as "already on the
        // wrong side" and won't fire it.  This is what makes "seek to a
        // cue and play" not retrigger the cue: the cue's positionMs is
        // equal to lastCueCheckMs, and the (prev, now] window is strict
        // on the lower bound.
        lastCueCheckMs = (uint32_t) juce::jmax(0.0, genCurrentMs);

        // Decide the post-seek state.  Stopped + genEndedAtEof means we
        // just finished the track on its own; treat the click as a
        // "resume from here" instead of a cue.  Any other Stopped becomes
        // Paused (preserves previous behaviour for cold scrub / post-Stop
        // scrub).  Playing / Paused are not modified.
        const bool resumeFromEof = (genState == GeneratorState::Stopped
                                    && genEndedAtEof);
        if (genState == GeneratorState::Stopped)
            genState = resumeFromEof ? GeneratorState::Playing
                                      : GeneratorState::Paused;
        markGeneratorParkedLocate(fromMs);

        // Consume the flag once acted on so the same click never
        // resumes twice.  Cleared regardless of whether we used it
        // (a click while Playing/Paused also implies the user has
        // moved on from the natural-end state).
        genEndedAtEof = false;
        retargetGeneratorAudioLastPass();

        if (activeInput == InputSource::SystemTime)
        {
            currentTimecode = wallClockToTimecode(genCurrentMs, currentFps);
            setFramePhaseFromPosition(genCurrentMs, currentFps);
        }

        seekGeneratorAudioToTimecode();

        // For the EOF-resume case, the audio player still has shouldPlay
        // cleared (stopAndReset was called when the EOF auto-stop fired),
        // so seekSeconds alone will not have restarted the transport.
        // Arm the play intent now; play() also calls transport.start()
        // at the just-seeked position.
        if (resumeFromEof)
            generatorAudioPlayer.play();
    }

    /// The smallest jump of the generator's own seek (setGeneratorPosition)
    /// that is announced to the outputs: the jump a DJ source's PLL takes
    /// for a seek (pll.seekDetected, an error over 500 ms).
    static constexpr double kGenSeekAnnounceMs = 500.0;

    double getGeneratorStartMs() const { return genStartMs; }
    double getGeneratorStopMs()  const { return genStopMs; }
    double getGeneratorCurrentMs() const { return genCurrentMs; }

    /// Read-only view of the Generator preset's currently armed cues.
    /// Empty when no preset is active or input source is not SystemTime.
    /// The list is mutated by setGeneratorCuePoints / clearing the input
    /// source change, so consumers should re-read on every paint rather
    /// than hold onto the reference across frames.
    const std::vector<GeneratorCuePoint>& getRawGeneratorCues() const
    {
        return rawGeneratorCues;
    }

    /// Clock mode: read wall clock (old SystemTime behavior) instead of generator transport.
    void setGeneratorClockMode(bool useSystemClock)
    {
        if (useSystemClock && !genClockMode)
            generatorStop();  // stop transport when switching to clock mode
        if (useSystemClock && ! genClockMode) clockFollower.reset();
        // A parked locate the stop above marks is left to the ticks (#24):
        // in Clock mode the outputs run from the next tick, and the first
        // tick back in transport mode is a clean stop, which clears it.
        // Switched on and off before a tick, the outputs never ran, and the
        // locate gives them Start TC.
        genClockMode = useSystemClock;
    }
    bool getGeneratorClockMode() const { return genClockMode; }

    //==========================================================================
    // Generator audio playback (per-engine output device for preset audio files)
    //==========================================================================
    /// Open or change the generator audio output device.
    /// channel: -1 = stereo (file L->ch0, R->ch1); >=0 = mono mix to that channel.
    bool startGeneratorAudio(const juce::String& typeName,
                              const juce::String& devName,
                              int channel = -1,
                              double sampleRate = 0,
                              int bufferSize = 0)
    {
        return generatorAudioPlayer.openDevice(typeName, devName, channel, sampleRate, bufferSize);
    }

    void stopGeneratorAudio() { generatorAudioPlayer.closeDevice(); }

    /// The generator's audio output was (re)opened (startGeneratorAudio:
    /// MainComponent::startCurrentGenAudio, for the AUDIO PLAYBACK DEVICE or
    /// AUDIO CHANNEL changed, or the output turned on), which attaches the
    /// loaded file at its top: bring the audio to where the timecode puts
    /// it, as a seek of the generator does (seekGeneratorAudioToTimecode,
    /// which on the timecode loop's gapless path folds a timecode before
    /// Start TC into the loop, #24), and start it while the generator
    /// plays.  Paused, the audio is only positioned, as PLAY from Paused
    /// does not seek: it used to stay at the file's top, and PLAY started
    /// it there wherever the timecode was.  Stopped, nothing: PLAY seeks.
    /// While a load is pending the player ignores the seek, and the load's
    /// completion brings the audio to the timecode.  Message thread.
    void resyncGeneratorAudioToTimecode()
    {
        if (genState == GeneratorState::Stopped)
            return;
        seekGeneratorAudioToTimecode();
        if (genState == GeneratorState::Playing)
            generatorAudioPlayer.play();
    }

    bool isGeneratorAudioRunning() const { return generatorAudioPlayer.isDeviceOpen(); }

    /// Load (or unload, when file is empty/missing) an audio file for the generator.
    /// Loop flag is applied at the same time so subsequent file ends honour it.
    /// Returns immediately -- the actual load runs on a dedicated I/O thread.
    ///
    /// shouldLoop is the preset's "Loop audio only";
    /// loopTimecode its "Loop timecode" (#24).  Both follow the file: they
    /// are set here, or live for the file that is loaded
    /// (setGeneratorLoopFlags, the preset editor's Update; OSC looptc,
    /// setGeneratorLoopTimecode), and the player's loop goes with the file
    /// in the same request.  That loop depends on the file's length when
    /// the timecode loop is on (on only for its gapless path), so the
    /// request carries a guess -- gapless unless a Stop TC is set -- which
    /// the load's completion settles (syncGeneratorPlayerLooping).  With
    /// both flags set, loopTimecode wins and the engine keeps shouldLoop
    /// off, as the preset editor's two boxes untick each other: turning the
    /// loop off later (OSC) then gives its last pass rather than "Loop
    /// audio".  Message thread.
    void setGeneratorAudioFile(const juce::File& file, bool shouldLoop, bool loopTimecode = false)
    {
        const juce::File f = (file == juce::File() || ! file.existsAsFile()) ? juce::File() : file;

        // On a real file change, clear A/B loop state.  Loop In/Out
        // are absolute TC ms tied to the previously loaded file's
        // timeline and are meaningless against a different track;
        // leaving them armed would either fire a wrap mid-playback
        // at an arbitrary point or visually mark a loop range that
        // does not correspond to anything on the new waveform.
        // Re-loading the SAME file (user re-applies the active
        // preset, OSC re-trigger) is detected by comparing against
        // the player's current file and leaves the loop untouched, so
        // the operator does not have to re-place the markers across
        // no-op reloads.  MainComponent sets the A/B again after this
        // by the file it last gave the engine with a preset (#24,
        // applyGenPresetToEngine): kept also for a file the player does
        // not hold yet -- after a restart, whose settings restore the
        // A/B but load no file, or while a load is pending.
        const juce::File prev = generatorAudioPlayer.getCurrentFile();
        if (f != prev)
        {
            genLoopInMs    = 0.0;
            genLoopOutMs   = 0.0;
            genLoopEnabled = false;
        }

        // New file (or unload) invalidates the natural-EOF marker -- a
        // click on the timeline of a freshly loaded track should cue,
        // not auto-resume from the previous track's EOF intent.
        genEndedAtEof = false;
        genAudioLoop    = shouldLoop && ! loopTimecode;
        genLoopTimecode = loopTimecode;
        genAudioLoopLastPassEndMs = 0.0;
        const bool playerLoops = loopTimecode ? (f != juce::File() && genStopMs <= 0.0) : shouldLoop;
        generatorAudioPlayer.requestLoad(f, playerLoops);
    }

    void clearGeneratorAudioFile()
    {
        // Same rationale as setGeneratorAudioFile on file change:
        // loop positions are tied to the loaded file, so unloading
        // also clears the loop.  Without this, the A/B LOOP toggle
        // and any saved In/Out would carry over to whatever file the
        // user loads next.
        genLoopInMs    = 0.0;
        genLoopOutMs   = 0.0;
        genLoopEnabled = false;
        genEndedAtEof  = false;
        genAudioLoop    = false;   // as setGeneratorAudioFile(File(), false)
        genLoopTimecode = false;
        genAudioLoopLastPassEndMs = 0.0;
        generatorAudioPlayer.requestLoad(juce::File(), false);
    }

    bool       hasGeneratorAudioFile()    const { return generatorAudioPlayer.hasFileLoaded(); }
    juce::File getGeneratorAudioFile()    const { return generatorAudioPlayer.getCurrentFile(); }
    bool       isGeneratorAudioPlaying()  const { return generatorAudioPlayer.isPlaying(); }
    bool       isGeneratorAudioLooping()  const { return generatorAudioPlayer.isLooping(); }

    /// Output volume for the generator audio playback (0..1.5 linear, 1=unity).
    void  setGeneratorAudioVolume(float linearGain) { generatorAudioPlayer.setOutputVolume(linearGain); }
    float getGeneratorAudioVolume() const           { return generatorAudioPlayer.getOutputVolume(); }

    /// Source-channel mode for the loaded audio file:
    /// 0 = stereo (use both), 1 = left-only, 2 = right-only.
    /// Useful for files that carry programme audio on one side and a
    /// reference signal (LTC, click track, etc.) on the other.
    void setGeneratorAudioFileChannelMode(int mode)
    {
        generatorAudioPlayer.setFileChannelMode((GeneratorAudioPlayer::FileChannelMode) mode);
    }
    int getGeneratorAudioFileChannelMode() const
    {
        return (int) generatorAudioPlayer.getFileChannelMode();
    }

    GeneratorAudioPlayer&       getGeneratorAudio()       { return generatorAudioPlayer; }
    const GeneratorAudioPlayer& getGeneratorAudio() const { return generatorAudioPlayer; }

    //==========================================================================
    // VU meter smoothed levels
    //==========================================================================
    float getSmoothedLtcInLevel() const  { return sLtcIn; }
    float getSmoothedThruInLevel() const { return sThruIn; }
    float getSmoothedLtcOutLevel() const { return sLtcOut; }
    float getSmoothedThruOutLevel() const { return sThruOut; }

    //==========================================================================
    // Helper queries
    //==========================================================================
    bool isInputStarted() const
    {
        switch (activeInput)
        {
            case InputSource::SystemTime: return true;
            case InputSource::MTC:        return mtcInput.getIsRunning();
            case InputSource::ArtNet:     return artnetInput.getIsRunning();
            case InputSource::LTC:        return ltcInput.getIsRunning();
            case InputSource::ProDJLink:  return sharedProDJLink != nullptr && sharedProDJLink->getIsRunning();
            case InputSource::StageLinQ:  return sharedStageLinQ != nullptr && sharedStageLinQ->getIsRunning();
            case InputSource::Hippotizer: return hippotizerInput.getIsRunning();
            case InputSource::Winamp:     return winampInput.getIsRunning();
            case InputSource::LANetTC:    return laNetTCInput.getIsRunning();
            default:                      return false;
        }
    }

    static juce::String inputSourceToString(InputSource src)
    {
        switch (src)
        {
            case InputSource::MTC:        return "MTC";
            case InputSource::ArtNet:     return "ArtNet";
            case InputSource::SystemTime: return "Generator";
            case InputSource::LTC:        return "LTC";
            case InputSource::ProDJLink:  return "ProDJLink";
            case InputSource::StageLinQ:  return "StageLinQ";
            case InputSource::Hippotizer: return "HippoNet";
            case InputSource::Winamp:     return "Winamp";
            case InputSource::LANetTC:    return "LANetTC";
        }
        return "Generator";
    }

    static InputSource stringToInputSource(const juce::String& s)
    {
        if (s == "MTC") return InputSource::MTC;
        if (s == "ArtNet") return InputSource::ArtNet;
        if (s == "LTC") return InputSource::LTC;
        if (s == "ProDJLink") return InputSource::ProDJLink;
        if (s == "StageLinQ") return InputSource::StageLinQ;
        if (s == "HippoNet" || s == "Hippotizer") return InputSource::Hippotizer;
        if (s == "Winamp") return InputSource::Winamp;
        if (s == "TCNet") return InputSource::ProDJLink;  // legacy migration
        if (s == "Generator" || s == "SystemTime") return InputSource::SystemTime;  // backward compat
        if (s == "LANetTC") return InputSource::LANetTC;
        return InputSource::SystemTime;
    }

    static juce::String getInputName(InputSource s)
    {
        switch (s)
        {
            case InputSource::MTC:        return "MTC";
            case InputSource::ArtNet:     return "ART-NET";
            case InputSource::SystemTime: return "GENERATOR";
            case InputSource::LTC:        return "LTC";
            case InputSource::ProDJLink:  return "PRO DJ LINK";
            case InputSource::StageLinQ:  return "STAGELINQ";
            case InputSource::Hippotizer: return "HIPPONET";
            case InputSource::Winamp:     return "WINAMP";
            case InputSource::LANetTC:    return "LA-NET";
            default:                      return "---";
        }
    }

    static int fpsToIndex(FrameRate fps)
    {
        switch (fps)
        {
            case FrameRate::FPS_2398: return 0;
            case FrameRate::FPS_24:   return 1;
            case FrameRate::FPS_25:   return 2;
            case FrameRate::FPS_2997: return 3;
            case FrameRate::FPS_30:   return 4;
        }
        return 4;
    }

    static FrameRate indexToFps(int index)
    {
        switch (index)
        {
            case 0: return FrameRate::FPS_2398;
            case 1: return FrameRate::FPS_24;
            case 2: return FrameRate::FPS_25;
            case 3: return FrameRate::FPS_2997;
            case 4: return FrameRate::FPS_30;
        }
        return FrameRate::FPS_30;
    }

private:
    //--------------------------------------------------------------------------
    int engineIndex;
    juce::String engineName;

    // Input state
    InputSource activeInput = InputSource::SystemTime;
    FrameRate currentFps = FrameRate::FPS_30;
    Timecode currentTimecode;
    bool sourceActive = true;
    bool outputsWereActive = false;  // previous sourceActive state for transition detection
    // A 23.976 or 29.97 the user chose over a signal input that reads it as
    // 24 or 30 (followDetectedRate).  Named for LTC, where it began; MTC,
    // Art-Net and LA-Net honour it too (AUDIT NET-4).
    bool userOverrodeLtcFps = false;
    // MTC locate while stopped (AUDIT LTC-13): the frozen value of the last
    // inactive tick.  forwardParkedLocate is the one-shot request to pass a
    // new position on to the paused outputs (routeTimecodeToOutputs), set
    // for the MTC source's locate (tick) and the generator's
    // (updateGeneratorParkedLocate, #24).
    Timecode mtcParkedTc;
    bool mtcParkedValid = false;
    bool forwardParkedLocate = false;
    // The generator's parked locate (#24): a position change made while the
    // generator (transport mode) is paused or stopped and its outputs are
    // paused.  genParkedPending and genParkedChangedMs (hi-res ms of the
    // last change) are set by the generator functions
    // (markGeneratorParkedLocate); genParkedGivenMs is the position the
    // outputs were last given -- the clean stop's or the last parked
    // locate's, or where the outputs were found paused at start-up or
    // after an input switch -- valid while genParkedGivenValid.  One value
    // for every output: an output that was off when a locate went out, or
    // is switched on while paused, gets the position at the next locate or
    // PLAY.  Message thread: the generator functions (UI, OSC) and the tick
    // both run there.
    bool   genParkedPending    = false;
    double genParkedChangedMs  = 0.0;
    double genParkedGivenMs    = 0.0;
    bool   genParkedGivenValid = false;

    // Generator state (internal timecode source)
    GeneratorState genState = GeneratorState::Stopped;
    bool   genClockMode = true;    // true = wall clock (old SystemTime), false = transport generator
    double genStartMs   = 0.0;     // start TC in ms from midnight
    double genStopMs    = 0.0;     // stop TC in ms (0 = freerun)
    double genCurrentMs = 0.0;     // current position in ms
    int inputFreewheelMs = (int) kSourceTimeoutMs;   // AUDIT D10
    juce::String genPresetName;        // preset in use, for metadata (see getActiveTrackInfo)
    double genLastTickTime = 0.0;
    bool   cueCursorInclusive = false;  // next crossing check includes a cue exactly at lastCueCheckMs
    int    lastLoggedGapCount = 0;      // LTC output gaps already written to ltc_gaps.log
    int    lastLoggedTrackCount = 0;    // LTC value corrections already written there (DESIGN D30)
    WallClockFollower clockFollower;    // clock mode: time of day, followed rather than jumped to (DESIGN D31)
    double genLastAudioMs = -1.0;       // audio clock discipline (updateGenerator)
    double genLastAudioMoveTs = 0.0;  // hiRes ms for delta calculation
    // Timecode loop (#24; see "Generator timecode loop" above): the preset's
    // "Loop timecode" and "Loop audio only" as given with the
    // file (setGeneratorAudioFile) or live (setGeneratorLoopFlags; the first
    // also by OSC).  Never both true: setting the first clears the second.
    // genAudioLoopLastPassEndMs: Loop audio turned off live from its second
    // pass on, where its last pass ends -- the end of the pass the timecode
    // is in, a file's end in ms from midnight -- and the generator stops; 0
    // otherwise (setGeneratorLoopFlags, generatorAudioLastPassEndMs).
    // Message thread.
    bool   genLoopTimecode = false;
    bool   genAudioLoop    = false;
    double genAudioLoopLastPassEndMs = 0.0;

    // A/B loop: when genLoopEnabled and genLoopOutMs > genLoopInMs, the tick
    // wraps genCurrentMs from loopOutMs back to loopInMs, keeping what the
    // tick ran past Out (wrapGenerator).  Pressing Play with loop
    // enabled snaps position to loopInMs first (standard DAW / CDJ loop).
    // Set and cleared on the message thread, which also runs the tick, so
    // no lock is needed.
    // Cleared automatically in setGeneratorAudioFile / clearGeneratorAudioFile
    // when a different file is loaded, so the loop is effectively
    // per-track within the engine: switching pistas wipes In/Out/Enabled
    // since they are absolute ms against the previous file's timeline.
    double genLoopInMs    = 0.0;
    double genLoopOutMs   = 0.0;
    bool   genLoopEnabled = false;
    // Set when the generator stops automatically because the loaded audio
    // file reached EOF (as opposed to a user-initiated stop).  Consumed by
    // setGeneratorPosition() so that a click on the timeline immediately
    // after the track ends both seeks and resumes audio in one action,
    // matching the muscle memory of consumer media players.  Cleared by
    // any explicit user transition (Play / Stop / file change / input
    // source change), so it never survives a context switch.
    bool   genEndedAtEof = false;
    // The generator's timecode jumped -- a loop wrap (wrapGenerator), or its
    // own seek of kGenSeekAnnounceMs or more (setGeneratorPosition) -- and
    // the outputs are to be told as for a seek: routeTimecodeToOutputs
    // consumes it exactly like a DJ source's pll.seekDetected (MTC Full
    // Frame, an immediate Art-Net / LA-Net / HippoNet frame, LTC re-seed),
    // instead of each sender finding the jump with its own value tracking
    // (#24).  Set and consumed on the message thread (the tick, the UI,
    // OSC).
    bool   genJumpAnnounce = false;

    // Generator audio playback (per-engine, optional)
    GeneratorAudioPlayer generatorAudioPlayer;

    // FPS conversion
    bool fpsConvertEnabled = false;
    FrameRate outputFps = FrameRate::FPS_30;
    Timecode outputTimecode;

    // Output state
    bool outputMtcEnabled    = false;
    bool outputArtnetEnabled = false;
    bool outputLANetTCEnabled = false;
    bool outputLtcEnabled    = false;
    bool outputThruEnabled   = false;
    bool outputTcnetEnabled  = false;
    bool outputHippoEnabled  = false;
    int  tcnetLayer          = 0;      // TCNet layer index 0-3

    // On-air gate: when enabled, the engine only produces active timecode
    // when the current CDJ is flagged on-air by the DJM mixer. This uses the
    // mixer's own gating logic (fader + cross-fader + EQ + mute), so no
    // threshold or channel selection is needed.
    bool onAirGateEnabled = false;
    int  onAirQuietStep = 0;      // OFF AIR AT, StageLinQ ON AIR (DESIGN D34): 0 = SILENCE

    int mtcOutputOffset    = 0;
    int artnetOutputOffset = 0;
    int laNetTCOutputOffset = 0;
    int ltcOutputOffset    = 0;
    juce::String ltcUserBitsHex;   // normalised LTC user-bits hex ("" = zero)
    bool ltcUserBitsReversed = false;   // MANUAL mode: reverse the group order for GoPro-style readers
    juce::String ltcUserBitsName;  // 4-char label for kUserBitsName ("" = STC<n>)
    int ltcUserBitsMode = kUserBitsManual;
    double lastSystemDateCheckMs = 0.0;   // throttles the date recompute to ~1Hz

    /// Feed the encoder in the dynamic user-bits modes.  Called once per
    /// output routing tick; cheap and a no-op in MANUAL mode.
    void refreshDynamicUserBits()
    {
        if (ltcUserBitsMode == kUserBitsFromLtcIn)
        {
            // Passthrough: mirror whatever the LTC input last decoded.
            // On signal loss the input keeps its last good value, so the
            // output HOLDS rather than dropping to zeros -- a receiver
            // gating on user bits should not see them vanish during a
            // brief dropout.  Stays 0 if the LTC input never ran.
            //
            // With them go the flags that say what they carry, BGF0 and
            // BGF2 (12M-1 sec. 8.4.1: eight-bit characters, ST 309 date and
            // zone, page/line): a passed-through date or text used to go out
            // declared as free-form data, BGF 0/0/0 (AUDIT ENG-11).  BGF1
            // stays 0: it describes the time address, which here is STC's,
            // not the input's.  Both are read as one record, from the same
            // frame (AUDIT LTC-8).
            const auto frame = ltcInput.getLastFrame();
            ltcOutput.setUserBits(frame.userBits);
            ltcOutput.setBinaryGroupFlags((uint8_t)(frame.binaryGroupFlags & 0x5));
        }
        else if (ltcUserBitsMode == kUserBitsName)
        {
            // Four-character label.  Defaults to STC<engine number> when the
            // operator has not typed anything, as suggested in issue #13.
            juce::String label = ltcUserBitsName;
            if (label.isEmpty())
                label = "STC" + juce::String(juce::jlimit(1, 9, engineIndex + 1));
            ltcOutput.setUserBits(packNameUserBits(label));
            // BGF0 = 1 signals an eight-bit character set (12M-1 sec. 8.4.2).
            ltcOutput.setBinaryGroupFlags(0x1);
        }
        else if (ltcUserBitsMode == kUserBitsSystemDate)
        {
            // ST 309 date and zone, re-read once a second so midnight and DST
            // changes are followed (ST 309 sec. 5.4).
            const double now = juce::Time::getMillisecondCounterHiRes();
            if (now - lastSystemDateCheckMs >= 1000.0)
            {
                lastSystemDateCheckMs = now;
                ltcOutput.setUserBits(systemDateUserBits());
                ltcOutput.setBinaryGroupFlags(0x4);
            }
        }
    }
    int tcnetOutputOffsetMs = 0;   // TCNet offset in milliseconds

    // Protocol handlers
    MtcInput     mtcInput;
    MtcOutput    mtcOutput;
    ArtnetInput  artnetInput;
    ArtnetOutput artnetOutput;
    LANetTimecodeInput  laNetTCInput;
    LANetTimecodeOutput laNetTCOutput;
    HippotizerInput hippotizerInput;
    HippotizerOutput hippotizerOutput;
    LtcInput     ltcInput;
    LtcOutput    ltcOutput;
    WinampInput  winampInput;
    ProDJLinkInput* sharedProDJLink = nullptr;  // shared across engines
    StageLinQInput* sharedStageLinQ = nullptr;  // shared across engines
    DbServerClient* dbClient       = nullptr;  // shared across engines (Phase 2)
    int             proDJLinkPlayer = 1;        // per-engine player selection (1..6, 7=XF-A, 8=XF-B, 9=MASTER, 10=ON AIR)

    // Crossfader auto-follow (XF-A / XF-B mode), Master and ON AIR auto-follow.
    static constexpr int kPlayerXfA    = 7;        // auto-follow crossfader side A
    static constexpr int kPlayerXfB    = 8;        // auto-follow crossfader side B
    static constexpr int kPlayerMaster = 9;        // auto-follow whichever player has DJM master
    static constexpr int kPlayerOnAir  = 10;       // auto-follow the deck on air (DESIGN D34, Pro DJ Link and StageLinQ)
    int  resolvedXfPlayer = 0;                  // physical player currently followed in XF / MASTER / ON AIR mode

    bool isXfMode() const     { return proDJLinkPlayer == kPlayerXfA || proDJLinkPlayer == kPlayerXfB; }
    bool isMasterMode() const { return proDJLinkPlayer == kPlayerMaster; }
    bool isOnAirMode() const  { return proDJLinkPlayer == kPlayerOnAir; }
    bool isAutoMode() const   { return isXfMode() || isMasterMode() || isOnAirMode(); }

    /// The auto mode's name as the player combo shows it, for status text.
    const char* autoModeLabel() const
    {
        switch (proDJLinkPlayer)
        {
            case kPlayerXfA:    return "XF-A";
            case kPlayerXfB:    return "XF-B";
            case kPlayerMaster: return "MASTER";
            case kPlayerOnAir:  return "ON AIR";
            default:            return "";
        }
    }

    /// The selections StageLinQ offers: DECK 1-4, XF-A, XF-B, ON AIR.  (No
    /// MASTER: that would need its own resolver for StageLinQ.)
    static int sanitiseStageLinQPlayer(int p)
    {
        if ((p >= 1 && p <= StageLinQ::kMaxDecks)
            || p == kPlayerXfA || p == kPlayerXfB || p == kPlayerOnAir)
            return p;
        return 1;
    }

    /// Resolve which physical player to follow in XF-A/XF-B mode.
    /// Sticky: stays on current player while it has on-air flag.
    /// Falls back to another player on the same XF side when current loses on-air.
    /// Channels 1 to the mixer's count: 6 on a DJM-V10, 4 otherwise (it
    /// stopped at 4, AUDIT ENG-9).
    void resolveXfPlayer()
    {
        if (!sharedProDJLink || !sharedProDJLink->hasMixerFaderData())
            return;

        uint8_t targetSide = (proDJLinkPlayer == kPlayerXfA) ? 1 : 2; // 1=A, 2=B
        const int channels = sharedProDJLink->getMixerChannelCount();

        // Sticky: keep current if still assigned to our side AND on-air
        if (resolvedXfPlayer >= 1 && resolvedXfPlayer <= channels)
        {
            uint8_t xf = sharedProDJLink->getChannelXfAssign(resolvedXfPlayer);
            bool onAir = sharedProDJLink->isPlayerOnAir(resolvedXfPlayer);
            if (xf == targetSide && onAir)
                return;  // still valid
        }

        // Current player lost on-air or wrong side -- find replacement
        // Prefer on-air players on our side
        for (int ch = 1; ch <= channels; ++ch)
        {
            uint8_t xf = sharedProDJLink->getChannelXfAssign(ch);
            if (xf == targetSide && sharedProDJLink->isPlayerOnAir(ch))
            {
                switchResolvedPlayer(ch);
                return;
            }
        }

        // No on-air player -- keep current if still on right side (just faded out)
        if (resolvedXfPlayer >= 1 && resolvedXfPlayer <= channels)
        {
            uint8_t xf = sharedProDJLink->getChannelXfAssign(resolvedXfPlayer);
            if (xf == targetSide)
                return;
        }

        // Find any player on this side (not on-air but assigned)
        for (int ch = 1; ch <= channels; ++ch)
        {
            uint8_t xf = sharedProDJLink->getChannelXfAssign(ch);
            if (xf == targetSide)
            {
                switchResolvedPlayer(ch);
                return;
            }
        }

        // No player assigned to this side at all
        if (resolvedXfPlayer != 0)
        {
            resolvedXfPlayer = 0;
            pll.reset(); clearBeatGrid(); pdlTcFrozen = false; pdlLastPlayheadMs = 0; pdlLastAbsPosTs = 0.0;
            pdlSnapMs = 0.0; pdlSnapTime = 0.0; pdlSnapSpeed = 1.0;
        }
    }

    /// Resolve which physical player to follow in MASTER mode.
    /// Sticky: stays on the current master while it remains master.
    /// When a new player becomes master, switch to it.
    /// Falls back to whichever player most recently held master if no player
    /// currently has the flag (rare, brief gaps during track loads).
    void resolveMasterPlayer()
    {
        if (!sharedProDJLink) return;

        // Sticky: keep current player if it still holds master.
        if (resolvedXfPlayer >= 1 && resolvedXfPlayer <= 6
            && sharedProDJLink->isPlayerMaster(resolvedXfPlayer))
        {
            return;
        }

        // Find the player that currently holds master.
        for (int ch = 1; ch <= 6; ++ch)
        {
            if (sharedProDJLink->isPlayerMaster(ch))
            {
                switchResolvedPlayer(ch);
                return;
            }
        }

        // No player currently reports master.  Keep the previous one (the
        // master flag often goes briefly low during track load); the next
        // tick will pick up the new master once it's announced.
        if (resolvedXfPlayer >= 1 && resolvedXfPlayer <= 6)
            return;

        // First tick with no master ever seen -- nothing to follow yet.
        // resolvedXfPlayer stays 0 and the engine will idle until a master
        // appears.
    }

    /// Resolve XF-A/XF-B for StageLinQ.  Same sticky logic as ProDJLink.
    /// On air from isDeckOnAir (ExternalMixerVolume above silence when the
    /// device sends it).  Sides from /Mixer/ChannelAssignmentN, values
    /// assumed 0=THRU, 1=A, 2=B -- which a PRIME 4+ never sends (#23 second
    /// capture), so on that unit XF finds no deck and the status says why.
    void resolveXfPlayerStageLinQ()
    {
        if (!sharedStageLinQ || !sharedStageLinQ->hasMixerData())
            return;

        int targetSide = (proDJLinkPlayer == kPlayerXfA) ? 1 : 2;

        // Helper: get crossfader assignment for a channel.
        // Values assumed: 0=THRU, 1=A, 2=B -- awaiting hardware confirmation.
        auto getAssign = [this](int ch) -> int
        {
            return sharedStageLinQ->getChannelAssignment(ch);
        };

        // Sticky: keep current if still assigned to our side AND on-air
        if (resolvedXfPlayer >= 1 && resolvedXfPlayer <= StageLinQ::kMaxDecks)
        {
            int assign = getAssign(resolvedXfPlayer);
            bool onAir = sharedStageLinQ->isDeckOnAir(resolvedXfPlayer);
            if (assign == targetSide && onAir)
                return;  // still valid
        }

        // Find on-air replacement on our side
        for (int ch = 1; ch <= StageLinQ::kMaxDecks; ++ch)
        {
            int assign = getAssign(ch);
            if (assign == targetSide && sharedStageLinQ->isDeckOnAir(ch))
            {
                switchResolvedPlayer(ch);
                return;
            }
        }

        // No on-air player -- keep current if still on right side
        if (resolvedXfPlayer >= 1 && resolvedXfPlayer <= StageLinQ::kMaxDecks)
        {
            int assign = getAssign(resolvedXfPlayer);
            if (assign == targetSide)
                return;
        }

        // Find any player on this side
        for (int ch = 1; ch <= StageLinQ::kMaxDecks; ++ch)
        {
            int assign = getAssign(ch);
            if (assign == targetSide)
            {
                switchResolvedPlayer(ch);
                return;
            }
        }

        // No player assigned to this side
        if (resolvedXfPlayer != 0)
        {
            resolvedXfPlayer = 0;
            pll.reset(); clearBeatGrid(); pdlTcFrozen = false; pdlLastPlayheadMs = 0; pdlLastAbsPosTs = 0.0;
            pdlSnapMs = 0.0; pdlSnapTime = 0.0; pdlSnapSpeed = 1.0;
        }
    }

    /// Resolve which deck to follow in ON AIR mode (DESIGN D34), for Pro DJ Link
    /// (players 1-6, on air from the DJM, loudest by channel fader) and for
    /// StageLinQ (decks 1-4, on air above the OFF AIR AT level and loudest
    /// by ExternalMixerVolume).  The
    /// rule itself is OnAirFollow::pick: the current deck until it goes quiet
    /// or stops, then the loudest one playing on air, else stay.
    void resolveOnAirPlayer()
    {
        OnAirFollow::Deck candidates[ProDJLink::kMaxPlayers];
        int count = 0;

        if (activeInput == InputSource::ProDJLink && sharedProDJLink != nullptr)
        {
            count = ProDJLink::kMaxPlayers;
            for (int p = 1; p <= count; ++p)
                candidates[p - 1] = { sharedProDJLink->isPlayerPlaying(p),
                                      sharedProDJLink->getOnAirLevel(p) };
        }
        else if (activeInput == InputSource::StageLinQ && sharedStageLinQ != nullptr)
        {
            static_assert(StageLinQ::kMaxDecks <= ProDJLink::kMaxPlayers, "candidate array size");
            count = StageLinQ::kMaxDecks;
            const double quiet = StageLinQ::onAirQuietLevel(onAirQuietStep);
            for (int d = 1; d <= count; ++d)
                candidates[d - 1] = { sharedStageLinQ->isPlayerPlaying(d),
                                      sharedStageLinQ->getOnAirLevel(d, quiet) };
        }

        const int next = OnAirFollow::pick(resolvedXfPlayer, candidates, count);
        if (next != resolvedXfPlayer)
            switchResolvedPlayer(next);
    }

    /// Switch the resolved player with a mini-reset (PLL + track cache)
    void switchResolvedPlayer(int newPlayer)
    {
        if (newPlayer == resolvedXfPlayer) return;
        DBG("TimecodeEngine[" + engineName + "]: XF resolved player "
            + juce::String(resolvedXfPlayer) + " -> " + juce::String(newPlayer));
        resolvedXfPlayer = newPlayer;
        // Reset PLL and track cache so we start clean on the new player
        pll.reset(); clearBeatGrid(); pdlTcFrozen = false; pdlLastPlayheadMs = 0; pdlLastAbsPosTs = 0.0;
        pdlSnapMs = 0.0; pdlSnapTime = 0.0; pdlSnapSpeed = 1.0;
        cachedTrackId = 0;
        cachedLoadedPlayer = cachedLoadedSlot = 0;
        cachedMediaChanges = 0;
        dbRequestIp.clear();
        cachedTrackArtist.clear();
        cachedTrackTitle.clear();
        cachedTrackDurationSec = 0;
        trackMapped = false;
        cachedOffH = cachedOffM = cachedOffS = cachedOffF = 0;
        cachedBpmMultiplier = 0;
        lastSeenTrackVersion = 0;
        armedCues.clear();
        lastCueCheckMs = cueFlagsAtMs = cueStopRawMs = 0;
        cueArmPending = cueWasPlaying = cueRelocated = cueFlagsAtIncl = false;   // the new deck's list arms at its playhead
        lastSentClockBpm = -1.0f;
        lastSentOscBpm   = -1.0f;
        bpmPlayerOverride = kBpmNoOverride;
        ltcOutput.setPitchMultiplier(1.0);
    }

    //==========================================================================
    // Playhead PLL -- the DJ source's speed and seek verdict.
    //
    // A free-running clock that advances at the deck's actual speed (CDJ
    // status offset 152; StageLinQ's BeatInfo rate) and is pulled towards
    // each new position.  What it feeds today (AUDIT D4, ENG-15):
    //   - `pitch`: the LTC encoder's bit rate (setPitchMultiplier) and the
    //     speed TCNet carries (getSourceSpeedRatio);
    //   - `actualSpeed` / `smoothVelocity`: the source-active test;
    //   - `seekDetected` (an error over 500 ms): cue dispatch's seek rule
    //     (DESIGN D17 and D36; on the Pro DJ Link beat fallback not for a
    //     step of one beat, AUDIT ENG-2) and the outputs' resync.
    // The timecode does NOT come from it: tick() interpolates the deck's own
    // position (pdlSnapMs/pdlSnapTime/pdlSnapSpeed), and `positionMs` serves
    // only the 500 ms seek test.
    //
    // CDJ actual speed (offset 152) is the real playback rate including:
    //   - Motor ramp on play (0 -> target over ~0.5s)
    //   - Motor ramp on pause (target -> 0 over ~4-5s)
    //   - Jog wheel adjustments
    //   - Pitch fader changes
    // so the pitch follows ramps without transient/stable modes; dp/dt
    // between packets is kept as the fallback for a player that reports no
    // speed.
    //==========================================================================
    struct PlayheadPLL
    {
        double positionMs     = 0.0;  // the PLL's position (ms): only the seek test reads it
        double lastTickTime   = 0.0;  // timestamp of last tick
        double lastPacketTs   = 0.0;  // to detect new CDJ packets
        double lastCdjPos     = 0.0;  // previous CDJ position (for velocity calc)
        double pitch          = 0.0;  // effective speed for LTC encoding
        double smoothVelocity = 0.0;  // dp/dt fallback for non-CDJ-3000
        double actualSpeed    = 0.0;  // real playback speed (offset 152) -- includes motor ramp
        bool   playing        = false; // CDJ play state (PLAYING/LOOPING/CUE_PLAY)
        bool   initialized    = false;
        bool   seekDetected   = false; // set when position jumps >500ms (seek/hot cue/track load)

        // Below this, encoder bits become absurdly long -> glitches
        static constexpr double kMinEncodingPitch = 0.08;  // ~-92%

        // Velocity below this = stopped
        static constexpr double kDeadZone = 0.005;  // 0.5% speed

        void reset()
        {
            positionMs     = 0.0;
            lastTickTime   = 0.0;
            lastPacketTs   = 0.0;
            lastCdjPos     = 0.0;
            pitch          = 0.0;
            smoothVelocity = 0.0;
            actualSpeed    = 0.0;
            playing        = false;
            seekDetected   = false;
            initialized    = false;
        }

        // State-aware PLL driven by CDJ actual speed (one call per tick, 60 Hz):
        //
        //   Position input:
        //     CDJ-3000:   absolute playhead at 30Hz (type 0x0b) -- ms precision
        //     NXS2/older: beat-derived at ~5Hz (beatCount x 60000/BPM from status)
        //     StageLinQ:  each BeatInfo message's position (~35 ms)
        //
        //   Drive velocity: actualSpeed from CDJ status (offset 152).
        //     Includes motor ramp, jog, pitch changes -- everything.
        //     Fallback to dp/dt if actualSpeed is 0 (non-CDJ-3000 models).
        //
        //   CDJ state determines correction strategy:
        //     PLAYING:                 PLL interpolates, graduated correction (8-25%)
        //     PAUSED but decelerating: PLL still drives (respects motor ramp)
        //     PAUSED and stopped:      snap to CDJ position (zero oscillation)
        //     END_OF_TRACK:            handled externally by pdlTcFrozen
        //
        //   Hard reset on >500ms error (seek/track change).

        void tick(uint32_t cdjPlayheadMs, double cdjPacketTs, double cdjActualSpeed,
                  bool cdjPlaying)
        {
            double now = juce::Time::getMillisecondCounterHiRes();
            double cdjPos = double(cdjPlayheadMs);

            if (!initialized)
            {
                positionMs     = cdjPos;
                lastTickTime   = now;
                lastPacketTs   = cdjPacketTs;
                lastCdjPos     = cdjPos;
                actualSpeed    = cdjActualSpeed;
                pitch          = 0.0;
                smoothVelocity = 0.0;
                playing        = cdjPlaying;
                initialized    = true;
                return;
            }

            // --- Advance free-running clock ---
            double elapsed = now - lastTickTime;
            lastTickTime = now;
            actualSpeed = cdjActualSpeed;
            playing     = cdjPlaying;

            // When actualSpeed confirms the player is stopped, decay the dp/dt
            // fallback toward zero.  Without this, noise in the NXS2 beat-derived
            // position can leave smoothVelocity just above kDeadZone, causing a
            // slow position creep even though the CDJ reports 0 speed.
            if (actualSpeed <= kDeadZone && std::abs(smoothVelocity) > 0.0)
                smoothVelocity *= 0.8;  // decays to <kDeadZone in ~5 ticks

            // Drive at CDJ's actual motor speed. This already includes:
            //   - Acceleration ramp on play start
            //   - Deceleration ramp on pause
            //   - Jog wheel adjustments
            //   - Pitch fader changes applied through motor
            // Fallback to dp/dt for models that don't report actualSpeed.
            double driveVelocity = (actualSpeed > kDeadZone) ? actualSpeed : smoothVelocity;

            // When CDJ is not playing AND velocity is near zero, we're truly stopped.
            // Don't interpolate -- just hold position and snap on next packet.
            // This eliminates micro-oscillation from timer jitter (especially macOS).
            bool trulyStopped = !playing && std::abs(driveVelocity) <= kDeadZone;

            if (!trulyStopped && std::abs(driveVelocity) > kDeadZone
                && elapsed > 0.0 && elapsed < 200.0)
                positionMs += elapsed * driveVelocity;

            // Pitch for LTC encoder
            double absVel = std::abs(driveVelocity);
            pitch = (absVel > kDeadZone) ? std::max(absVel, kMinEncodingPitch) : 0.0;

            // --- Correct against CDJ when new packet arrives ---
            if (cdjPacketTs != lastPacketTs && cdjPacketTs > 0.0)
            {
                double packetDt = cdjPacketTs - lastPacketTs;
                double posDelta = cdjPos - lastCdjPos;
                lastPacketTs = cdjPacketTs;
                lastCdjPos = cdjPos;

                // dp/dt measurement: kept as fallback for NXS2 and older models
                // that may not report actualSpeed in status packets.
                if (packetDt > 0.0 && packetDt < 200.0)
                {
                    double instantVel = posDelta / packetDt;
                    constexpr double kAlpha = 0.6;
                    smoothVelocity = smoothVelocity * (1.0 - kAlpha) + instantVel * kAlpha;
                    if (std::abs(smoothVelocity) < kDeadZone)
                        smoothVelocity = 0.0;
                }
                else
                {
                    smoothVelocity = 0.0;
                }

                // --- Position correction ---
                double error = cdjPos - positionMs;
                double absErr = std::abs(error);
                if (absErr > 500.0)
                {
                    // Seek or track change: snap immediately
                    positionMs = cdjPos;
                    seekDetected = true;  // signal engine to resync outputs
                }
                else if (trulyStopped)
                {
                    // Stopped: snap directly to CDJ position.
                    positionMs = cdjPos;
                }
                else
                {
                    // Playing or decelerating: graduated correction.
                    //   |error| 50-500ms -> 25% per packet (fast convergence)
                    //   |error| < 50ms   -> 8% per packet  (gentle, avoids overshoot)
                    double gain = (absErr > 50.0) ? 0.25 : 0.08;
                    positionMs += error * gain;
                }
            }

            if (positionMs < 0.0) positionMs = 0.0;
        }

        /// Beat grid nudge: within 15 ms of a beat, move the PLL position 3 %
        /// of the way to it per tick (90 % in about 75 ticks, 1.25 s at
        /// 60 Hz).  It touches only positionMs, which serves only the 500 ms
        /// seek test, so it changes nothing that is sent: the LTC output's
        /// phase comes from the interpolated position in tick() (DESIGN D5),
        /// not from here (AUDIT ENG-15; it also makes AUDIT B3 moot).
        void beatGridCorrect(const std::vector<TrackMetadata::BeatEntry>& grid)
        {
            if (grid.empty() || !playing || positionMs < 1.0) return;

            // Binary search: find nearest beat to current position
            uint32_t posMs = (uint32_t)positionMs;
            int lo = 0, hi = (int)grid.size() - 1, best = 0;
            while (lo <= hi)
            {
                int mid = (lo + hi) / 2;
                if (grid[(size_t)mid].timeMs <= posMs)
                    { best = mid; lo = mid + 1; }
                else
                    hi = mid - 1;
            }

            // Check both the beat before and after current position
            double nearestMs = (double)grid[(size_t)best].timeMs;
            if (best + 1 < (int)grid.size())
            {
                double nextMs = (double)grid[(size_t)(best + 1)].timeMs;
                if (std::abs(nextMs - positionMs) < std::abs(nearestMs - positionMs))
                    nearestMs = nextMs;
            }

            double beatErr = nearestMs - positionMs;
            double absBeatErr = std::abs(beatErr);

            // Only correct if within 15ms of a beat (avoids correcting during
            // transitions between beats).  3 % per tick.
            if (absBeatErr > 0.5 && absBeatErr < 15.0)
                positionMs += beatErr * 0.03;
        }

        uint32_t getPositionMs() const { return uint32_t(juce::jmax(0.0, positionMs)); }   // no caller
    };

    PlayheadPLL pll;
    // How long past the last position the DJ branches interpolate, in wall
    // time (tick): CDJ-3000 abspos (every 30 ms) and StageLinQ BeatInfo
    // (about every 35 ms), one late or lost message bridged; NXS2 status
    // packets, 5 Hz.
    static constexpr double kInterpolationCapMs     = 60.0;
    static constexpr double kNxs2InterpolationCapMs = 250.0;
    Timecode pdlFrozenTc {};          // frozen timecode on end-of-track (prevents flicker)
    bool pdlTcFrozen = false;         // true = outputting frozen timecode
    uint32_t pdlLastPlayheadMs = 0;   // last CDJ playhead for change detection
    double pdlLastAbsPosTs = 0.0;     // last absPositionTs for NXS2 new-packet detection
    double pdlSnapMs = 0.0;           // playhead ms at last CDJ packet (interpolation anchor)
    double pdlSnapTime = 0.0;         // hi-res timestamp of last CDJ packet
    double pdlSnapSpeed = 1.0;        // actualSpeed at last CDJ packet

    // This engine's player's rekordbox beat grid (DbServerClient's cache,
    // refreshBeatGridFromDb; setBeatGrid).  On the NXS2 beat fallback (no
    // 0x0b) it gives the position: the time of the beat the beat count
    // names, which is what goes on the wire, hence one grid per engine
    // (AUDIT ENG-4).  It also nudges the PLL position (beatGridCorrect),
    // which changes nothing that is sent (AUDIT ENG-15).
    std::vector<TrackMetadata::BeatEntry> pdlBeatGrid;
    uint32_t pdlBeatGridTrackId = 0;  // track ID for which beat grid is loaded
    uint32_t beatGridCheckedVersion = 0;  // dbserver cache version last looked at (refreshBeatGridFromDb)

    LinkBridge   linkBridge;
    std::unique_ptr<AudioThru> audioThru;  // Only for primary engine

    // Audio BPM detection (every source but Pro DJ Link and StageLinQ)
    AudioBpmInput audioBpmInput;
    bool audioBpmEnabled = false;

    // Status
    juce::String inputStatusText = "SYSTEM CLOCK";
    juce::String mtcOutStatusText, artnetOutStatusText, ltcOutStatusText, thruOutStatusText, hippoOutStatusText, laNetTCOutStatusText;
    bool statusTextVisible = true;  // only build inputStatusText when engine is displayed

    // VU meter smoothed state
    float sLtcIn = 0.0f, sThruIn = 0.0f, sLtcOut = 0.0f, sThruOut = 0.0f;

    // TrackMap state (track-to-offset mapping)
    TrackMap* trackMapPtr       = nullptr;
    TrackMapOverrides trackMapOverrides;   // this engine's layer over the global map (copied to/from its settings block)
    TrackMapEntry effectiveEntry;          // global entry with this engine's overrides applied
    MixerMap* mixerMapPtr       = nullptr;
    MixerMap* slqMixerMapPtr    = nullptr;  // Denon StageLinQ mixer map
    bool      trackMapEnabled   = false;
    bool      trackMapped       = false;    // current track has a mapping
    uint32_t  cachedTrackId     = 0;        // currently tracked Track ID: rekordbox ID (Pro DJ Link), deck load counter (StageLinQ), 0 (Winamp)
    uint8_t   cachedLoadedPlayer = 0;       // Pro DJ Link: player (Dr) and slot (Sr) the track was
    uint8_t   cachedLoadedSlot   = 0;       //   loaded from -- part of its identity (AUDIT PDL-7)
    uint32_t  cachedMediaChanges = 0;       //   ... and that slot's media change count (AUDIT META-4)
    juce::String dbRequestIp;               // Pro DJ Link: address last asked for its metadata (AUDIT PDL-3)
    uint32_t  lastSeenTrackVersion = 0;     // per-engine version counter for track change detection
    int       cachedOffH = 0, cachedOffM = 0, cachedOffS = 0, cachedOffF = 0;
    juce::String cachedTrackArtist, cachedTrackTitle;
    int cachedTrackDurationSec = 0;

    // Track change triggers
    TriggerOutput triggerOutput;

    // MIDI Clock (BPM), OSC Forward (BPM)
    bool midiClockEnabled = false;     // MIDI Clock (24ppqn) for BPM
    float lastSentClockBpm = -1.0f;    // dedup: last BPM sent to clock

    // BPM multiplier: session-level per-player override (set by UI buttons, not persisted)
    // 0=1x (passthrough override), 1=x2, 2=x4, -1=/2, -2=/4, kBpmNoOverride(-99)=no override
    int  bpmPlayerOverride   = -99;  // = kBpmNoOverride (literal avoids forward-ref with MSVC)
    // BPM multiplier: cached from TrackMap entry on track change
    int  cachedBpmMultiplier = 0;

    bool oscForwardEnabled    = false;
    bool oscMixerForwardEnabled  = false;
    bool midiMixerForwardEnabled = false;
    bool artnetMixerForwardEnabled = false;
    int  midiMixerCCChannel      = 1;   // 1-16 (for CC messages)
    int  midiMixerNoteChannel    = 1;   // 1-16 (for Note messages)
    int  artnetMixerUniverse     = 0;   // 0-32767
    uint8_t dmxBuffer[512] {};          // DMX frame of the Art-Net mixer forward (Pro DJ Link or StageLinQ; emptied on a source change)
    int  dmxHighWaterMark = 0;          // highest DMX channel written since then
    double lastDmxSendTime = 0.0;       // for periodic re-send (DMX timeout compliance)

    // Track trigger Art-Net DMX (one-shot on track change, separate from mixer forward)
    uint8_t trigDmxBuffer[512] {};      // persistent: previous trigger values stay until overwritten
    int  trigDmxHighWater = 0;
    int  artnetTriggerUniverse = 1;     // default universe 1 (separate from mixer universe 0)
    bool artnetTriggerEnabled = false;  // must be enabled for Art-Net DMX track triggers to fire

    // --- Cue point firing state ---
    // Armed cue points for the currently loaded track.  Loaded from TrackMap
    // on track change, sorted by positionMs.  Each has a `fired` flag that is
    // set when the playhead crosses the cue and reset on track change or seek.
    struct ArmedCue
    {
        CuePoint cue;           // copy of the cue point data (trigger config)
        bool     fired = false;
    };
    std::vector<ArmedCue> armedCues;
    // Raw cue list for the Generator path, kept so a frame-rate change
    // can re-derive armedCues with the new fps (the frame-component of
    // each cue's TC contributes a fps-dependent ms offset).  Empty when
    // no Generator preset is active or a TrackMap cue load took over.
    std::vector<GeneratorCuePoint> rawGeneratorCues;
    uint32_t lastCueCheckMs = 0;   // last playhead position used for cue check (seek detection)
    // TrackMap cue arming (dispatchTrackCues, DESIGN D36).  Message thread.
    bool cueArmPending = false;    // list (re)loaded: arm it at the next playhead seen
    bool cueWasPlaying = false;    // the deck played at the last dispatch
    bool cueRelocated  = false;    // the source reported a seek while the deck did not play
    uint32_t cueFlagsAtMs = 0;     // the playhead the fired flags stand for: every cue before it
                                   // is fired or passed, none after it (armCuesAt, tickCuePoints)
    bool cueFlagsAtIncl = false;   // ... and a cue exactly at it is too (it was checked, not just armed)
    uint32_t cueStopRawMs = 0;     // the source's own position (not interpolated) at the last
                                   // dispatch while playing or at the arm, raised to the
                                   // furthest one seen while the deck does not play
    // A play position this far or less behind cueStopRawMs is not a move back
    // (dispatchTrackCues): Winamp's position runs on up to one 50 ms poll past
    // the pause; the DJ sources' own positions do not move while stopped.
    static constexpr uint32_t kCueMovedBackMs = 100;
    uint32_t pdlPrevBeatCount = 0; // Pro DJ Link: the followed player's beat count at the last tick
                                   // (the cue dispatch's one-beat test, AUDIT ENG-2)
    juce::String oscFwdBpmAddr = "/composition/tempocontroller/tempo";
    juce::String oscFwdBpmCmd;  // e.g. "Master 3.x at %BPM%" -- if non-empty, sends string instead of float
    float lastSentOscBpm = -1.0f;      // dedup: last sent OSC value

    static constexpr float kOscBpmThreshold = 0.05f;   // 0.05 BPM

    // Mixer fader dedup (last sent values, -1 = never sent)
    // MixerMap-driven dedup: one slot per MixerMap entry (at most kMaxMixerEntries)
    static constexpr int kMaxMixerEntries = 128;  // 6ch x 13 params + ~45 globals
    int lastSentMixer[kMaxMixerEntries];  // initialised to -1 in constructor/reset
    uint32_t lastMixerPktCount = 0;      // for dirty-flag skip in forwardMixerParams

    // StageLinQ mixer dedup: 4 faders + 1 crossfader (0-255 scaled)
    static constexpr int kSlqMixerSlots = 5;  // CH1..CH4 fader + crossfader
    int lastSentSlqMixer[kSlqMixerSlots] = { -1, -1, -1, -1, -1 };

public:
    void setMidiClockEnabled(bool enabled)
    {
        midiClockEnabled = enabled;
        if (enabled && triggerOutput.isMidiOpen())
        {
            float bpm = 0.0f;
            if (activeInput == InputSource::StageLinQ && sharedStageLinQ != nullptr)
            {
                // Same order as the StageLinQ tick: master tempo, then the
                // followed deck (the selection itself is 7-10 in auto modes).
                bpm = (float)sharedStageLinQ->getMasterBPM();
                if (bpm <= 0.0f) bpm = (float)sharedStageLinQ->getBPM(getEffectivePlayer());
            }
            else if (activeInput == InputSource::ProDJLink && sharedProDJLink != nullptr)
            {
                bpm = (float)sharedProDJLink->getMasterBPM();
                if (bpm <= 0.0f) bpm = (float)sharedProDJLink->getBPM(getEffectivePlayer());
            }
            // Fallback: audio BPM detection (non-DJ sources)
            if (bpm <= 0.0f && audioBpmEnabled && audioBpmInput.hasBpm())
                bpm = (float)audioBpmInput.getBpm();
            triggerOutput.startMidiClock(bpm > 0.0f ? (double)bpm : 120.0);
        }
        else
        {
            triggerOutput.stopMidiClock();
        }
        lastSentClockBpm = -1.0f;
    }
    bool isMidiClockEnabled() const { return midiClockEnabled; }

    // Sentinel value: "no session override active" (falls through to TrackMap).
    static constexpr int kBpmNoOverride = -99;

    // BPM multiplier -- session-level per-player override (not persisted).
    // Valid values: 0=1x (passthrough), 1=x2, 2=x4, -1=/2, -2=/4.
    // Use kBpmNoOverride to clear the override (falls through to TrackMap).
    // Session override takes priority over TrackMap value.
    void setBpmPlayerOverride(int mult)
    {
        if (mult == kBpmNoOverride)
        {
            bpmPlayerOverride = kBpmNoOverride;
        }
        else
        {
            static const int kValid[] = { -2, -1, 0, 1, 2 };
            bool ok = false;
            for (int v : kValid) if (v == mult) { ok = true; break; }
            bpmPlayerOverride = ok ? mult : kBpmNoOverride;
        }
        lastSentClockBpm = -1.0f;   // force resend
        lastSentOscBpm   = -1.0f;
    }
    int getBpmPlayerOverride() const { return bpmPlayerOverride; }

    // Allows external code (e.g. ProDJLinkView double-click save) to sync the
    // cached TrackMap value without waiting for the next lookupTrackInMap call.
    void setCachedBpmMultiplier(int mult)
    {
        cachedBpmMultiplier = mult;
        lastSentClockBpm = -1.0f;
        lastSentOscBpm   = -1.0f;
    }

    /// Hand the engine the rekordbox beat grid of `trackId`.  The engine
    /// fetches its own player's grid from the dbserver cache since AUDIT
    /// ENG-4 (refreshBeatGridFromDb), so this only gets it there sooner when
    /// the UI already has it; a grid for another track than the one the
    /// engine follows, or for an engine not on Pro DJ Link (whose track id
    /// is not a rekordbox ID), is ignored.  The grid gives the NXS2's
    /// position (see tick) and nudges the PLL.  Cleared on track change.
    /// Message thread.
    void setBeatGrid(const std::vector<TrackMetadata::BeatEntry>& grid, uint32_t trackId)
    {
        if (activeInput != InputSource::ProDJLink || trackId == 0 || trackId != cachedTrackId) return;
        if (trackId == pdlBeatGridTrackId && !pdlBeatGrid.empty()) return;
        pdlBeatGrid = grid;
        pdlBeatGridTrackId = trackId;
    }

    void clearBeatGrid()
    {
        pdlBeatGrid.clear();
        pdlBeatGridTrackId = 0;
        beatGridCheckedVersion = 0;
    }

    // Returns the effective multiplier: session override if set, else TrackMap value.
    int getEffectiveBpmMultiplier() const
    {
        return (bpmPlayerOverride != kBpmNoOverride) ? bpmPlayerOverride : cachedBpmMultiplier;
    }

    // Helper: apply effective multiplier to a raw BPM value
    static double applyBpmMultiplier(double bpm, int mult)
    {
        switch (mult)
        {
            case  1: return bpm * 2.0;
            case  2: return bpm * 4.0;
            case -1: return bpm * 0.5;
            case -2: return bpm * 0.25;
            default: return bpm;
        }
    }

    void setOscForward(bool enabled,
                       const juce::String& bpmAddr = "/composition/tempocontroller/tempo",
                       const juce::String& bpmCmd = {})
    {
        oscForwardEnabled = enabled;
        oscFwdBpmAddr = bpmAddr;
        oscFwdBpmCmd = bpmCmd;
        lastSentOscBpm = -1.0f;
    }
    bool isOscForwardEnabled() const { return oscForwardEnabled; }
    juce::String getOscFwdBpmAddr() const { return oscFwdBpmAddr; }
    juce::String getOscFwdBpmCmd() const  { return oscFwdBpmCmd; }

    // Send BPM via OSC: if command template is set, send as string; otherwise as float
    void sendBpmOsc(double bpm)
    {
        if (!oscForwardEnabled || !triggerOutput.isOscConnected() || bpm <= 0.0) return;
        if (std::abs((float)bpm - lastSentOscBpm) < kOscBpmThreshold) return;

        if (oscFwdBpmCmd.isNotEmpty())
        {
            // Template mode: replace %BPM% with actual value
            auto cmd = oscFwdBpmCmd.replace("%BPM%", juce::String(bpm, 1));
            triggerOutput.sendOscString(oscFwdBpmAddr, cmd);
        }
        else
        {
            triggerOutput.sendOscFloat(oscFwdBpmAddr, (float)bpm);
        }
        lastSentOscBpm = (float)bpm;
    }

    void setOscMixerForward(bool enabled)
    {
        oscMixerForwardEnabled = enabled;
        std::fill(std::begin(lastSentMixer), std::end(lastSentMixer), -1); lastMixerPktCount = 0;
    }
    bool isOscMixerForwardEnabled() const { return oscMixerForwardEnabled; }

    void setMidiMixerForward(bool enabled, int ccChannel = 1, int noteChannel = 1)
    {
        midiMixerForwardEnabled = enabled;
        midiMixerCCChannel = juce::jlimit(1, 16, ccChannel);
        midiMixerNoteChannel = juce::jlimit(1, 16, noteChannel);
        std::fill(std::begin(lastSentMixer), std::end(lastSentMixer), -1); lastMixerPktCount = 0;
    }
    bool isMidiMixerForwardEnabled() const { return midiMixerForwardEnabled; }
    int  getMidiMixerCCChannel()     const { return midiMixerCCChannel; }
    int  getMidiMixerNoteChannel()   const { return midiMixerNoteChannel; }

    void setArtnetMixerForward(bool enabled, int universe = 0)
    {
        artnetMixerForwardEnabled = enabled;
        artnetMixerUniverse = juce::jlimit(0, 32767, universe);
        std::fill(std::begin(lastSentMixer), std::end(lastSentMixer), -1); lastMixerPktCount = 0;
        std::memset(dmxBuffer, 0, sizeof(dmxBuffer));
        dmxHighWaterMark = 0;
        lastDmxSendTime = 0.0;
    }
    bool isArtnetMixerForwardEnabled() const { return artnetMixerForwardEnabled; }
    int  getArtnetMixerUniverse()      const { return artnetMixerUniverse; }

    void setArtnetTriggerUniverse(int universe) { artnetTriggerUniverse = juce::jlimit(0, 32767, universe); }
    int  getArtnetTriggerUniverse() const       { return artnetTriggerUniverse; }

    void setArtnetTriggerEnabled(bool enabled) { artnetTriggerEnabled = enabled; }
    bool isArtnetTriggerEnabled() const        { return artnetTriggerEnabled; }

    //----------------------------------------------------------------------
    // Ableton Link -- BPM sync to Link session
    //----------------------------------------------------------------------
    LinkBridge& getLinkBridge() { return linkBridge; }
    const LinkBridge& getLinkBridge() const { return linkBridge; }
private:

    /// Where the followed player's track lives for dbserver: the address of
    /// the player holding the media (Dr; the player itself when 0) and the
    /// slot (Sr) -- the key the metadata cache is filed under
    /// (DbServerClient, AUDIT META-5).  Pro DJ Link only: a rekordbox ID
    /// means nothing on another input, where the engine's track id is a
    /// StageLinQ version or 0 (AUDIT ENG-8).  False when there is no such
    /// source.  Message thread.
    bool getDbSource(juce::String& ip, uint8_t& slot) const
    {
        if (activeInput != InputSource::ProDJLink || sharedProDJLink == nullptr) return false;
        const int effP = getEffectivePlayer();
        if (effP < 1) return false;
        uint8_t src = sharedProDJLink->getLoadedPlayer(effP);
        if (src == 0) src = (uint8_t) effP;
        ip = sharedProDJLink->getPlayerIP((int) src);
        slot = sharedProDJLink->getLoadedSlot(effP);
        return ip.isNotEmpty() && slot != 0;
    }

    /// The cached dbserver metadata of the track this engine follows, by the
    /// exact key (getDbSource).  The lookup by ID alone could answer with
    /// another medium's track that shares the ID (AUDIT META-5), or, on
    /// StageLinQ, with whatever rekordbox track has the number of the deck's
    /// load counter (AUDIT ENG-8).  Invalid when there is no Pro DJ Link
    /// source or nothing is cached.  Message thread.
    DbServerClient::MetadataLight getTrackDbMetadata() const
    {
        juce::String ip;
        uint8_t slot = 0;
        if (dbClient == nullptr || cachedTrackId == 0 || !getDbSource(ip, slot)) return {};
        return dbClient->getCachedMetadataLight(ip, slot, cachedTrackId);
    }

    /// This engine's beat grid (AUDIT ENG-4): the grid of the track its own
    /// player has loaded, from the dbserver cache, taken when that track's
    /// cache entry changes (a version number, so the full entry is copied
    /// only then).  The grid used to arrive only through setBeatGrid() from
    /// the engine on screen and the PDL View, so on an NXS2, where the grid
    /// gives the position (tick()), what an engine sent depended on which
    /// tab was open.  Message thread.
    void refreshBeatGridFromDb()
    {
        if (dbClient == nullptr || cachedTrackId == 0) return;
        if (!pdlBeatGrid.empty() && pdlBeatGridTrackId == cachedTrackId) return;
        juce::String ip;
        uint8_t slot = 0;
        if (!getDbSource(ip, slot)) return;
        const uint32_t version = dbClient->getMetadataVersion(ip, slot, cachedTrackId);
        if (version == 0 || version == beatGridCheckedVersion) return;
        beatGridCheckedVersion = version;
        auto meta = dbClient->getCachedMetadata(ip, slot, cachedTrackId);
        if (meta.hasBeatGrid())
        {
            pdlBeatGrid = std::move(meta.beatGrid);
            pdlBeatGridTrackId = cachedTrackId;
        }
    }

    /// Request metadata from dbserver for a track on the current ProDJLink player.
    /// Encapsulates source-player discovery, dbCtx collision avoidance, and model propagation.
    void requestDbMetadata(uint32_t trackId)
    {
        if (dbClient == nullptr || !dbClient->getIsRunning()) return;
        if (sharedProDJLink == nullptr || !sharedProDJLink->getIsRunning()) return;

        int effP = getEffectivePlayer();
        if (effP < 1) return;

        uint8_t srcPlayer = sharedProDJLink->getLoadedPlayer(effP);
        if (srcPlayer == 0) srcPlayer = (uint8_t)effP;
        juce::String srcIP = sharedProDJLink->getPlayerIP((int)srcPlayer);
        uint8_t slot = sharedProDJLink->getLoadedSlot(effP);
        dbRequestIp = srcIP;   // asked of this address (see the re-request in tick)

        if (srcIP.isEmpty() || slot == 0)
        {
            DBG("TimecodeEngine: SKIPPED metadata -- srcIP empty or slot=0");
            return;
        }

        // Choose dbserver query identity.
        // CDJ-3000: accepts player 5 (our VCDJ number) — use it directly.
        // NXS2/older: rejects player 5, requires 1-4 that's present on the
        // network.  Use suggestDbPlayerNumber() to find a valid candidate.
        // Keyed on the CDJ-3000 FORMAT of 0x0b: an NXS2 that streams its own
        // 0x0b format has absolute position too, and used to be asked as
        // player 5 because of it (AUDIT A20).
        int dbCtx;
        bool srcIs3000 = sharedProDJLink->playerSends3000Position((int)srcPlayer);
        if (srcIs3000)
        {
            dbCtx = sharedProDJLink->getVCDJPlayerNumber();
            // Safety: if VCDJ coincidentally matches source, pick another
            if (dbCtx == (int)srcPlayer)
                dbCtx = (srcPlayer != 1) ? 1 : 2;
        }
        else
        {
            // NXS2: suggestDbPlayerNumber already picks a valid 1-4 excluding
            // srcPlayer.  If it returns srcPlayer (last resort: only player on
            // network), that's the best we can do — don't override to a
            // non-existent player.
            dbCtx = sharedProDJLink->suggestDbPlayerNumber((int)srcPlayer);
            if (dbCtx == 0)
            {
                DBG("TimecodeEngine: SKIPPED metadata -- no valid player 1-4 for NXS2 query");
                return;
            }
        }

        juce::String model = sharedProDJLink->getPlayerModel((int)srcPlayer);

        DBG("TimecodeEngine: metadata request -- srcPlayer=" + juce::String(srcPlayer)
            + " srcIP=" + srcIP + " slot=" + juce::String(slot)
            + " dbCtx=" + juce::String(dbCtx) + " model=" + model);

        dbClient->requestMetadata(srcIP, slot, 1, trackId, dbCtx, model);
    }

    /// Lookup a track in the TrackMap by artist+title and cache the offset values.
    /// Called when a track change is detected or metadata is resolved.
    /// Returns the matched entry pointer (or nullptr if not found/malformed).
    const TrackMapEntry* lookupTrackInMap()
    {
        if (!trackMapPtr || cachedTrackTitle.isEmpty())
        {
            trackMapped = false;
            return nullptr;
        }

        auto* entry = trackMapPtr->find(cachedTrackArtist, cachedTrackTitle,
                                        cachedTrackDurationSec);

        // Duration fallback: when duration resolves late (deferred pickup),
        // the key changes from "artist|title" to "artist|title|300".  If the
        // user's entry was saved without duration (legacy or manual add),
        // the duration-aware lookup misses.  Fall back to duration=0 so we
        // don't lose the TrackMap match (and its armed cue points).
        if (!entry && cachedTrackDurationSec > 0)
            entry = trackMapPtr->find(cachedTrackArtist, cachedTrackTitle, 0);

        // Last resort: ignore duration entirely.  Catches the case where the
        // entry was saved with a duration that differs from the engine's cached
        // duration (e.g. PDL View saved with CDJ-reported duration while the
        // engine's cachedTrackDurationSec was still 0 or stale from an earlier
        // enrichment pass).
        if (!entry)
            entry = trackMapPtr->findIgnoringDuration(cachedTrackArtist, cachedTrackTitle);

        // Per-engine override layer: triggers, BPM multiplier and cue points
        // come from this engine's override when it has one for the track;
        // identity, offset and notes stay global.  An override without a
        // global entry still works (offset zero, identity from the key).
        if (!trackMapOverrides.empty())
        {
            if (const auto* ovr = trackMapOverrides.resolve(cachedTrackArtist, cachedTrackTitle,
                                                            cachedTrackDurationSec))
            {
                TrackMapEntry base;
                if (entry) base = *entry;
                else { base.artist = cachedTrackArtist; base.title = cachedTrackTitle; base.durationSec = cachedTrackDurationSec; }
                effectiveEntry = TrackMapOverrides::apply(base, *ovr);
                entry = &effectiveEntry;
            }
        }

        if (entry)
        {
            int h, m, s, f;
            if (TrackMapEntry::parseTimecodeString(entry->timecodeOffset, h, m, s, f))
            {
                cachedOffH = h;
                cachedOffM = m;
                cachedOffS = s;
                cachedOffF = f;
                trackMapped = true;

                cachedBpmMultiplier = entry->bpmMultiplier;
                lastSentClockBpm = -1.0f;
                lastSentOscBpm   = -1.0f;
                return entry;
            }
            else
            {
                trackMapped = false;
                cachedOffH = cachedOffM = cachedOffS = cachedOffF = 0;
                cachedBpmMultiplier = 0;
                return nullptr;
            }
        }
        else
        {
            trackMapped = false;
            cachedOffH = cachedOffM = cachedOffS = cachedOffF = 0;
            cachedBpmMultiplier = 0;
            return nullptr;
        }
    }

    /// Fire track-change triggers (MIDI/OSC/Art-Net DMX) for a TrackMap entry.
    /// Null-safe: does nothing if entry is nullptr or has no triggers.
    /// Art-Net DMX channel is bounds-checked to [1,512] before buffer access.
    void fireTrackTrigger(const TrackMapEntry* entry)
    {
        if (!entry || !entry->hasAnyTrigger()) return;

        triggerOutput.fire(*entry);

        if (artnetTriggerEnabled && entry->hasArtnetTrigger() && artnetOutput.getIsRunning())
        {
            int ch = entry->artnetCh;
            if (ch > 0 && ch <= 512)
            {
                trigDmxBuffer[ch - 1] = uint8_t(entry->artnetVal);
                if (ch > trigDmxHighWater) trigDmxHighWater = ch;
                artnetOutput.sendDmxFrame(trigDmxBuffer, trigDmxHighWater,
                                          artnetTriggerUniverse);
            }
        }
    }

    //--------------------------------------------------------------------------
    // Cue point management
    //--------------------------------------------------------------------------

    /// Load cue points from the TrackMap entry for a new track: a track
    /// change, including the first track seen after a deck switch or an
    /// input switch (called after fireTrackTrigger).  The list is armed
    /// against the playhead the next dispatch sees (dispatchTrackCues): the
    /// deck may already be anywhere in the track -- a deck switch in XF,
    /// MASTER or ON AIR, a track loaded at its memory cue -- and the cues
    /// behind it are passed, not fired (DESIGN D36).  Setting lastCueCheckMs
    /// to 0 here, as this did, fired every one of them on the next tick.
    /// The track already followed reloads through reloadCuePointsForTrack.
    void loadCuePointsForTrack(const TrackMapEntry* entry)
    {
        armedCues.clear();
        // The Generator and TrackMap cue paths share armedCues but only
        // one of them is active at any time.  Clear the Generator's raw
        // cache here so a later setFrameRate() can't rearm leftover
        // Generator cues on top of a TrackMap-driven session.
        rawGeneratorCues.clear();
        cueArmPending = true;

        if (!entry || entry->cuePoints.empty()) return;

        armedCues.reserve(entry->cuePoints.size());
        for (auto& cp : entry->cuePoints)
        {
            ArmedCue ac;
            ac.cue = cp;       // copy trigger data
            ac.fired = false;
            armedCues.push_back(std::move(ac));
        }
        // Guarantee sorted by position
        std::sort(armedCues.begin(), armedCues.end(),
                  [](const ArmedCue& a, const ArmedCue& b) {
                      return a.cue.positionMs < b.cue.positionMs;
                  });
    }

    /// Reload the cue list of the track already followed: the map edited
    /// (refreshTrackMapLookup), or the track's title or length resolved
    /// after its track change.  Once the list has been armed, the new list
    /// gets the flags the old one stood for (cueFlagsAtMs): the cues the deck
    /// has crossed or passed stay passed, and a cue the playhead crosses in
    /// the next tick fires.  Arming it at the next playhead, as a new track's
    /// list is, would pass that cue without firing it.  While the deck plays
    /// that position is the last playhead checked, a cue exactly on it
    /// included (it fired there); while the deck is paused it is where the
    /// deck stopped, not the paused reading, which on the NXS2 beat fallback
    /// is the beat-derived position (the start of the current beat with the
    /// rekordbox grid, of the next one without it), with the grid behind
    /// cues fired before the pause.  A list still waiting to be armed (its
    /// track change was this tick) keeps waiting.
    void reloadCuePointsForTrack(const TrackMapEntry* entry)
    {
        const bool wasArmed = ! cueArmPending;
        loadCuePointsForTrack(entry);
        if (! wasArmed) return;
        for (auto& ac : armedCues)
            ac.fired = ac.cue.positionMs < cueFlagsAtMs
                    || (cueFlagsAtIncl && ac.cue.positionMs == cueFlagsAtMs);
        cueArmPending = false;
    }

    /// Pass the cues behind `playheadMs` without firing them and take it as
    /// the last position checked (DESIGN D36).  `rearmAhead` also un-fires
    /// the cues at or ahead of it, as a seek does (DESIGN D17); without it a
    /// cue ahead keeps its flag, and the flags go on standing for the
    /// furthest of the two positions (cueFlagsAtMs).
    void armCuesAt(uint32_t playheadMs, bool rearmAhead)
    {
        for (auto& ac : armedCues)
            ac.fired = (ac.cue.positionMs < playheadMs) || (! rearmAhead && ac.fired);
        lastCueCheckMs = playheadMs;
        if (rearmAhead || playheadMs > cueFlagsAtMs)
        {
            cueFlagsAtMs   = playheadMs;
            cueFlagsAtIncl = false;
        }
    }

    /// TrackMap cue dispatch for the DJ sources and Winamp, once per tick
    /// (message thread).  `playheadMs` is the position the cues are checked
    /// against (interpolated between packets); `rawMs` is the source's own
    /// position, not interpolated: Pro DJ Link's absolute position, or on
    /// the NXS2 beat fallback the beat-derived position (the start of the
    /// current beat with the rekordbox grid, of the next one without it);
    /// StageLinQ's last BeatInfo position; for Winamp, playheadMs.  Cues
    /// fire only while the deck plays, when the playhead crosses them
    /// (tickCuePoints, with DESIGN D17's rule for a seek while playing; on
    /// the beat fallback a one-beat step is not a seek, see the caller).
    /// Whenever the list is armed against a playhead that is already
    /// somewhere, the cues behind it are passed without firing and only the
    /// ones crossed from then on fire (DESIGN D36, Joaky's answer to AUDIT
    /// Q9):
    ///   - a new track's list (track change, deck switch) is armed at the
    ///     first playhead seen after it; the track already followed reloads
    ///     with the flags it had (reloadCuePointsForTrack);
    ///   - while the deck does not play the playhead is followed and nothing
    ///     fires; at the next play the cues behind the playhead are passed
    ///     (what a scrub, jog or cue preview moved past).  The cues ahead are
    ///     re-armed too, as DESIGN D17 does for a seek while playing, when
    ///     the source reported a seek meanwhile (a hot cue or a relocation),
    ///     or when the deck moved back while it did not play: its own
    ///     position at play is more than kCueMovedBackMs behind the furthest
    ///     one it reached since it last played or the list was armed.  A jog
    ///     or scrub back raises no seek verdict.
    /// The move-back test compares the source's own positions, not the
    /// playhead: on the NXS2 beat fallback the playhead runs through the beat
    /// while the deck plays but reads the beat-derived position once it
    /// stops, with the grid up to a whole beat behind cues already fired,
    /// and taken for a move back that made them fire twice after a plain
    /// pause and play below 120 BPM.  On that fallback what the deck does
    /// within one beat while stopped is not seen: a jog back inside the
    /// beat keeps the flags.  A jog back into an earlier beat is seen from
    /// the player's next status on (no beat packet comes while the deck is
    /// stopped, and ProDJLinkInput refuses a lower status beat count only
    /// within 50 ms of one, AUDIT ENG-2).  On any
    /// source a step back of kCueMovedBackMs or less while the deck does not
    /// play keeps them (Winamp's position runs on up to one poll past a
    /// pause); while it plays, any step back is a seek (tickCuePoints).
    /// Before, the paused position was only followed: a relocation forward
    /// then play fired every cue in between at once, and one backward left
    /// the cues ahead marked fired (AUDIT ENG-2).
    void dispatchTrackCues(uint32_t playheadMs, uint32_t rawMs, bool playing, bool sourceSeeked)
    {
        if (cueArmPending)
        {
            armCuesAt(playheadMs, true);
            cueStopRawMs  = rawMs;
            cueArmPending = false;
            cueRelocated  = false;
        }
        if (! playing)
        {
            if (sourceSeeked) cueRelocated = true;
            cueStopRawMs   = juce::jmax(cueStopRawMs, rawMs);
            lastCueCheckMs = playheadMs;
            cueWasPlaying  = false;
            return;
        }
        if (! cueWasPlaying)
        {
            const bool movedBack = rawMs + kCueMovedBackMs < cueStopRawMs;
            armCuesAt(playheadMs, cueRelocated || movedBack);
            cueRelocated  = false;
            cueWasPlaying = true;
        }
        tickCuePoints(playheadMs, sourceSeeked);
        cueStopRawMs = rawMs;
    }

    /// Fire the cues crossed since the last call (forward playback, seek
    /// forward, seek backward).  `sourceSeeked` is the
    /// source estimator's own verdict (PlayheadPLL::seekDetected): it judges
    /// a jump against the position it predicted, so a source that only
    /// reports once per beat (NXS2 fallback: 500 ms at 120 BPM, more below)
    /// is not mistaken for a seek while it plays on.  The old rule here --
    /// any forward step over 500 ms -- did exactly that, and every cue
    /// behind the new position was marked fired without firing; below
    /// 120 BPM no TrackMap cue fired at all on that path.  The first beat
    /// after a play from a pause late in a beat can still exceed the PLL's
    /// 500 ms; the Pro DJ Link caller does not pass that one-beat step as a
    /// seek (AUDIT ENG-2).  A backward step is still a seek.
    void tickCuePoints(uint32_t playheadMs, bool sourceSeeked)
    {
        const bool seekDetected = sourceSeeked || (playheadMs < lastCueCheckMs);

        // After this call every cue up to this playhead is fired or passed,
        // so the flags stand for it, a cue exactly on it included -- also
        // with no list, so that a list loaded later for this track is armed
        // where the deck is (reloadCuePointsForTrack).  Without a seek they
        // go on standing for a position further on, where a play that did
        // not move back left them (dispatchTrackCues).
        if (seekDetected || playheadMs >= cueFlagsAtMs)
        {
            cueFlagsAtMs   = playheadMs;
            cueFlagsAtIncl = true;
        }
        if (armedCues.empty()) { lastCueCheckMs = playheadMs; return; }

        if (seekDetected)
        {
            // Reset fired flags: un-fire cues that are ahead of new playhead,
            // mark cues behind new playhead as already fired (don't re-trigger
            // cues we've passed)
            for (auto& ac : armedCues)
                ac.fired = (ac.cue.positionMs < playheadMs);
        }

        // Fire cues whose position the playhead has crossed
        for (auto& ac : armedCues)
        {
            if (ac.fired) continue;
            if (ac.cue.positionMs > playheadMs) break;  // sorted: no more to check

            // Playhead has crossed this cue -- fire it
            ac.fired = true;

            triggerOutput.fireCuePoint(ac.cue);

            // Art-Net DMX trigger (same pattern as track change triggers)
            if (artnetTriggerEnabled && ac.cue.hasArtnetTrigger() && artnetOutput.getIsRunning())
            {
                int ch = ac.cue.artnetCh;
                if (ch > 0 && ch <= 512)
                {
                    trigDmxBuffer[ch - 1] = uint8_t(ac.cue.artnetVal);
                    if (ch > trigDmxHighWater) trigDmxHighWater = ch;
                    artnetOutput.sendDmxFrame(trigDmxBuffer, trigDmxHighWater,
                                              artnetTriggerUniverse);
                }
            }

            DBG("TimecodeEngine: Cue fired '" + ac.cue.name + "' at "
                + CuePoint::formatPositionMs(ac.cue.positionMs)
                + " (playhead=" + CuePoint::formatPositionMs(playheadMs) + ")");
        }

        lastCueCheckMs = playheadMs;
    }

    /// Crossing-based cue dispatch for the Generator.
    ///
    /// Different semantics from tickCuePoints (which is the TrackMap path):
    /// here a cue fires every time the playhead is observed to advance
    /// across the cue position -- specifically when prevMs < cue <= nowMs.
    /// There is no `fired` flag and the order of cues is otherwise
    /// irrelevant; we just walk all armed cues and trigger those that
    /// fall in the (prev, now] half-open window.
    ///
    /// What this gets us:
    ///   - Seek backward and play forward -> cues are crossed again and fire
    ///     each time, which is the natural "rehearse this section again"
    ///     behaviour the user asked for.
    ///   - Seek to exactly a cue position and play -> the cue is NOT fired,
    ///     because the next tick advances *past* it without crossing into it
    ///     (the cue's positionMs equals the previous mark, which is excluded
    ///     by the strict-less comparison).
    ///   - The A/B loop wraps the TC back to loop In -> every iteration
    ///     re-fires the cues inside the loop region.  "Loop audio only"
    ///     does not: it loops the audio only, the TC keeps counting past
    ///     the file's end, so its cues fire on the first pass only.
    ///   - Backward jumps (seek back, stop+restart) just update prevMs
    ///     without firing anything; a loop wrap moves the cursor itself
    ///     (wrapGenerator).
    void tickCuePointsCrossing(uint32_t playheadMs)
    {
        if (armedCues.empty()) { lastCueCheckMs = playheadMs; cueCursorInclusive = false; return; }

        const uint32_t prevMs = lastCueCheckMs;

        // Backward jump: just take the new mark, don't fire anything.  This
        // covers seek-back and stop->start (which leaves genCurrentMs at
        // startMs, often less than where it was before); a loop wrap moves
        // the cursor back itself (wrapGenerator).  The inclusive flag
        // survives: it belongs to the transport event that set it, not to
        // this tick.  Standing still with the cursor inclusive is not a step
        // back: the cue exactly there fires now -- a wrap that landed in the
        // loop's first millisecond, or a start whose first tick has not
        // moved, fired it a tick late.
        if (playheadMs < prevMs || (playheadMs == prevMs && ! cueCursorInclusive))
        {
            lastCueCheckMs = playheadMs;
            return;
        }

        // Forward advance.  Fire any cue whose position is strictly greater
        // than where we were and at most where we are now -- except on the
        // first check after the transport started or a loop wrapped (the
        // wrap's own tick, wrapGenerator), where the cursor is inclusive so
        // that a cue placed exactly at the start TC (or at loop In) fires.
        // "At 00:00:00:00, go" is the obvious way to ask for something at
        // the top of a cue, and it used to fire never.
        const bool inclusive = cueCursorInclusive;
        cueCursorInclusive = false;
        for (auto& ac : armedCues)
        {
            const uint32_t pos = ac.cue.positionMs;
            if (inclusive ? (pos < prevMs) : (pos <= prevMs)) continue;  // already behind
            if (pos >  playheadMs) continue;  // still ahead; not crossed this tick

            triggerOutput.fireCuePoint(ac.cue);

            if (artnetTriggerEnabled && ac.cue.hasArtnetTrigger() && artnetOutput.getIsRunning())
            {
                int ch = ac.cue.artnetCh;
                if (ch > 0 && ch <= 512)
                {
                    trigDmxBuffer[ch - 1] = uint8_t(ac.cue.artnetVal);
                    if (ch > trigDmxHighWater) trigDmxHighWater = ch;
                    artnetOutput.sendDmxFrame(trigDmxBuffer, trigDmxHighWater,
                                              artnetTriggerUniverse);
                }
            }

            DBG("TimecodeEngine: Generator cue fired '" + ac.cue.name + "' at "
                + CuePoint::formatPositionMs(pos)
                + " (playhead=" + CuePoint::formatPositionMs(playheadMs) + ")");
        }

        lastCueCheckMs = playheadMs;
    }

    /// One wrap for the generator's loops (#24): the A/B loop, from
    /// loop Out back to loop In, and the timecode loop, from its end back to
    /// Start TC.  updateGenerator calls it, on the message thread, once
    /// genCurrentMs has reached endMs.  It
    ///  - fires the cues the tick crossed up to the end, (cursor, endMs], so
    ///    a cue in the last tick before the end, and one exactly at it, fire
    ///    on every pass (the end one just before the begin one).  Folding
    ///    first, as the A/B wrap did, made that window a step back, where
    ///    tickCuePointsCrossing fires nothing;
    ///  - folds the position back keeping what the tick ran past the end,
    ///    beginMs + fmod(genCurrentMs - beginMs, endMs - beginMs): a pass
    ///    lasts exactly endMs - beginMs (the A/B wrap dropped the excess,
    ///    up to a tick per pass);
    ///  - leaves the cue cursor at beginMs, inclusive, so the tick's own
    ///    tickCuePointsCrossing fires the cues in [beginMs, position] -- the
    ///    begin cue in the wrap's tick, not a tick later;
    ///  - seeks the audio to the new position (audio = timecode - Start
    ///    TC, as every generator seek) when seekAudio: the A/B loop, and the
    ///    timecode loop's seek path.  On its gapless path the player has
    ///    looped the file itself, and the fold by exactly the file's length
    ///    keeps the timecode where the audio is;
    ///  - has the outputs told, as for a seek (genJumpAnnounce).
    /// A position within kGenLoopEndEpsMs below a multiple of the length
    /// folds to the beginning, as it counts as the end (kGenLoopEndEpsMs).
    /// A tick longer than a whole pass (the message thread stalled) fires
    /// the cues the old pass had left up to the end, then those of the new
    /// pass up to where it lands: a cue in both stretches fires twice in
    /// that tick, once for each pass, never twice in one pass (DESIGN
    /// D36), and the passes the tick skipped whole fire nothing.
    ///
    /// When the cursor was already at or past the end, nothing was played
    /// up to it: a seek past the end, an end moved behind the playhead, the
    /// A/B loop armed with the playhead past Out.  No cue fires up to the
    /// end then, and where the position lands is jumpToBegin's:
    ///  - true, the A/B loop: on beginMs, the cursor there and inclusive, so
    ///    In's cue fires -- what the A/B loop did there before #24, what a
    ///    CDJ's reloop does, and where Play from Stopped starts;
    ///  - false, the timecode loop: folded, beginMs + fmod(position -
    ///    beginMs, length), the cursor folded with it, so the cues the jump
    ///    passed do not fire, as for a seek forward.  On the gapless path
    ///    that is also where seekSeconds() put the looping audio.
    void wrapGenerator(double beginMs, double endMs, bool seekAudio, bool jumpToBegin)
    {
        const double lenMs = endMs - beginMs;
        if (lenMs <= 0.0)
            return;

        const auto fold = [beginMs, lenMs](double ms)
        {
            const double inLoopMs = std::fmod(ms - beginMs, lenMs);
            return beginMs + (inLoopMs > lenMs - kGenLoopEndEpsMs ? 0.0 : inLoopMs);
        };
        const double cursorMs = (double) lastCueCheckMs;
        if (cursorMs < endMs)
        {
            tickCuePointsCrossing((uint32_t) juce::jmax(0.0, endMs));
            genCurrentMs = fold(genCurrentMs);
            lastCueCheckMs = (uint32_t) juce::jmax(0.0, beginMs);
            cueCursorInclusive = true;
        }
        else if (jumpToBegin)
        {
            genCurrentMs = beginMs;
            lastCueCheckMs = (uint32_t) juce::jmax(0.0, beginMs);
            cueCursorInclusive = true;
        }
        else
        {
            genCurrentMs = fold(genCurrentMs);
            lastCueCheckMs = (uint32_t) juce::jmax(0.0, fold(cursorMs));
            cueCursorInclusive = false;
        }
        retargetGeneratorAudioLastPass();

        if (seekAudio)
            generatorAudioPlayer.seekSeconds(juce::jmax(0.0, (genCurrentMs - genStartMs) / 1000.0));

        genJumpAnnounce = true;
    }

    /// A loop wraps from this close below its end, so the end frame is
    /// never published.  Within 1e-9 of a frame below a boundary (4.2e-8 ms
    /// at most) wallClockToTimecode already reads the next frame, here the
    /// end's, and a timer in step with the loop lands a few dozen ulps
    /// short of the end, by the rounding of its sums; the margin covers
    /// both.  Further below, up to the margin, a position still reads the
    /// frame before, and the loop wraps there at most 1 ns early.  A tick
    /// landing this close to the end is rare with a real timer, and did
    /// happen with one exactly in step with the loop (loop_tc_sim, group
    /// S).
    static constexpr double kGenLoopEndEpsMs = 1e-6;

    /// The timecode loop's end (#24), when it acts: endMs (exclusive, ms
    /// from midnight) and whether it goes round gapless.  The file's end
    /// counts only with a file loaded and no load pending (the length may
    /// still be the previous file's); a Stop TC less than a frame before it,
    /// or past it, is that end, gapless.  Otherwise Stop TC, by seek: also
    /// a Stop TC exactly a frame before the file's end -- the file's last
    /// frame, when the file is a whole number of frames long -- which the
    /// loop then leaves out, as it leaves out every Stop TC frame
    /// (kGenLoopEndEpsMs keeps the rounding of the two sums from deciding
    /// that case at 29.97 and 23.976).  False with the flag off, with no
    /// end, or with a loop shorter than kMinLoopTimecodeMs (Stop TC at or
    /// before Start TC included).  evenWhileLoading counts the loaded
    /// file's end while a load is pending too; only PLAY asks for it
    /// (generatorPlay).  Message thread.
    bool loopTimecodeEnd(double& endMs, bool& gapless, bool evenWhileLoading = false) const
    {
        endMs = 0.0;
        gapless = false;
        if (! genLoopTimecode)
            return false;

        double fileEndMs = 0.0;
        if (generatorAudioPlayer.hasFileLoaded() && (evenWhileLoading || ! generatorAudioPlayer.isLoadPending()))
        {
            const double lenSec = generatorAudioPlayer.getFileLengthSeconds();
            if (lenSec > 0.0)
                fileEndMs = genStartMs + lenSec * 1000.0;
        }

        const double frameMs = 1000.0 / frameRateToDouble(currentFps);
        if (fileEndMs > 0.0 && (genStopMs <= 0.0 || genStopMs > fileEndMs - frameMs + kGenLoopEndEpsMs))
        {
            endMs = fileEndMs;
            gapless = true;
        }
        else if (genStopMs > 0.0)
            endMs = genStopMs;
        else
            return false;

        if (endMs - genStartMs < kMinLoopTimecodeMs)
        {
            endMs = 0.0;
            gapless = false;
            return false;
        }
        return true;
    }

    /// Seek the audio to where the timecode is in the timecode loop (#24),
    /// after Start TC or the path has changed under a running loop
    /// (setGeneratorStartMs, setGeneratorStopMs, setGeneratorLoopFlags):
    /// (timecode - Start TC) folded into [0, endMs - Start TC), the place a
    /// wrap would give it.  setGeneratorLoopFlags also brings the audio to
    /// its place under Loop audio this way, with endMs Start TC + the
    /// file's length and gapless, for a timecode at or past Start TC.
    /// Below Start TC -- a Start TC moved past the timecode, which first
    /// runs up to it, outside the loop, as in 1.9.14 -- the gapless path
    /// folds too, the player looping from the file's tail into its top as
    /// the timecode reaches Start TC; the seek path, whose player does not
    /// loop, puts the audio at the file's top, as every seek there does
    /// (audio = timecode - Start TC, not below 0), ahead of the timecode by
    /// what is left to Start TC until DESIGN D18 pulls the two together
    /// (under a second) or the next wrap does.  onlyIfOutOfStep leaves
    /// audio within kGenAudioInStepMs of that place where it is: sought to
    /// it, audio in step would skip or repeat the few ms the two differ
    /// by.  endMs and gapless are loopTimecodeEnd's.  Message thread.
    void seekGeneratorAudioIntoLoop(double endMs, bool gapless, bool onlyIfOutOfStep = false)
    {
        const double lenMs = endMs - genStartMs;
        if (lenMs <= 0.0)
            return;
        double inLoopMs = std::fmod(genCurrentMs - genStartMs, lenMs);
        if (inLoopMs < 0.0)
            inLoopMs = gapless ? inLoopMs + lenMs : 0.0;
        if (onlyIfOutOfStep)
        {
            const double audioMs = generatorAudioPlayer.getCurrentPositionSeconds() * 1000.0;
            const double offMs = gapless ? std::remainder(audioMs - inLoopMs, lenMs) : audioMs - inLoopMs;
            if (std::abs(offMs) <= kGenAudioInStepMs)
                return;
        }
        generatorAudioPlayer.seekSeconds(inLoopMs / 1000.0);
    }

    /// How far the player's position may read from where the timecode puts
    /// the audio and still count as in step (seekGeneratorAudioIntoLoop).
    /// It moves a device block at a time, and the timecode is where the
    /// last tick left it, so audio in step reads up to about a tick plus
    /// half a block from there, around DESIGN D18's few ms: some 65 ms with
    /// blocks of 4096 samples at 44.1 kHz, 17-19 ms with 480 at 48 kHz.
    /// That holds for blocks of up to about 4096 samples.  With 8192, the
    /// largest BUFFER SIZE offered, audio in step can read up to about
    /// 115 ms off (106-114 ms measured at 48 kHz), and a switch that has
    /// the player loop the file then seeks it: a skip or repeat of about
    /// that much, in about one switch in twelve.
    static constexpr double kGenAudioInStepMs = 100.0;

    /// Seek the audio to where the timecode puts it, for a seek of the
    /// generator (setGeneratorPosition: a click on the waveform, an OSC jog),
    /// the load completion's catch-up (onLoadCompleted) and the audio
    /// output's (re)opening (resyncGeneratorAudioToTimecode): timecode -
    /// Start TC, which the player folds into the file while it loops the
    /// file and holds at 0 below its top.  On the timecode loop's gapless
    /// path a timecode before Start TC -- an OSC jog there, or the timecode
    /// running up to a later Start TC -- is folded into the loop instead,
    /// as a Start TC change folds it (seekGeneratorAudioIntoLoop): the audio
    /// plays the file's tail and goes round into its top as the timecode
    /// reaches Start TC (#24).  Held at the top, the audio ran ahead of the
    /// timecode by what was left to Start TC, and DESIGN D18, which compares
    /// the two modulo the file's length there, pulled the timecode forwards
    /// when that was under a second, backwards when it was within a second
    /// of the file's length (the nearer relation then lying across the
    /// fold), up to 20 ms a tick, and left the two apart for good in
    /// between.  At or past Start TC the
    /// player's own fold gives the same place, and the seek is made as
    /// before.  While a load is pending the player ignores the seek, and
    /// the completion's catch-up comes back here.  Message thread.
    void seekGeneratorAudioToTimecode()
    {
        double loopEndMs = 0.0;
        bool loopGapless = false;
        if (genCurrentMs < genStartMs && loopTimecodeEnd(loopEndMs, loopGapless) && loopGapless)
            seekGeneratorAudioIntoLoop(loopEndMs, true);
        else
            generatorAudioPlayer.seekSeconds(juce::jmax(0.0, (genCurrentMs - genStartMs) / 1000.0));
    }

    /// Whether the generator follows the armed A/B loop (#24).  With the
    /// timecode loop, only an A/B inside it -- In at or after Start TC, Out
    /// at or before the loop's end, and on its gapless path more than a
    /// tick (kGenLoopTickMs) before the file's end, as the fold, or the
    /// player's own loop, gets there before the A/B's seek.  Without it,
    /// an A/B the generator can reach: In before, and Out at or before,
    /// where it stops (generatorStopEndMs) -- at the end of a file the
    /// player does not loop, or at a Stop TC.  An A/B set under "Loop audio
    /// only" from its second pass on lies past the file's end, where the
    /// timecode counts on; with Loop audio off it was followed all the same,
    /// so GO or PLAY started at its In, past the file's end, and the file's
    /// end stopped the generator at once (Joaky's case, an A/B left on one
    /// preset and called from another with the same file).  Any other A/B
    /// is ignored: the tick does not wrap at its Out, and PLAY from Stopped
    /// starts at Start TC, not at its In.  The three arguments are
    /// loopTimecodeEnd's.  Message thread.
    bool generatorAbLoopFollowed(bool loopTimecode, double loopEndMs, bool loopGapless) const
    {
        if (! isGeneratorLoopActive())
            return false;
        if (! loopTimecode)
        {
            const double stopEndMs = generatorStopEndMs();
            return stopEndMs <= 0.0 || (genLoopInMs < stopEndMs && genLoopOutMs <= stopEndMs);
        }
        const double outLimitMs = loopGapless ? loopEndMs - kGenLoopTickMs : loopEndMs;
        return genLoopInMs >= genStartMs && genLoopOutMs <= outLimitMs;
    }

    /// Where the generator stops without the timecode loop, in ms from
    /// midnight, or 0 where nothing stops it (#24): the earlier of a Stop TC
    /// and the file's end -- Start TC + the length of the file the player
    /// holds, also while a load is pending, as the tick then takes it; the
    /// end of Loop audio's last pass after it is turned off live from its
    /// second pass on.  The file's end does not count under "Loop audio
    /// only", with no file, or while a load is pending with either loop
    /// option on (updateGenerator).  For generatorAbLoopFollowed.  Message
    /// thread.
    double generatorStopEndMs() const
    {
        double endMs = 0.0;
        if (genAudioLoopLastPassEndMs > 0.0)
            endMs = genAudioLoopLastPassEndMs;
        else if (! genAudioLoop && generatorAudioPlayer.hasFileLoaded()
                 && ! (genLoopTimecode && generatorAudioPlayer.isLoadPending())
                 && generatorAudioPlayer.getFileLengthSeconds() > 0.0)
            endMs = genStartMs + generatorAudioPlayer.getFileLengthSeconds() * 1000.0;
        if (genStopMs > 0.0)
            endMs = endMs > 0.0 ? juce::jmin(endMs, genStopMs) : genStopMs;
        return endMs;
    }

    /// Where Loop audio's last pass ends when it is turned off live
    /// (setGeneratorLoopFlags): the end of the pass the timecode is in,
    /// Start TC + a whole number of file lengths, from the second pass on.
    /// 0 -- the file's end stops the generator, as without the option -- in
    /// the first pass or before Start TC, with no file, or while a load is
    /// pending (the length may still be the previous file's).  Message
    /// thread.
    double generatorAudioLastPassEndMs() const
    {
        if (! generatorAudioPlayer.hasFileLoaded() || generatorAudioPlayer.isLoadPending())
            return 0.0;
        const double lenMs = generatorAudioPlayer.getFileLengthSeconds() * 1000.0;
        const double relMs = genCurrentMs - genStartMs;
        if (lenMs <= 0.0 || relMs < lenMs)
            return 0.0;
        return genStartMs + (std::floor(relMs / lenMs) + 1.0) * lenMs;
    }

    /// Loop audio's last pass under way (genAudioLoopLastPassEndMs) and the
    /// timecode moved -- a seek, an A/B wrap, a Start TC change: the last
    /// pass is the one the timecode is in now.  Moved into the first pass
    /// or before Start TC, there is none: the file's end stops the
    /// generator, as without the option, and the player stops looping at
    /// the next tick (syncGeneratorPlayerLooping) -- unless the audio is
    /// then a whole pass ahead of the timecode and in step with it, as
    /// after a jog to about a whole number of file lengths before Start
    /// TC, when the loop is held until the audio goes round.  Message
    /// thread.
    void retargetGeneratorAudioLastPass()
    {
        if (genAudioLoopLastPassEndMs > 0.0)
            genAudioLoopLastPassEndMs = generatorAudioLastPassEndMs();
    }

    /// Bring the player's own loop in line (#24): on for the timecode loop's
    /// gapless path, off for its seek path and when it does not act, "Loop
    /// audio file when it ends" when the flag is off -- on also for the
    /// last pass after Loop audio is turned off live, until it ends
    /// (genAudioLoopLastPassEndMs).  Called by the setters that move the
    /// loop or switch the flags, the load's completion and every tick (a
    /// frame rate change moves the "last frame" threshold; a last pass
    /// ends); it calls the player only when the player's loop differs from
    /// the one wanted.  Not while a load is pending: the request in flight
    /// carries the flag, and the completion comes back here.
    ///
    /// Switching off is held while the audio is still finishing the
    /// previous pass: more than half the file ahead of the timecode's place
    /// (timecode - Start TC) and in step with it modulo the file's length,
    /// within kGenPlayerLoopHoldMs.  Off there, the audio would stop at the
    /// file's end and the timecode run its pass in silence.  That is the
    /// timecode loop turned off on its gapless path, or no longer acting
    /// there, in the tick or two in which the timecode has folded and the
    /// audio has not yet (the two go round a few ms apart, DESIGN D18), or
    /// with the timecode before Start TC and the audio in the file's tail,
    /// where the loop folds it (seekGeneratorAudioIntoLoop), until the
    /// audio goes round at Start TC, up to a file's length later; and "Loop
    /// audio" turned off in its first pass or before Start TC with the
    /// audio so.  The test is made when the switch comes, and at every
    /// tick after it (generatorAudioPassAheadInStep), on where the audio is
    /// then.  A jog before Start TC under "Loop audio" (the audio then at
    /// the file's top), or a Start TC moved later, leaves the audio ahead
    /// of the timecode and in general out of step, and DESIGN D18,
    /// comparing modulo the length in Loop audio's first pass too, brings a
    /// remainder under a second into step in the second or two after it: a
    /// switch then is held and the pass plays in step, as is one soon after
    /// a jog of about a whole number of file lengths.  Once the audio has
    /// gone round, both are in the same pass.  While the loop is held, a
    /// Start TC change folds the audio again, so it stays a whole pass
    /// ahead and in step (setGeneratorStartMs).  Audio ahead but not in
    /// step when the switch comes -- soon after such a jog or Start TC
    /// change, before D18 has pulled the two in, or with a remainder of a
    /// second or more, which D18 leaves -- is not held: the player stops
    /// looping at once, and the file plays to its end and stops there, as
    /// without the option, D18 comparing the two as they are.  (Held, as it
    /// was, it went round and played the file again from its top until the
    /// generator stopped, while D18, comparing modulo the length, could
    /// pull the timecode, and the outputs with it, backwards.)  Within a
    /// device block and a tick of kGenPlayerLoopHoldMs, a loop held at the
    /// switch can be let go at a later tick, before the audio has gone
    /// round, as the position read moves a block at a time: the pass then
    /// ends silent, as without the option.  The other way round -- the
    /// audio gone round a few ms before the timecode -- is not held, as
    /// the timecode no longer folds once the flag is off: the audio the
    /// device has taken from the file's top, and takes until the next tick
    /// stops the generator at the pass's end, sounds before that stop cuts
    /// it -- about one device block, or one tick with small blocks.
    /// Message thread.
    void syncGeneratorPlayerLooping()
    {
        if (generatorAudioPlayer.isLoadPending())
            return;

        const bool want = generatorPlayerLoopWanted();
        if (want == generatorAudioPlayer.isLooping())
            return;
        if (! want && generatorAudioPassAheadInStep())
            return;   // the audio is still finishing the previous pass
        generatorAudioPlayer.setLoopingWhilePlaying(want);
    }

    /// How far, modulo the file's length, audio more than half the file
    /// ahead of the timecode's place may read from it and still count as a
    /// whole pass ahead and in step (syncGeneratorPlayerLooping's hold).
    /// Wider than kGenAudioInStepMs, as the costs differ: audio in step not
    /// held stops at the file's end and leaves a pass silent, while audio
    /// held a little out of step is pulled in by DESIGN D18, by about 2 %
    /// of this (5 ms) a tick at most -- 5.3 ms measured, as the hold reads
    /// the remainder before the tick moves the timecode, and D18 up to a
    /// tick later.  Audio in step, held with the timecode before Start TC,
    /// read up to 25.9 ms from it with device blocks of 480 samples, 64.2 ms
    /// with 4096 and 151.2 ms with 8192, the largest BUFFER SIZE offered
    /// (the timecode loop turned off on its gapless path after a jog or a
    /// later Start TC, a Start TC change during the hold, "Loop audio"
    /// turned off after a jog of one file length).  Near the edge the
    /// position read, a block at a time, can cross it at a later tick and
    /// let the hold go.  With a file of 0.5 s or less every remainder is
    /// within it, and the hold is the half-file rule alone.
    static constexpr double kGenPlayerLoopHoldMs = 250.0;

    /// The player's own loop as the options want it, the hold aside
    /// (syncGeneratorPlayerLooping): on for the timecode loop's gapless
    /// path; with the timecode loop off, on for "Loop audio only" and for
    /// its last pass after it is turned off live.  Message thread.
    bool generatorPlayerLoopWanted() const
    {
        double endMs = 0.0;
        bool gapless = false;
        const bool loopActive = loopTimecodeEnd(endMs, gapless);
        return genLoopTimecode ? (loopActive && gapless)
                               : (genAudioLoop || genAudioLoopLastPassEndMs > 0.0);
    }

    /// The hold's test (syncGeneratorPlayerLooping): playing or paused with
    /// a file loaded, the audio more than half the file ahead of the
    /// timecode's place (timecode - Start TC) and within
    /// kGenPlayerLoopHoldMs of a whole number of file lengths ahead -- a
    /// whole pass ahead and in step, still finishing the previous pass.
    /// The position reads folded into the file while the player loops.
    /// Message thread.
    bool generatorAudioPassAheadInStep() const
    {
        if (genState == GeneratorState::Stopped || ! generatorAudioPlayer.hasFileLoaded())
            return false;
        const double lenMs   = generatorAudioPlayer.getFileLengthSeconds() * 1000.0;
        const double audioMs = generatorAudioPlayer.getCurrentPositionSeconds() * 1000.0;
        const double aheadMs = audioMs - (genCurrentMs - genStartMs);
        return lenMs > 0.0 && aheadMs > lenMs / 2.0
            && std::abs(std::remainder(aheadMs, lenMs)) <= kGenPlayerLoopHoldMs;
    }

    /// True when syncGeneratorPlayerLooping holds the player's loop, or
    /// would at its next call: no load pending, the player loops the file
    /// though the options no longer want it to, and the audio is a whole
    /// pass ahead and in step (generatorAudioPassAheadInStep).  Message
    /// thread.
    bool generatorPlayerLoopHeld() const
    {
        return ! generatorAudioPlayer.isLoadPending() && generatorAudioPlayer.isLooping()
            && ! generatorPlayerLoopWanted() && generatorAudioPassAheadInStep();
    }

    //--------------------------------------------------------------------------
    void updateGenerator()
    {
        // Clock mode: time of day.  The wall clock says WHAT time it is but
        // moves in system-timer steps (up to 15.6 ms on Windows); the
        // high-resolution counter is smooth but is a different oscillator,
        // tens of ppm away.  This used to run on the counter and re-anchor to
        // the wall clock whenever they disagreed by 50 ms -- a 50 ms jump on
        // every output, a skipped frame at 25 fps, every time the two drifted
        // that far apart (@mungewell: every 46 minutes).  The follower pulls
        // towards the wall clock continuously instead, and only jumps for a
        // disagreement of more than a second: the clock being set, a resume,
        // midnight (DESIGN D31).
        if (genClockMode)
        {
            auto now = juce::Time::getCurrentTime();
            const double wallMs = (double)now.getHours() * 3600000.0
                                + (double)now.getMinutes() * 60000.0
                                + (double)now.getSeconds() * 1000.0
                                + (double)now.getMilliseconds();
            const double msSinceMidnight =
                clockFollower.update(wallMs, juce::Time::getMillisecondCounterHiRes());
            currentTimecode = wallClockToTimecode(msSinceMidnight, currentFps);
            setFramePhaseFromPosition(msSinceMidnight, currentFps);
            return;
        }

        // Generator mode: transport-controlled.  The player's own loop
        // follows the timecode loop (#24); a no-op unless it changed.
        syncGeneratorPlayerLooping();
        if (genState == GeneratorState::Playing)
        {
            double now = juce::Time::getMillisecondCounterHiRes();
            double delta = now - genLastTickTime;
            genLastTickTime = now;
            if (delta > 0.0)
                genCurrentMs += delta;

            // Audio clock discipline.  The timecode above advances on the
            // system clock; a loaded file plays on the audio device's clock,
            // and the two differ by tens of ppm -- 70-360 ms an hour between
            // the sound the audience hears and the LTC the lights and video
            // chase.  While the file is playing, pull the timecode gently
            // towards the transport position (audio position = timecode -
            // start TC, the same relation every seek here uses).  The
            // transport position moves in audio-block steps, so a slow
            // first-order pull (tau ~ 0.8 s at 60 Hz) keeps the timecode
            // smooth.  A discrepancy of a second or more is not drift but a
            // loop fold, a seek in flight, or a transport stopped at EOF:
            // leave it to the code that handles those.  Not while a file
            // load is pending: the transport still holds the file being
            // replaced and no longer moves (the audio callback plays
            // silence), so following it pulled the timecode back for up to
            // 200 ms -- ~25 ms late after a preset change from a slow disk
            // during playback (AUDIT LTC-4); the load's onLoadCompleted
            // seek brings the new file to the timecode.
            //
            // The timecode loop (#24) is worked out first.  While the player
            // loops the file and the timecode loop is not on its seek path,
            // the two are compared modulo the file's length, as the audio
            // goes round at the file's end on its own:
            //  - on the timecode loop's gapless path the timecode folds by
            //    exactly that length, at its own instant -- each fold would
            //    otherwise read as an error of a whole pass and switch this
            //    off;
            //  - with "Loop audio only" (the player loops the
            //    file, the timecode loop does not act) the timecode never
            //    folds: it counts on past the file's end, a whole number of
            //    file lengths after the audio's place from the second pass
            //    on.  Compared as they were, that read as an error of a pass
            //    or more and switched this off after the first pass: the
            //    timecode ran on the system clock and drifted from the audio
            //    by the device's clock error (0.2-0.4 s an hour at 50-100
            //    ppm), and with a file of about a second or less a pass read
            //    as drift and held the timecode back, up to 20 ms a tick --
            //    with one of about 0.3 s or less for good, 0.8-1.0 s past
            //    Start TC.  Modulo the length the timecode follows the audio
            //    device's clock in every pass, as in the first, and counts at
            //    that clock's rate for the whole run, with a file longer than
            //    about two device blocks.  With a shorter file the position
            //    read here, up to a block old, can alias modulo the length:
            //    the timecode still settles at its usual offset from the
            //    audio modulo the length, but may slide there over tens of
            //    seconds, by up to a whole file length, at up to about 2 ms a
            //    tick and without a jump.  A file of a block or less is in
            //    effect not corrected (one whose length divides the block
            //    leaves the position read unchanged, so the stall guard
            //    below keeps this off): the timecode runs on the system
            //    clock;
            //  - the same while the player's loop is held, the audio a whole
            //    pass ahead of the timecode and in step with it, until the
            //    audio has gone round (syncGeneratorPlayerLooping): after the
            //    timecode loop is turned off on its gapless path or no longer
            //    acts there (e.g. a Stop TC set less than kMinLoopTimecodeMs
            //    after Start TC), a tick or few at its seam and up to a file
            //    length with the timecode before Start TC, and after "Loop
            //    audio" is turned off before Start TC with the audio so --
            //    which, after a jog there or a later Start TC, it is once the
            //    first-pass comparison below has pulled a remainder under a
            //    second in, a second or two later, or at once after a jog of
            //    about a whole number of file lengths; within about
            //    kGenPlayerLoopHoldMs of in step (the hold reads it before
            //    the tick moves the timecode, this up to a tick later), so a
            //    pull of about 5 ms a tick at most (5.3 measured).  Audio not
            //    in step when the switch comes is not held: the player stops
            //    looping and the two are compared as they are, as without
            //    the option.  And in the last pass after "Loop audio" is
            //    turned off live from its second pass on, which the player
            //    loops to its end (genAudioLoopLastPassEndMs).
            // On the seek path they are compared as they are, also in the
            // ticks in which the player's loop is still held that way after
            // a Stop TC set at the seam has moved the loop there: with a
            // file little more than a second long and large device blocks,
            // such a tick can pull the timecode forward by up to 20 ms.
            // The remainder lies within half the file's length, so the pull
            // is at most 1 % of that length a tick (and 20 ms, with the
            // second's limit above), never a whole file.  Under Loop audio
            // the comparison is modulo the length from the start, the first
            // pass included: an error of more than half the file's length
            // -- Start TC moved while the file plays, a jog to before Start
            // TC, a device stall -- is pulled, when the remainder is under
            // the second, to the nearest relation modulo the length, which
            // can be the other way round to the unfolded difference, and
            // without waiting for the audio to go round.  Not while a load is
            // pending (above): the length is the loaded file's.
            double loopEndMs = 0.0;
            bool loopGapless = false;
            const bool loopTimecode = loopTimecodeEnd(loopEndMs, loopGapless);
            if (generatorAudioPlayer.hasFileLoaded() && generatorAudioPlayer.isPlaying()
                && ! generatorAudioPlayer.isLoadPending())
            {
                const double audioMs = genStartMs + generatorAudioPlayer.getCurrentPositionSeconds() * 1000.0;
                // Only follow a clock that is running: a device that has
                // stalled leaves the position frozen, and following it would
                // drag the timecode to a halt.
                if (audioMs != genLastAudioMs) { genLastAudioMs = audioMs; genLastAudioMoveTs = now; }
                double err = audioMs - genCurrentMs;
                if (loopTimecode && loopGapless)
                    err = std::remainder(err, loopEndMs - genStartMs);
                else if (! loopTimecode && generatorAudioPlayer.isLooping())
                    err = std::remainder(err, generatorAudioPlayer.getFileLengthSeconds() * 1000.0);
                if (std::abs(err) < 1000.0 && (now - genLastAudioMoveTs) < 200.0)
                    genCurrentMs += err * 0.02;
            }

            // A/B loop: when active and we reach loopOutMs, wrap back to
            // loopInMs (wrapGenerator: the cues up to Out fire, the position
            // folds keeping what the tick ran past Out, the cues from In fire
            // in this tick, the audio seeks, the outputs are told; a jump
            // past Out, such as A/B LOOP armed there, lands on In).  Checked
            // BEFORE stop TC and EOF -- if both the stop TC and the loop Out
            // fall in the same tick, the loop wins (the user explicitly armed
            // the loop).  ("Loop audio only" has no such wrap:
            // the TC never goes back, see the EOF branch below.)
            //
            // Then the timecode loop (#24): at its end, back to Start TC
            // instead of stopping (wrapGenerator), by seek or, on the gapless
            // path, by folding the timecode while the player loops the file.
            // An armed A/B inside the timecode loop wins; one not inside it
            // is ignored (generatorAbLoopFollowed): on the gapless path an
            // Out at the file's end or past it is never reached before the
            // fold, and within a tick of it the player has looped before
            // the A/B's seek.  Without the timecode loop, one past where the
            // generator stops -- the end of a file the player does not loop,
            // a Stop TC -- is ignored too.
            const bool abLoop = generatorAbLoopFollowed(loopTimecode, loopEndMs, loopGapless);
            if (abLoop && genCurrentMs >= genLoopOutMs - kGenLoopEndEpsMs)
                wrapGenerator(genLoopInMs, genLoopOutMs, true, true);
            else if (loopTimecode && genCurrentMs >= loopEndMs - kGenLoopEndEpsMs)
                wrapGenerator(genStartMs, loopEndMs, ! loopGapless, false);

            // Auto-stop at stop TC (if set and not zero) -- not while the
            // timecode loop acts: it goes round there instead.
            if (! loopTimecode && genStopMs > 0.0 && genCurrentMs >= genStopMs)
            {
                genCurrentMs = genStopMs;
                genState = GeneratorState::Stopped;
                genAudioLoopLastPassEndMs = 0.0;
                generatorAudioPlayer.stopAndReset();
            }
            // Auto-stop when the loaded audio file has played to its end.
            // Without this, the SMPTE would keep advancing past the file's
            // last sample (the audio transport silently auto-stops at EOF
            // but nothing was relaying that back to the generator state).
            // With "Loop audio only" this branch is skipped
            // (isLooping): the player loops the audio, and the TC keeps
            // counting past the file's end -- until Stop TC, or for ever
            // without one.  Nothing here folds genCurrentMs; only a seek is
            // folded into the file (seekSeconds).  A user-defined stop TC
            // takes precedence (handled by the prior branch).
            //
            // genEndedAtEof is set so that a subsequent click on the
            // waveform timeline (setGeneratorPosition) treats the seek
            // as a "resume from new position" gesture instead of just
            // cueing.  See setGeneratorPosition for the consumer side.
            //
            // Not while the timecode loop acts either.  And with "Loop
            // timecode" or "Loop audio" on while a file load is pending, the
            // file's end is not evaluated at all (the length may still be
            // the previous file's): the timecode loop does not count it yet
            // (loopTimecodeEnd), and neither does this stop.  The player's
            // loop is then the request's until the load completes
            // (syncGeneratorPlayerLooping), so "Loop audio" switched on live
            // during the load (setGeneratorLoopFlags) would otherwise let
            // the previous file's end stop the generator.
            //
            // "Loop audio" turned off live from its second pass on: the
            // player loops on to the end of the pass the timecode is in,
            // and the generator stops there as at the file's end
            // (genAudioLoopLastPassEndMs, setGeneratorLoopFlags).
            else if (! loopTimecode && ! ((genLoopTimecode || genAudioLoop) && generatorAudioPlayer.isLoadPending()))
            {
                const double fileLenSec = generatorAudioPlayer.getFileLengthSeconds();
                const bool lastPass = genAudioLoopLastPassEndMs > 0.0;
                if (fileLenSec > 0.0 && (lastPass || ! generatorAudioPlayer.isLooping()))
                {
                    const double endMs = lastPass ? genAudioLoopLastPassEndMs
                                                  : genStartMs + fileLenSec * 1000.0;
                    if (genCurrentMs >= endMs)
                    {
                        genCurrentMs = endMs;
                        genState = GeneratorState::Stopped;
                        genEndedAtEof = true;
                        genAudioLoopLastPassEndMs = 0.0;
                        generatorAudioPlayer.stopAndReset();
                    }
                }
            }

            // Check armed cue points against the current generated TC.
            // Uses the crossing-based variant: a cue fires whenever the
            // generated TC advances across its position in play.  Seeking
            // backwards and playing forward will re-fire cues, and the A/B
            // loop re-fires them every iteration ("Loop audio only" does
            // not: the TC does not go back) -- which is what the Generator's
            // transport-mode UX wants (vs. the TrackMap path where each cue
            // fires at most once per track to match how a CDJ scratch / jog
            // should behave).
            tickCuePointsCrossing((uint32_t) juce::jmax(0.0, genCurrentMs));
        }
        // Stopped and Paused: genCurrentMs stays where it is
        currentTimecode = wallClockToTimecode(genCurrentMs, currentFps);
        setFramePhaseFromPosition(genCurrentMs, currentFps);
    }

    //--------------------------------------------------------------------------
    // The generator's parked locate (#24).  While the generator (transport
    // mode) is paused or stopped its outputs are paused, and a position
    // changed then -- STOP after PAUSE, or after a stop at Stop TC or at the
    // file's end; Start TC changed while stopped (panel, OSC /start, a
    // preset browsed); a click or drag on the waveform; an OSC jog -- reached
    // only the display and TCNet.  It goes out as an MTC source's locate
    // while stopped does (forwardParkedLocate, AUDIT LTC-13): an MTC Full
    // Frame, one Art-Net and one LA-Net frame, the outputs staying paused.
    //
    // A trailing debounce: the generator functions mark each change
    // (markGeneratorParkedLocate) and the tick passes the position on once
    // it has not changed for kGenParkedSettleMs, and only if the outputs
    // would get another frame than they were last given, at the output rate
    // (updateGeneratorParkedLocate).  A drag on the waveform seeks on every
    // mouse event and an OSC jog stream on every message; told each time,
    // the outputs would get a Full Frame and an Art-Net frame per event, a
    // stream of changing positions a receiver can take for running
    // timecode.  Told once it rests, a gesture gives one locate, where it
    // ends.  Nothing is sent for start-up, an input switch, a frame-rate
    // change or Clock mode.  The first tick that finds the generator
    // playing drops a pending mark, so GO (stop, preset and play in one
    // call) and a PLAY within the settle time send nothing extra.  A PLAY
    // and a PAUSE before a tick (OSC /stc/N/gen/preset, then
    // /stc/N/gen/pause) keep it -- PLAY from a stop marks its own move to
    // Start TC or the A/B's In -- since the outputs never ran.  Message
    // thread, like the tick.
    //
    // 150 ms: a click goes out 150-167 ms after it (the first tick past the
    // settle time).  JUCE sends a drag event only when the mouse moves (the
    // waveform view asks for no auto-repeat), so a drag sends nothing while
    // its events keep coming within 150 ms of each other, and sends where
    // the hand rests once it has been still that long (at the first tick
    // past it).  OSC jogs closer together than that (loop_out_sim's
    // streams, 15 to 60 a second) go out once, at the end; further apart (2
    // a second), once each.  Shorter, a slow drag's hesitations would send
    // locates mid-gesture; longer, a click would reach the outputs later.
    static constexpr double kGenParkedSettleMs = 150.0;

    /// A generator function moved the position from fromMs: while the
    /// generator is paused or stopped in transport mode, mark a parked
    /// locate, restarting the settle time.  Playing or in Clock mode the
    /// outputs run and carry the position themselves.  Message thread.
    void markGeneratorParkedLocate(double fromMs)
    {
        if (activeInput != InputSource::SystemTime || genClockMode
            || genState == GeneratorState::Playing || genCurrentMs == fromMs)
            return;
        genParkedPending   = true;
        genParkedChangedMs = juce::Time::getMillisecondCounterHiRes();
    }

    /// Once per tick with the generator in transport mode, sourceActive
    /// known, before routeTimecodeToOutputs: asks for the parked locate
    /// (forwardParkedLocate) when a marked position has rested for
    /// kGenParkedSettleMs, the outputs are still paused, and they would get
    /// another frame than they were last given.  Message thread.
    void updateGeneratorParkedLocate()
    {
        if (sourceActive)
        {
            // Playing: the outputs run from this tick and carry the
            // position themselves (GO, or PLAY within the settle time).
            genParkedPending = false;
            return;
        }
        if (outputsWereActive)
            return;   // this tick's clean stop gives the position and clears the mark
        if (! genParkedGivenValid)
        {
            // Start-up, or an input switch from a source that was not
            // active: the outputs were given nothing.  Where they were found
            // paused is the reference; nothing is sent for it.
            genParkedGivenMs    = genCurrentMs;
            genParkedGivenValid = true;
            genParkedPending    = false;
            return;
        }
        if (! genParkedPending
            || juce::Time::getMillisecondCounterHiRes() - genParkedChangedMs < kGenParkedSettleMs)
            return;
        genParkedPending = false;
        // Compared as the outputs get it (routeTimecodeToOutputs' baseTc):
        // with FPS CONVERT, two input frames can give one output frame.
        const FrameRate outRate = getEffectiveOutputFps();
        auto onOutputs = [&](double ms)
        {
            const Timecode tc = wallClockToTimecode(ms, currentFps);
            return fpsConvertEnabled ? convertTimecodeRate(tc, currentFps, outRate) : tc;
        };
        if (sameTimecode(onOutputs(genCurrentMs), onOutputs(genParkedGivenMs)))
            return;   // back on the frame the outputs hold
        genParkedGivenMs    = genCurrentMs;
        forwardParkedLocate = true;
    }

    //==========================================================================
    // MixerMap-driven parameter forwarding
    //
    // Reads all DJM mixer values, compares with lastSentMixer[], and sends
    // changed values via OSC and/or MIDI CC using the addresses and CC numbers
    // configured in the MixerMap.
    //==========================================================================
    /// Empty the mixer forward's DMX frame and forget what was sent, so the
    /// next source's values all go out afresh (setInputSource, AUDIT ENG-10).
    void resetMixerForward()
    {
        std::memset(dmxBuffer, 0, sizeof(dmxBuffer));
        dmxHighWaterMark = 0;
        lastDmxSendTime = 0.0;
        std::fill(std::begin(lastSentMixer), std::end(lastSentMixer), -1);
        lastMixerPktCount = 0;
        std::fill(std::begin(lastSentSlqMixer), std::end(lastSentSlqMixer), -1);
    }

    void forwardMixerParams()
    {
        if (!sharedProDJLink || !mixerMapPtr) return;

        const bool doArtnet = artnetMixerForwardEnabled && artnetOutput.getIsRunning();
        bool dmxDirty = false;

        // Only iterate mixer values when a new 0x39 packet has arrived.
        // At 60Hz tick rate with ~5Hz mixer packets, this skips ~92% of iterations.
        uint32_t currentMixerPktCount = sharedProDJLink->getMixerPacketCount();
        if (currentMixerPktCount != lastMixerPktCount)
        {
            lastMixerPktCount = currentMixerPktCount;

            const int n = std::min(mixerMapPtr->size(), kMaxMixerEntries);
            const auto& entries = mixerMapPtr->getEntries();
            const bool doOsc    = oscMixerForwardEnabled && triggerOutput.isOscConnected();
            const bool doMidi   = midiMixerForwardEnabled && triggerOutput.isMidiOpen();
            const int ccCh      = midiMixerCCChannel;
            const int noteCh    = midiMixerNoteChannel;

            for (int i = 0; i < n; ++i)
            {
                const auto& e = entries[(size_t)i];
                if (!e.enabled) continue;

                int val = readMixerValue(i);
                if (val < 0 || val == lastSentMixer[i]) continue;

                // Map raw value according to parameter type:
                //   Continuous (faders, knobs):  OSC 0.0-1.0, CC 0-127, DMX 0-255
                //   Toggle     (on/off buttons): OSC 0.0/1.0, CC 0/127, DMX 0/255
                //   Discrete   (select, assign): OSC integer,  CC clamp, DMX raw
                float oscVal;
                int   midiVal;
                int   dmxVal;
                switch (e.paramType)
                {
                    case ParamType::Toggle:
                        oscVal  = val > 0 ? 1.0f : 0.0f;
                        midiVal = val > 0 ? 127 : 0;
                        dmxVal  = val > 0 ? 255 : 0;
                        break;
                    case ParamType::Discrete:
                        oscVal  = (float)val;          // integer as float (e.g. 3.0 for BeatFX #3)
                        midiVal = juce::jlimit(0, 127, val);
                        dmxVal  = val;
                        break;
                    default: // Continuous
                        oscVal  = val / 255.0f;
                        midiVal = val >> 1;            // 0-255 -> 0-127
                        dmxVal  = val;
                        break;
                }

                if (doOsc && e.oscAddress.isNotEmpty())
                    triggerOutput.sendOscFloat(e.oscAddress, oscVal);

                if (doMidi && e.midiCC >= 0)
                    triggerOutput.sendCC(ccCh, e.midiCC, midiVal);

                if (doMidi && e.midiNote >= 0)
                    triggerOutput.sendNote(noteCh, e.midiNote, midiVal);

                if (doArtnet && e.artnetCh > 0 && e.artnetCh <= 512)
                {
                    dmxBuffer[e.artnetCh - 1] = uint8_t(dmxVal);
                    dmxDirty = true;
                    if (e.artnetCh > dmxHighWaterMark)
                        dmxHighWaterMark = e.artnetCh;
                }

                lastSentMixer[i] = val;
            }
        }

        // Art-Net DMX re-send: runs even when no new mixer data to prevent
        // Art-Net node DMX timeout (some nodes blackout after 2-3s without data).
        if (doArtnet && dmxHighWaterMark > 0)
        {
            double now = juce::Time::getMillisecondCounterHiRes();
            if (dmxDirty || (now - lastDmxSendTime) >= 100.0)
            {
                artnetOutput.sendDmxFrame(dmxBuffer, dmxHighWaterMark, artnetMixerUniverse);
                lastDmxSendTime = now;
            }
        }
    }

    //==========================================================================
    // Forward StageLinQ mixer data (faders + crossfader) via OSC/MIDI/ArtNet.
    //
    // StageLinQ provides channel faders (0.0-1.0) and crossfader (0.0-1.0)
    // directly from StateMap.  Where each goes (OSC address, MIDI CC/note,
    // DMX channel) and whether it is sent come from the Denon MixerMap
    // (slqMixerMapPtr, MixerMap::buildDenonDefaults), five entries in this
    // order: CH1-CH4 fader, crossfader (readSlqMixerValue).  Values go out
    // as 0.0-1.0 on OSC, 0-127 on MIDI and 0-255 on DMX.
    //==========================================================================
    void forwardStageLinQMixer()
    {
        if (!sharedStageLinQ || !slqMixerMapPtr) return;

        const bool doOsc    = oscMixerForwardEnabled && triggerOutput.isOscConnected();
        const bool doMidi   = midiMixerForwardEnabled && triggerOutput.isMidiOpen();
        const bool doArtnet = artnetMixerForwardEnabled && artnetOutput.getIsRunning();
        if (!doOsc && !doMidi && !doArtnet) return;

        bool dmxDirty = false;
        const int ccCh   = midiMixerCCChannel;
        const int noteCh = midiMixerNoteChannel;
        const int n = juce::jmin(slqMixerMapPtr->size(), kSlqMixerSlots);
        const auto& entries = slqMixerMapPtr->getEntries();

        for (int i = 0; i < n; ++i)
        {
            const auto& e = entries[(size_t)i];
            if (!e.enabled) continue;

            int val = readSlqMixerValue(i);
            if (val < 0 || val == lastSentSlqMixer[i]) continue;

            if (doOsc && e.oscAddress.isNotEmpty())
                triggerOutput.sendOscFloat(e.oscAddress, val / 255.0f);

            if (doMidi && e.midiCC >= 0)
                triggerOutput.sendCC(ccCh, e.midiCC, val >> 1);

            if (doMidi && e.midiNote >= 0)
                triggerOutput.sendNote(noteCh, e.midiNote, val >> 1);

            if (doArtnet && e.artnetCh > 0 && e.artnetCh <= 512)
            {
                dmxBuffer[e.artnetCh - 1] = (uint8_t)val;
                dmxDirty = true;
                if (e.artnetCh > dmxHighWaterMark)
                    dmxHighWaterMark = e.artnetCh;
            }

            lastSentSlqMixer[i] = val;
        }

        // Art-Net DMX re-send (prevent node timeout)
        if (doArtnet && dmxHighWaterMark > 0)
        {
            double now = juce::Time::getMillisecondCounterHiRes();
            if (dmxDirty || (now - lastDmxSendTime) >= 100.0)
            {
                artnetOutput.sendDmxFrame(dmxBuffer, dmxHighWaterMark, artnetMixerUniverse);
                lastDmxSendTime = now;
            }
        }
    }

    /// Read a StageLinQ mixer value (0-255) by MixerMap entry index.
    /// Entry order matches buildDenonDefaults():
    ///   [0] CH1 fader, [1] CH2 fader, [2] CH3 fader, [3] CH4 fader, [4] crossfader
    int readSlqMixerValue(int entryIndex) const
    {
        if (!sharedStageLinQ) return -1;
        if (entryIndex >= 0 && entryIndex < 4)
            return juce::jlimit(0, 255, (int)(sharedStageLinQ->getFaderPosition(entryIndex + 1) * 255.0));
        if (entryIndex == 4)
            return juce::jlimit(0, 255, (int)(sharedStageLinQ->getCrossfaderPosition() * 255.0));
        return -1;
    }

    /// Read a DJM mixer parameter value (0-255) by MixerMap entry index.
    /// Returns -1 if the index is out of range.
    /// Entry order matches MixerMap::buildDefaults():
    ///   [0-12]  CH1: fader,trim,eq_hi,eq_mid,eq_lo,color,cue,input_src,xf_assign,
    ///                 comp,eq_lo_mid,send,cue_b
    ///   [13-25] CH2, [26-38] CH3, [39-51] CH4, [52-64] CH5, [65-77] CH6
    ///   [78+]   globals (crossfader, master, monitor, fx, sends, isolator, etc.)
    /// MixerMap::buildDefaults() ends with a jassert on this layout (6 x 13
    /// channel entries, then 45 globals from the crossfader to Multi I/O
    /// Level, AUDIT DEBT-9): the two change together.
    int readMixerValue(int entryIndex) const
    {
        if (!sharedProDJLink) return -1;
        auto& pdl = *sharedProDJLink;

        // Per-channel params (13 per channel, up to 6 channels)
        static constexpr int kParamsPerCh = 13;
        static constexpr int kChBlock = kParamsPerCh * ProDJLink::kMaxMixerChannels;  // 78

        if (entryIndex < kChBlock)
        {
            int ch = (entryIndex / kParamsPerCh) + 1;   // 1-6
            int p  =  entryIndex % kParamsPerCh;         // 0-12
            switch (p)
            {
                case 0: return pdl.getChannelFader(ch);
                case 1: return pdl.getChannelTrim(ch);
                case 2: return pdl.getChannelEqHi(ch);
                case 3: return pdl.getChannelEqMid(ch);
                case 4: return pdl.getChannelEqLo(ch);
                case 5: return pdl.getChannelColor(ch);
                case 6: return pdl.getChannelCue(ch);
                case 7: return pdl.getChannelInputSrc(ch);
                case 8: return pdl.getChannelXfAssign(ch);
                // V10 per-channel (0 on 900NXS2)
                case  9: return pdl.getChannelComp(ch);
                case 10: return pdl.getChannelEqLoMid(ch);
                case 11: return pdl.getChannelSend(ch);
                case 12: return pdl.getChannelCueB(ch);
                default: return -1;
            }
        }

        // Global params (indices kChBlock+)
        int gi = entryIndex - kChBlock;
        switch (gi)
        {
            case  0: return pdl.getCrossfader();
            case  1: return pdl.getMasterFader();
            case  2: return pdl.getMasterCue();
            case  3: return pdl.getFaderCurve();
            case  4: return pdl.getXfCurve();
            case  5: return pdl.getBoothLevel();
            case  6: return pdl.getHpCueLink();
            case  7: return pdl.getHpMixing();
            case  8: return pdl.getHpLevel();
            case  9: return pdl.getBeatFxSelect();
            case 10: return pdl.getBeatFxLevel();
            case 11: return pdl.getBeatFxOn();
            case 12: return pdl.getBeatFxAssign();
            case 13: return pdl.getFxFreqLo();
            case 14: return pdl.getFxFreqMid();
            case 15: return pdl.getFxFreqHi();
            case 16: return pdl.getSendReturnLevel();
            case 17: return pdl.getColorFxSelect();
            case 18: return pdl.getColorFxParam();
            case 19: return pdl.getColorFxAssign();
            case 20: return pdl.getMicEqHi();
            case 21: return pdl.getMicEqLo();
            // V10 globals (0 on 900NXS2)
            // A9+ globals (A9 and V10: dual CUE, HP B, booth EQ)
            case 22: return pdl.getMasterCueB();
            case 23: return pdl.getHpCueLinkB();
            case 24: return pdl.getHpMixingB();
            case 25: return pdl.getHpLevelB();
            case 26: return pdl.getBoothEqHi();
            case 27: return pdl.getBoothEqLo();
            case 28: return pdl.getBoothEq();
            // V10-only globals
            case 29: return pdl.getIsolatorOn();
            case 30: return pdl.getIsolatorHi();
            case 31: return pdl.getIsolatorMid();
            case 32: return pdl.getIsolatorLo();
            case 33: return pdl.getFilterLPF();
            case 34: return pdl.getFilterHPF();
            case 35: return pdl.getFilterResonance();
            case 36: return pdl.getSendExt1();
            case 37: return pdl.getSendExt2();
            case 38: return pdl.getMasterMixOn();
            case 39: return pdl.getMasterMixSize();
            case 40: return pdl.getMasterMixTime();
            case 41: return pdl.getMasterMixTone();
            case 42: return pdl.getMasterMixLevel();
            case 43: return pdl.getMultiIoSelect();
            case 44: return pdl.getMultiIoLevel();
        }
        return -1;
    }

    //==========================================================================
    // Sub-frame phase publishing (issue #15)
    //==========================================================================
    // tick() runs on the message thread at 60Hz, so simply noticing that the
    // timecode value changed locates the frame boundary to no better than
    // 16.7ms -- half a frame at 30fps, and worse still, at 30fps the tick is
    // exactly twice the frame rate, so the error is a constant that differs
    // per session rather than noise that could be averaged away.  That is
    // what made the LTC output phase random on every restart.
    //
    // Instead each source publishes where it actually is inside the current
    // frame, which every source can answer far more precisely than the tick
    // rate: position-based sources (generator, Pro DJ Link, StageLinQ,
    // Winamp, system clock) hold a continuous millisecond playhead, and
    // frame-based sources (MTC, LTC) know the instant the frame arrived.
    // Sources that can supply neither leave the phase unset and the LTC
    // encoder keeps its previous free-running behaviour.
    double framePhaseMs = 0.0;
    bool   framePhaseValid = false;

    /// Publish the phase from a continuous playhead position in ms.
    ///
    /// The phase and the value handed to the encoder have to come out of the
    /// same quantisation of the same playhead.  A plain fmod does not: at a
    /// position sitting on a frame boundary the value rounds up through the
    /// epsilon that TimecodeCore uses against exactly this truncation, while
    /// the fmod returns a hair under a whole frame -- the pair then says
    /// "frame N, and almost a frame into it", which is frame N+1.  The
    /// encoder reads it as one frame of catching up to do and skips a frame
    /// on the wire.  Taking the remainder off the same epsilon-corrected
    /// frame index leaves the phase at zero on the boundary, where it
    /// belongs.
    void setFramePhaseFromPosition(double positionMs, FrameRate fps)
    {
        const double f = frameRateToDouble(fps);
        if (f <= 0.0) return;
        const double frameMs = 1000.0 / f;
        const double frames  = positionMs / frameMs;
        const double idx     = std::floor(frames + 1e-9);
        double p = (frames - idx) * frameMs;
        if (p < 0.0) p = 0.0;
        if (p >= frameMs) p = 0.0;
        framePhaseMs = p;
        framePhaseValid = true;
    }

    /// Publish the phase from the instant the current frame arrived.
    void setFramePhaseFromArrival(double arrivalMs, FrameRate fps)
    {
        if (arrivalMs <= 0.0) return;
        const double f = frameRateToDouble(fps);
        if (f <= 0.0) return;
        const double frameMs = 1000.0 / f;
        double p = std::fmod(juce::Time::getMillisecondCounterHiRes() - arrivalMs, frameMs);
        if (p < 0.0) p += frameMs;
        framePhaseMs = p;
        framePhaseValid = true;
    }

    /// FPS CONVERT (AUDIT ENG-5): the sources publish the phase on the INPUT
    /// rate's grid -- time since the start of currentTimecode's frame at
    /// currentFps -- while LtcOutput reads it as time since the start of
    /// the frame it is given (`outTc`, the converted value) at the output
    /// rate: modulo an output frame for the phase lock (DESIGN D24), whole
    /// output frames carried into the value at a seed.  Taken as it was,
    /// the encoder worked from a position up to a frame off and locked to
    /// a boundary up to half a frame off.  Rewritten here as the source's
    /// position (input frame start plus phase) less the start of `outTc`'s
    /// frame: a converted value names the output frame holding the INPUT
    /// frame's start, so this is under one input plus one output frame,
    /// and the encoder ages the value by the whole frames in it.  The
    /// epsilon is setFramePhaseFromPosition's, for the same reason: a
    /// position on an output boundary must read as the next frame and 0,
    /// not as this one and a whole frame.  False (nothing published this
    /// tick) when the two sit on different sides of midnight.
    bool phaseOnOutputGrid(const Timecode& outTc, FrameRate outRate)
    {
        const double f = frameRateToDouble(outRate);
        if (f <= 0.0) return false;
        const double frameMs = 1000.0 / f;
        const double sinceStart = timecodeToMs(currentTimecode, currentFps) + framePhaseMs
                                - timecodeToMs(outTc, outRate);
        const double frames = sinceStart / frameMs;
        if (frames < -1e-6 || frames > 4.0) return false;
        const double idx = std::floor(juce::jmax(0.0, frames) + 1e-9);
        double rem = (frames - idx) * frameMs;
        if (rem < 0.0) rem = 0.0;
        framePhaseMs = idx * frameMs + rem;
        return true;
    }

    /// Follow the frame rate a signal input detected (tick, message thread).
    /// Rates its wire cannot tell apart -- 24 for 23.976 always, 30 for
    /// 29.97 when `thirtyAmbiguous` -- leave a 23.976 or 29.97 the user chose
    /// in place (userOverrodeLtcFps); a rate that is not ambiguous ends the
    /// choice.  LTC and LA-Net carry 24/25/30 only; MTC's and Art-Net's rate
    /// code 0 is 24 and 23.976 alike, while 29.97 has its own code, and
    /// these forced 24 every tick (AUDIT NET-4).
    void followDetectedRate(FrameRate d, bool thirtyAmbiguous)
    {
        const bool held = userOverrodeLtcFps
            && ((currentFps == FrameRate::FPS_2398 && d == FrameRate::FPS_24)
             || (thirtyAmbiguous && currentFps == FrameRate::FPS_2997 && d == FrameRate::FPS_30));
        if (d == currentFps || held)
            return;
        if (d != FrameRate::FPS_24 && ! (thirtyAmbiguous && d == FrameRate::FPS_30))
            userOverrodeLtcFps = false;
        setFrameRate(d);
    }

    static bool sameTimecode(const Timecode& a, const Timecode& b)
    {
        return a.hours == b.hours && a.minutes == b.minutes
            && a.seconds == b.seconds && a.frames == b.frames;
    }

    void routeTimecodeToOutputs()
    {
        // Keep LTC user bits current for the dynamic modes (passthrough from
        // the LTC input, system date).  No-op in MANUAL mode.
        refreshDynamicUserBits();

        FrameRate outRate = getEffectiveOutputFps();
        Timecode baseTc = fpsConvertEnabled
                        ? convertTimecodeRate(currentTimecode, currentFps, outRate)
                        : currentTimecode;
        outputTimecode = baseTc;

        // Hand the encoder the sub-frame phase gathered this tick, so its
        // frame boundary lands on the timecode frame boundary instead of
        // wherever the audio device happened to start (issue #15).  The
        // encoder reads it as time since the start of the frame it is given,
        // at the output rate; with FPS CONVERT it is re-expressed on that
        // grid first (AUDIT ENG-5).
        if (framePhaseValid && fpsConvertEnabled && outRate != currentFps)
            framePhaseValid = phaseOnOutputGrid(baseTc, outRate);
        if (framePhaseValid)
            ltcOutput.setFramePhaseMs(framePhaseMs);
        framePhaseValid = false;   // each tick must publish afresh

        bool wasActive = outputsWereActive;
        outputsWereActive = sourceActive;

        if (sourceActive)
        {
            if (outputMtcEnabled && mtcOutput.getIsRunning())
            {
                mtcOutput.setTimecode(offsetTimecode(baseTc, mtcOutputOffset, outRate));
                mtcOutput.setPaused(false);
            }
            if (outputArtnetEnabled && artnetOutput.getIsRunning())
            {
                artnetOutput.setTimecode(offsetTimecode(baseTc, artnetOutputOffset, outRate));
                artnetOutput.setPaused(false);
            }
            if (outputLANetTCEnabled && laNetTCOutput.getIsRunning())
            {
                laNetTCOutput.setTimecode(offsetTimecode(baseTc, laNetTCOutputOffset, outRate));
                laNetTCOutput.setPaused(false);
            }
            if (outputLtcEnabled && ltcOutput.getIsRunning())
            {
                ltcOutput.setTimecode(offsetTimecode(baseTc, ltcOutputOffset, outRate));
                // Inactive -> active for ANY source: the LTC encoder was
                // paused mid-frame with stale bits and its phase alignment
                // is gone, so it seeds afresh at the published phase.  (Pro
                // DJ Link and StageLinQ used to do this in their own
                // branches; MTC, LTC, Art-Net, LA-Net, Hippotizer, Winamp
                // and the generator resumed unaligned.)  Asked for after the
                // new value is published: with HOLD ON PAUSE the encoder
                // runs while paused, and a callback between the two used to
                // seed from the stop value -- after a move made while
                // stopped, the old position went out until the tracking
                // snapped.
                if (!wasActive)
                    ltcOutput.reseed();
                ltcOutput.setPaused(false);
            }
            if (outputHippoEnabled && hippotizerOutput.getIsRunning())
            {
                hippotizerOutput.setTimecode(baseTc);
                hippotizerOutput.setPaused(false);
            }

            // --- Seek/Hot Cue resync ---
            // PLL detected a position jump >500ms (seek, hot cue, track load),
            // or the generator's timecode jumped (genJumpAnnounce: a loop
            // wrap, or its own seek of 500 ms or more, #24).  Force
            // immediate resync on all digital outputs so receivers know the
            // new position instantly:
            //   MTC:    Full Frame message (instant vs 8 QFs = 2 frames)
            //   ArtNet: immediate frame (vs waiting for next timer tick)
            //   LTC:    reseed encoder (clean frame start at new position)
            if (pll.seekDetected || genJumpAnnounce)
            {
                pll.seekDetected = false;
                genJumpAnnounce = false;
                if (outputMtcEnabled && mtcOutput.getIsRunning())
                    mtcOutput.forceResync();
                if (outputArtnetEnabled && artnetOutput.getIsRunning())
                    artnetOutput.forceResync();
                if (outputLANetTCEnabled && laNetTCOutput.getIsRunning())
                    laNetTCOutput.forceResync();
                if (outputLtcEnabled && ltcOutput.getIsRunning())
                    ltcOutput.reseed();
                if (outputHippoEnabled && hippotizerOutput.getIsRunning())
                    hippotizerOutput.forceResync();
            }
        }
        else
        {
            // --- Clean stop ---
            // On active->inactive transition, send one final frame at the
            // stopped position before pausing. This gives receivers the exact
            // stop point instead of leaving them with an incomplete QF cycle
            // or stale position.
            if (wasActive)
            {
                if (outputMtcEnabled && mtcOutput.getIsRunning())
                {
                    mtcOutput.setTimecode(offsetTimecode(baseTc, mtcOutputOffset, outRate));
                    mtcOutput.sendFullFrame();
                }
                if (outputArtnetEnabled && artnetOutput.getIsRunning())
                {
                    artnetOutput.setTimecode(offsetTimecode(baseTc, artnetOutputOffset, outRate));
                    artnetOutput.forceResync();
                }
                if (outputLANetTCEnabled && laNetTCOutput.getIsRunning())
                {
                    laNetTCOutput.setTimecode(offsetTimecode(baseTc, laNetTCOutputOffset, outRate));
                    laNetTCOutput.forceResync();
                }
                // LTC: the stop value.  With HOLD ON PAUSE the encoder carries
                // it from the next frame boundary (the frame in progress
                // finishes); without it the output goes silent at once,
                // mid-codeword.
                if (outputLtcEnabled && ltcOutput.getIsRunning())
                    ltcOutput.setTimecode(offsetTimecode(baseTc, ltcOutputOffset, outRate));
                if (outputHippoEnabled && hippotizerOutput.getIsRunning())
                {
                    hippotizerOutput.setTimecode(baseTc);
                    hippotizerOutput.forceResync();
                }
                // The generator's parked locate (#24): this is the position
                // the outputs now hold, and a change marked before this tick
                // is in it.
                if (activeInput == InputSource::SystemTime)
                {
                    genParkedGivenMs = genCurrentMs;
                    genParkedGivenValid = true;
                }
                genParkedPending = false;
            }
            else if (forwardParkedLocate)
            {
                // A locate made while the source is stopped: an MTC source's
                // Full Frame (see the MTC branch of tick, AUDIT LTC-13), or
                // the generator's own position changed while paused or
                // stopped, once it has rested (updateGeneratorParkedLocate,
                // #24).  The outputs stay paused, and receivers get the new
                // position the way the clean stop gives the stop -- an MTC
                // Full Frame (the MTC spec's locate), one Art-Net and one
                // LA-Net frame.  Those two send only while not paused, so
                // each is let out for the one frame and paused again (the
                // frame goes out at setPaused(true) at the latest).  LTC OUT
                // gets the value as at the clean stop: with HOLD ON PAUSE the
                // held frame carries it from the next frame boundary, without
                // HOLD the output stays silent (#24; a held frame used to
                // stay on the stop value).  HippoNet is not sent: no capture
                // shows what a Hippotizer does with a position while
                // stopped, and a new message needs one (DESIGN D2).  (The
                // MTC source: until AUDIT LTC-13 made the locate a locate,
                // the source ran through the freewheel from it and the clean
                // stop at the end sent that run-on value.)
                if (outputMtcEnabled && mtcOutput.getIsRunning())
                {
                    mtcOutput.setTimecode(offsetTimecode(baseTc, mtcOutputOffset, outRate));
                    mtcOutput.sendFullFrame();
                }
                if (outputArtnetEnabled && artnetOutput.getIsRunning())
                {
                    artnetOutput.setTimecode(offsetTimecode(baseTc, artnetOutputOffset, outRate));
                    artnetOutput.setPaused(false);
                    artnetOutput.forceResync();
                    artnetOutput.setPaused(true);
                }
                if (outputLANetTCEnabled && laNetTCOutput.getIsRunning())
                {
                    laNetTCOutput.setTimecode(offsetTimecode(baseTc, laNetTCOutputOffset, outRate));
                    laNetTCOutput.setPaused(false);
                    laNetTCOutput.forceResync();
                    laNetTCOutput.setPaused(true);
                }
                if (outputLtcEnabled && ltcOutput.getIsRunning())
                    ltcOutput.setTimecode(offsetTimecode(baseTc, ltcOutputOffset, outRate));
            }
            forwardParkedLocate = false;

            // Clear seek flag if it was set during transition to inactive
            pll.seekDetected = false;
            genJumpAnnounce = false;

            if (outputMtcEnabled && mtcOutput.getIsRunning()) mtcOutput.setPaused(true);
            if (outputArtnetEnabled && artnetOutput.getIsRunning()) artnetOutput.setPaused(true);
            if (outputLANetTCEnabled && laNetTCOutput.getIsRunning()) laNetTCOutput.setPaused(true);
            if (outputLtcEnabled && ltcOutput.getIsRunning()) ltcOutput.setPaused(true);
            if (outputHippoEnabled && hippotizerOutput.getIsRunning()) hippotizerOutput.setPaused(true);
        }
    }

    void updateVuMeters()
    {
        auto decayLevel = [](float current, float target, float decay = 0.85f) {
            return target > current ? target : current * decay;
        };

        float ltcInLvl  = ltcInput.getIsRunning()  ? ltcInput.getLtcPeakLevel()  : 0.0f;
        float thruInLvl = ltcInput.getIsRunning()  ? ltcInput.getThruPeakLevel() : 0.0f;
        float ltcOutLvl = (ltcOutput.getIsRunning() && !ltcOutput.isPaused()) ? ltcOutput.getPeakLevel() : 0.0f;
        float thruOutLvl = (audioThru && audioThru->getIsRunning()) ? audioThru->getPeakLevel() : 0.0f;

        sLtcIn  = decayLevel(sLtcIn,  ltcInLvl);
        sThruIn = decayLevel(sThruIn, thruInLvl);
        sLtcOut = decayLevel(sLtcOut, ltcOutLvl);
        sThruOut = decayLevel(sThruOut, thruOutLvl);
    }

    JUCE_DECLARE_WEAK_REFERENCEABLE(TimecodeEngine)
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(TimecodeEngine)
};