inspectormediaio.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_PROAV
#include <cstdio>
#include <functional>
#include <promeki/function.h>
#include <promeki/namespace.h>
#include <promeki/sharedthreadmediaio.h>
#include <promeki/mediaiofactory.h>
#include <promeki/audiodatadecoder.h>
#include <promeki/imagedataencoder.h>
#include <promeki/imagedatadecoder.h>
#include <promeki/imagedesc.h>
#include <promeki/audiodesc.h>
#include <promeki/anctranslator.h>
#include <promeki/array.h>
#include <promeki/audiobuffer.h>
#include <promeki/buffer.h>
#include <promeki/framerate.h>
#include <promeki/timecode.h>
#include <promeki/mutex.h>
#include <promeki/list.h>
#include <promeki/ltcdecoder.h>
#include <promeki/string.h>
 
PROMEKI_NAMESPACE_BEGIN
 
struct InspectorDiscontinuity {
                enum Kind {
                        FrameNumberJump,
                        StreamIdChange,
                        PictureTcJump,
                        LtcTcJump,
                        ImageDataDecodeFailure,
                        LtcDecodeFailure,
                        SyncOffsetChange,
                        MissingVideoTimestamp,
                        MissingAudioTimestamp,
                        AudioTimestampReanchor,
                        VideoTimestampReanchor,
                        AudioChannelMismatch,
                        AudioDataDecodeFailure,
                        AudioDataLengthAnomaly,
 
                        KindCount
                };
 
                Kind   kind;          
                String previousValue; 
                String currentValue;  
                String description;   
};
 
struct InspectorEvent {
                FrameNumber frameIndex{0};
 
                // ---- Picture data band decode ----
 
                bool pictureDecoded = false;
                bool pictureDecoderEnabled = false;
                uint32_t pictureFrameNumber = 0;
                uint32_t pictureStreamId = 0;
                Timecode pictureTimecode;
 
                // ---- Audio LTC decode ----
 
                bool ltcDecoded = false;
                bool ltcDecoderEnabled = false;
                Timecode ltcTimecode;
                int64_t ltcSampleStart = 0;
 
                // ---- A/V Sync (marker-based, baseline-anchored) ----
 
                bool avSyncValid = false;
                int64_t avSyncOffsetSamples = 0;
 
                // ---- Timestamps (per-essence MediaTimeStamps) ----
 
                bool timestampTestEnabled = false;
                bool videoTimestampValid = false;
                bool audioTimestampValid = false;
                int64_t videoTimestampNs = 0;
                int64_t audioTimestampNs = 0;
                bool videoTimestampDeltaValid = false;
                bool audioTimestampDeltaValid = false;
                int64_t videoTimestampDeltaNs = 0;
                int64_t audioTimestampDeltaNs = 0;
 
                // ---- Audio sample count ----
 
                bool audioSamplesTestEnabled = false;
                bool audioSamplesValid = false;
                int64_t audioSamplesThisFrame = 0;
 
                // ---- Per-essence PTS jitter (continuous-stream model) ----
 
                bool audioPtsJitterValid = false;
                int64_t audioPtsJitterNs = 0;
                bool videoPtsJitterValid = false;
                int64_t videoPtsJitterNs = 0;
 
                // ---- A/V cross-essence PTS drift ----
 
                bool avPtsDriftValid = false;
                int64_t avPtsDriftNs = 0;
 
                // ---- Per-channel audio data marker decode ----
 
                struct AudioChannelMarker {
                                bool decoded = false;
                                bool channelMatches = false;
                                uint8_t streamId = 0;
                                uint8_t encodedChannel = 0;
                                uint64_t frameNumber = 0;
                                uint32_t packetsDecoded = 0;
                                uint32_t packetsCorrupt = 0;
                                int64_t streamSampleStart = -1;
                };
 
                bool audioDataDecoderEnabled = false;
                bool audioDataDecoded = false;
                List<AudioChannelMarker> audioChannelMarkers;
 
