framesync.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_PROAV
#include <promeki/namespace.h>
#include <promeki/string.h>
#include <promeki/frame.h>
#include <promeki/audiodesc.h>
#if PROMEKI_ENABLE_SRC
#include <promeki/audioresampler.h>
#endif
#include <promeki/videopayload.h>
#include <promeki/pcmaudiopayload.h>
#include <promeki/framecount.h>
#include <promeki/framenumber.h>
#include <promeki/framerate.h>
#include <promeki/duration.h>
#include <promeki/error.h>
#include <promeki/result.h>
#include <promeki/mutex.h>
#include <promeki/waitcondition.h>
#include <promeki/list.h>
#include <promeki/periodiccallback.h>
#include <promeki/atomic.h>
#include <promeki/clock.h>
 
PROMEKI_NAMESPACE_BEGIN
 
class SyntheticClock;
 
class FrameSync {
        public:
                enum class InputOverflowPolicy {
                        DropOldest,
 
                        Block,
                };
 
                struct PullResult {
                                Frame frame;
 
                                FrameNumber frameIndex{0};
 
                                FrameCount framesRepeated{0};
 
                                FrameCount framesDropped{0};
 
                                Duration error;
                };
 
                FrameSync();
 
                explicit FrameSync(const String &name);
 
                ~FrameSync();
 
                FrameSync(const FrameSync &) = delete;
                FrameSync &operator=(const FrameSync &) = delete;
                FrameSync(FrameSync &&) = delete;
                FrameSync &operator=(FrameSync &&) = delete;
 
                void setName(const String &name) { _name = name; }
 
                const String &name() const { return _name; }
 
                void setTargetFrameRate(const FrameRate &fps);
 
                const FrameRate &targetFrameRate() const { return _targetFrameRate; }
 
                void setTargetAudioDesc(const AudioDesc &desc);
 
                const AudioDesc &targetAudioDesc() const { return _targetAudioDesc; }
 
                void setClock(const Clock::Ptr &clock);
 
                Clock::Ptr clock() const { return _clock; }
 
                void setInputQueueCapacity(int capacity);
 
                int inputQueueCapacity() const { return _queueCapacity; }
 
                void setInputOverflowPolicy(InputOverflowPolicy policy);
 
                InputOverflowPolicy inputOverflowPolicy() const { return _overflowPolicy; }
 
                void reset();
 
                void reset(int64_t originNs);
 
                Error pushFrame(const Frame &frame);
 
                void pushEndOfStream();
 
                Result<PullResult> pullFrame(bool blockOnEmpty = true);
 
                void interrupt();
 
                void clearInterrupt();
 
                void resetSourceRateEstimator();
 
                // ---- Stats ----
 
                FrameCount framesIn() const { return FrameCount(_framesIn.value()); }
 
                FrameCount framesOut() const { return FrameCount(_framesOut.value()); }
 
                FrameCount framesRepeated() const { return FrameCount(_framesRepeated.value()); }
 
                FrameCount framesDropped() const { return FrameCount(_framesDropped.value()); }
 
                FrameCount overflowDrops() const { return FrameCount(_overflowDrops.value()); }
 
                Duration accumulatedError() const { return Duration::fromNanoseconds(_accumulatedErrorNs); }
 
                double currentResampleRatio() const { return _currentResampleRatio; }
 
                double currentSourceAudioRate() const { return _sourceAudioRateHz; }
 
                double currentSourceVideoRate() const { return _sourceVideoRateHz; }
 
        private:
                struct QueuedFrame {
                                Frame frame;
                                int64_t    videoTsNs = 0; // source video timestamp
                                bool       hasVideoTs = false;
                                int64_t    audioTsNs = 0; // first audio timestamp
                                bool       hasAudioTs = false;
                };
 
                // Initial setup done under the mutex on demand.
                void ensureInitialised();
                void resetLocked(bool setExplicitOrigin, int64_t originNs);
 
                // Pull-path helpers (all assume _mutex is NOT held).
                void selectVideo(int64_t sourceTimeNs, int64_t nextSourceTimeNs, VideoPayload::Ptr &outVideo,
                                 int64_t &outRepeated, int64_t &outDropped);
                PcmAudioPayload::Ptr produceAudio(int64_t targetSamples);
                void                 updateSourceAudioRate(const PcmAudioPayload &audio, int64_t audioTsNs);
                void                 updateSourceVideoRate(int64_t videoTsNs);
 
                // Periodic debug log.
                void periodicDebugLog(int64_t nowNs);
 
                // Configuration.
                String              _name;
                FrameRate           _targetFrameRate;
                AudioDesc           _targetAudioDesc;
                Clock::Ptr          _clock;
                SyntheticClock     *_syntheticClock = nullptr; // cached downcast
                int                 _queueCapacity = 8;
                InputOverflowPolicy _overflowPolicy = InputOverflowPolicy::DropOldest;
 
                // Shared state (all guarded by _mutex unless noted).
                mutable Mutex _mutex;
                WaitCondition _cv;
 
                // Input queue.
                List<QueuedFrame> _queue;
                bool              _eos = false;
                bool              _interrupted = false;
 
                // Timeline state.
                bool       _started = false;
                bool       _explicitOrigin = false;
                int64_t    _originNs = 0;
                int64_t    _framePeriodNs = 0;
                FrameCount _frameCount{0};
 
                // Source-origin anchoring — captured on first pushed frame.
                bool    _sourceOriginValid = false;
                int64_t _sourceVideoOriginNs = 0;
                int64_t _sourceAudioOriginNs = 0;
 
                // Held "current" video payload (used for repeats when
                // no new input qualifies for this pull).  Carries the
                // source payload with its original metadata.
                VideoPayload::Ptr _heldVideo;
                int64_t           _heldVideoSourceTsNs = 0;
                bool              _hasHeldVideo = false;
 
                // FrameSyncDrop/FrameSyncRepeat metadata state.
                // _pendingFrameSyncDrops accumulates input drops across
                // pulls that emit a repeat — the spec requires
                // FrameSyncDrop to be zero on repeat outputs, so any
                // drops that occur while the output is stuck on a
                // repeat are deferred to the next fresh emit.
                // _frameSyncRepeatIndex is the position of the current
                // output within a repeat sequence (0 on fresh emit;
                // 1, 2, ... on successive repeats).
                int64_t _pendingFrameSyncDrops = 0;
                int64_t _frameSyncRepeatIndex = 0;
 
                // Audio resampler pipeline.  Only present when libsamplerate
                // (PROMEKI_ENABLE_SRC) is compiled in; without it the audio
                // path falls back to a 1:1 pass-through (no rate conversion).
#if PROMEKI_ENABLE_SRC
                AudioResampler::UPtr       _resampler;
#endif
                List<PcmAudioPayload::Ptr> _audioInput;               // pending input audio, FIFO
                int64_t                    _audioSamplesConsumed = 0; // of current front audio
 
                // Rate tracking.
                double  _sourceAudioRateHz = 0.0; // LPF'd source rate
                double  _sourceVideoRateHz = 0.0; // LPF'd source video rate
                double  _currentResampleRatio = 1.0;
                int64_t _lastAudioTsForRateNs = 0;
                int64_t _lastAudioTsSamples = 0; // samples covered by last push
                int64_t _lastVideoTsForRateNs = 0;
 
                // Error / logging.
                int64_t    _accumulatedErrorNs = 0;
                int64_t    _lastPeriodicLogNs = 0;
                FrameCount _frameCountAtLastLog{0};
                FrameCount _lastEmitFrameCount = FrameCount::unknown(); // debug only
 
                // PLL-style deadline bias.  The per-pull measured
                // wake-error feeds this LPF; the next deadline is
                // shifted earlier by this amount so any systematic
                // bias (sleep latency, clock interpolation rate
                // mismatch, per-pull work time) self-corrects.
                int64_t _deadlineBiasNs = 0;
 
                // Atomic stats (readable from any thread without lock).
                Atomic<int64_t> _framesIn;
                Atomic<int64_t> _framesOut;
                Atomic<int64_t> _framesRepeated;
                Atomic<int64_t> _framesDropped;
                Atomic<int64_t> _overflowDrops;
};
 
PROMEKI_NAMESPACE_END
 
#endif // PROMEKI_ENABLE_PROAV