                // ---- Continuity ----
 
                List<InspectorDiscontinuity> discontinuities;
};
 
struct InspectorSnapshot {
                FrameCount framesProcessed{0};
                FrameCount framesWithPictureData{0};
                FrameCount framesWithLtc{0};
                FrameCount framesWithVideoTimestamp{0};
                FrameCount framesWithAudioTimestamp{0};
                int64_t videoDeltaSamples = 0;
                int64_t audioDeltaSamples = 0;
                int64_t videoDeltaMinNs = 0;
                int64_t videoDeltaMaxNs = 0;
                double videoDeltaAvgNs = 0.0;
                int64_t audioDeltaMinNs = 0;
                int64_t audioDeltaMaxNs = 0;
                double audioDeltaAvgNs = 0.0;
                double actualFps = 0.0;
                int64_t audioSamplesFrames = 0;
                int64_t audioSamplesMin = 0;
                int64_t audioSamplesMax = 0;
                double audioSamplesAvg = 0.0;
                int64_t audioSamplesTotal = 0;
                int64_t audioSamplesSpanNs = 0;
                double measuredAudioSampleRate = 0.0;
                int64_t totalDiscontinuities = 0;
                Array<int64_t, static_cast<size_t>(InspectorDiscontinuity::KindCount)>
                        discontinuitiesByKind{};
 
                // ---- Per-essence PTS jitter accumulators (jitter is
                // measured against the prediction; see
                // @ref InspectorEvent::audioPtsJitterNs and
                // @ref InspectorEvent::videoPtsJitterNs) ----
 
                int64_t audioPtsJitterSamples = 0;
                int64_t audioPtsJitterMinNs = 0;
                int64_t audioPtsJitterMaxNs = 0;
                double audioPtsJitterAvgNs = 0.0;
                int64_t audioReanchorCount = 0;
 
                int64_t videoPtsJitterSamples = 0;
                int64_t videoPtsJitterMinNs = 0;
                int64_t videoPtsJitterMaxNs = 0;
                double videoPtsJitterAvgNs = 0.0;
                int64_t videoReanchorCount = 0;
 
                // ---- A/V cross-stream PTS drift accumulators ----
 
                bool avBaselineSet = false;
                int64_t avBaselineOffsetNs = 0;
                int64_t avPtsDriftSamples = 0;
                int64_t avPtsDriftMinNs = 0;
                int64_t avPtsDriftMaxNs = 0;
                double avPtsDriftAvgNs = 0.0;
 
                bool hasLastEvent = false;
                InspectorEvent lastEvent;
};
 
class InspectorMediaIO : public SharedThreadMediaIO {
                PROMEKI_OBJECT(InspectorMediaIO, SharedThreadMediaIO)
        public:
                using EventCallback = Function<void(const InspectorEvent &)>;
 
                InspectorMediaIO(ObjectBase *parent = nullptr);
 
                ~InspectorMediaIO() override;
 
                void setEventCallback(EventCallback cb);
 
                InspectorSnapshot snapshot() const;
 
        protected:
                Error executeCmd(MediaIOCommandOpen &cmd) override;
                Error executeCmd(MediaIOCommandClose &cmd) override;
                Error executeCmd(MediaIOCommandWrite &cmd) override;
 
        private:
                void  decompressImages(Frame &frame);
                void  initDecoders(const Frame &frame);
                void  ingestAudio(const Frame &frame, InspectorEvent &event);
                void  runImageDataCheck(const Frame &frame, InspectorEvent &event);
                void  runAudioDataCheck(const Frame &frame, InspectorEvent &event);
                void  runLtcCheck(InspectorEvent &event);
                void  runAvSyncCheck(const Frame &frame, InspectorEvent &event);
                void  runContinuityCheck(InspectorEvent &event);
                void  runTimestampCheck(const Frame &frame, InspectorEvent &event);
                void  runAudioSamplesCheck(const Frame &frame, InspectorEvent &event);
                void  runCaptureStats(const Frame &frame, const InspectorEvent &event);
                void  runAncDataCheck(const Frame &frame, InspectorEvent &event);
                Error openCaptureStatsFile(const String &configured);
                void  closeCaptureStatsFile();
                Error openAncDataFile(const String &configured);
                void  closeAncDataFile();
                void  emitPeriodicLogIfDue();
                void  resetState();
 
                // ---- Configuration (resolved at open time) ----
                bool    _decodeImageData = false;
                bool    _decodeAudioData = false;
                bool    _decodeLtc = false;
                bool    _checkAvSync = false;
                bool    _checkContinuity = false;
                bool    _checkTimestamp = false;
                bool    _checkAudioSamples = false;
                bool    _checkCaptureStats = false;
                bool    _checkAncData = false;
                bool    _dropFrames = true;
                int     _imageDataRepeatLines = 16;
                int     _ltcChannel = 0;
                int     _syncOffsetToleranceSamples = 0;
                int64_t _audioPtsToleranceNs = 5'000'000;
                int64_t _videoPtsToleranceNs = 5'000'000;
                double  _logIntervalSec = 1.0;
                bool    _isOpen = false;
                double _videoFrameDurationNs = 0.0;
                FrameRate _frameRate;
                bool _frameRateConfirmed = false;
 
                // ---- Decoder state (constructed lazily on the first frame
                // because we need the actual ImageDesc and AudioDesc to
                // build them) ----
                ImageDataDecoder _imageDataDecoder;
                AudioDataDecoder _audioDataDecoder;
                LtcDecoder::UPtr _ltcDecoder;
                bool             _decodersInitialized = false;
 
                // ---- Video frame history (for marker-based A/V sync) ----
                //
                // Every successful @ref runImageDataCheck pushes a
                // record into this ring so the audio-side codeword
                // decode can look up the matching video frame's
                // wall-clock anchor by 48-bit frame number.  Bounded
                // at @ref kVideoFrameHistoryMax; older entries are
                // evicted from the front when the ring fills.
                struct VideoFrameRecord {
                                uint64_t frame48 = 0;
                                uint8_t streamId = 0;
                                int64_t videoWallNs = 0;
                };
                static constexpr size_t kVideoFrameHistoryMax = 64;
                List<VideoFrameRecord>  _videoFrameHistory;
 
                // ---- AudioData per-channel rolling accumulators ----
                //
                // Decoupled from the LTC-side @ref _audioStream so the
                // two decoders don't fight over the same FIFO and so
                // the data check can survive bursty audio that splits
                // a codeword across multiple chunks.  One @ref
                // AudioDataDecoder::StreamState per channel — owns the
                // per-channel rolling buffer and the absolute stream
                // sample anchor reported back through @ref
                // AudioDataDecoder::DecodedItem::streamSampleStart.
                List<AudioDataDecoder::StreamState> _audioDataStreamStates;
                // Per-channel "have I ever seen a clean decode on
                // this channel?" latch.  Anomaly discontinuities
                // (decode failure / length anomaly) only fire on
                // channels that have produced at least one valid
                // codeword — without this gate, channels that simply
                // don't carry PcmMarker (LTC, tones, silence) would
                // generate spurious anomalies whenever findSync's
                // 4-transition search happens to land on a samplesPerBit
                // inside the decoder's bandwidth gate.
                // Stored as @c uint8_t (0/1) rather than @c bool —
                // @c List<bool> wraps @c List<bool> whose
                // proxy references break the lvalue interfaces our
                // @c List wrapper exposes.
                List<uint8_t> _audioDataChannelActive;
 
                // ---- Audio stream (continuous-stream view of incoming
                // audio that decouples per-frame chunk boundaries from
                // analyses that want a real stream) ----
 
                AudioBuffer _audioStream;
                bool _audioStreamReady = false;
                double _audioSampleRate = 0.0;
                bool _audioStreamAnchored = false;
                int64_t _audioStreamStartNs = 0;
                int64_t _audioCumulativeIn = 0;
                int64_t _audioCumulativeAnalyzed = 0;
                Buffer _audioDrainScratch;
 
                // ---- Continuity tracking ----
                bool        _hasPreviousPicture = false;
                uint32_t    _previousFrameNumber = 0;
                uint32_t    _previousStreamId = 0;
                Timecode    _previousPictureTc;
                FrameNumber _previousFrameIndexAtDecode{0};
                bool        _hasPreviousLtc = false;
                Timecode    _previousLtcTc;
                Timecode::Mode _inferredPictureMode;
                bool    _hasPreviousSyncOffset = false;
                int64_t _previousSyncOffset = 0;
                bool    _avSyncBaselineSet = false;
                int64_t _avSyncBaselinePhase = 0;
                double _samplesPerFrame = 0.0;
 
                // ---- Timestamp test state (previous-frame anchors
                // needed to compute frame-to-frame deltas) ----
                bool    _hasPreviousVideoTimestamp = false;
                bool    _hasPreviousAudioTimestamp = false;
                int64_t _previousVideoTimestampNs = 0;
                int64_t _previousAudioTimestampNs = 0;
 
                // ---- Video PTS prediction anchor (for jitter / re-anchor) ----
                bool        _videoPtsAnchored = false;
                int64_t     _videoPtsAnchorNs = 0;
                FrameNumber _videoPtsAnchorFrame{0};
 
                // ---- A/V cross-PTS baseline for drift measurement.  Set
                // on the first frame that carries valid PTSs on both
                // essences. ----
                bool    _avBaselineSet = false;
                int64_t _avBaselineOffsetNs = 0;
                bool    _hasLastAudioPtsForAv = false;
                int64_t _lastAudioPtsForAvNs = 0;
 
                // ---- Per-frame counter ----
                FrameNumber _frameIndex{0};
 
                // ---- Stats accumulator ----
                mutable Mutex     _stateMutex;
                InspectorSnapshot _stats;
 
                // ---- Periodic log timing (wall time) ----
                double     _lastLogWallSec = 0.0;
                FrameCount _framesSinceLastLog{0};
 
                // ---- Per-frame callback ----
                EventCallback _callback;
 
                // ---- CaptureStats test output ----
                //
                // TSV with one row per frame.  @c _statsFile is opened
                // at @c open() time when the test is enabled and closed
                // at @c close().  @c _statsFilePath holds the resolved
                // path (caller-supplied or auto-generated inside
                // @c Dir::temp()).  @c _statsWriteError latches on the
                // first write failure so the inspector stops retrying
                // rather than spamming the log.
                FILE  *_statsFile = nullptr;
                String _statsFilePath;
                bool   _statsWriteError = false;
 
                // ---- AncData test output ----
                //
                // JSON Lines (one self-contained JSON object per frame)
                // covering every ANC packet on each incoming Frame.  Same
                // lifecycle and error-latching semantics as the
                // @c CaptureStats file.  Each row records the frame
                // index, per-packet format / transport / line / parsed
                // payload (via @ref AncTranslator) when a parser is
                // registered, plus an opaque hex dump fallback when not.
                FILE  *_ancDataFile = nullptr;
                String _ancDataFilePath;
                bool   _ancDataWriteError = false;
                FrameCount _ancDataFrameIndex{0};
                AncTranslator _ancTranslator;
};
 
class InspectorFactory : public MediaIOFactory {
        public:
                InspectorFactory() = default;
 
                String name() const override { return String("Inspector"); }
                String displayName() const override { return String("Frame Inspector"); }
                String description() const override {
                        return String("Sink that inspects each frame for continuity, sync, and decode "
                                      "tests, then drops it.");
                }
                bool canBeSink() const override { return true; }
 
                Config::SpecMap configSpecs() const override;
                MediaIO        *create(const Config &config, ObjectBase *parent = nullptr) const override;
};
 
PROMEKI_NAMESPACE_END
 
#endif // PROMEKI_ENABLE_PROAV