callharness

type AnswerFacts struct {
	SDP        string
	ICELite    bool     // a=ice-lite at session level
	Bundle     []string // MIDs in a=group:BUNDLE
	RTCPMux    bool     // every accepted m-line has a=rtcp-mux
	Candidates []string // every a=candidate value

	// Media are the answer's m-lines in order.
	Media []AnswerMedia
}

type AnswerMedia struct {
	Kind string // "audio", "video", "application", ...
	MID  string
	Port int // 0 when the answer rejects the m-line

	// Formats are the payload types; Codecs are their a=rtpmap values (for
	// example "opus/48000/2"), and RTCPFeedback the a=rtcp-fb values.
	Formats      []string
	Codecs       []string
	RTCPFeedback []string
}

type Call struct {
	// contains filtered or unexported fields
}

type CallOptions struct {
	// Freshness configures the caller's bounded recovery evaluation.
	// Defaults stay strict (2s recovery + 3s stability), including under race.
	// Acceptance callers such as #27 can set RecoveryLimit: 2*time.Second
	// explicitly and use RequireFreshnessRecovered with the required policy
	// (StrictAcceptancePolicy by default) without race. Phase-1
	// scenarios report freshness without gating it, with or without race.
	// These defaults and measured recovery times remain strict. Allow
	// enough media to observe Freshness.EvaluationWindow().
	Freshness FreshnessPolicy
	// SendTiming observes each successful RTP socket write. It must be fast
	// and safe for concurrent audio/video sends. Scheduled is the delivered
	// tick that triggered the frame; actual is after the UDP write.
	SendTiming func(kind string, scheduled, actual time.Time)
	// SendPacing counts successful frames and dropped ticker opportunities.
	// Video fragments count as one frame. The callback must be concurrent-safe.
	SendPacing func(kind string, sent, skipped uint64)
	Recording  RecordingOptions
	// SRTPDiagnostics authenticates a separate copy of received media for
	// bounded packet/index diagnostics. It never changes Pion's accounting.
	SRTPDiagnostics bool

	// InitialSequenceNumbers replaces random RTP starts for wrap tests. Nil
	// keeps Pion's random starts. Both tracks keep their normal packetizers.
	InitialSequenceNumbers *RTPSequenceNumbers

	// Video adds a VP8 video track next to the Opus audio track, on the same
	// bundled connection.
	Video bool
	// VideoData optionally supplies a VP8 IVF fixture. Nil uses the embedded
	// 320x240/30 fps fixture (natural keyframe interval one second).
	VideoData []byte

	// BrowserLikeOffer makes the caller offer what a browser offers rather
	// than just the codecs it sends: every codec Pion knows (VP8, VP9, H264,
	// H265 and AV1, each with RTX), RED, ULPFEC, telephone-event and comfort
	// noise, extra RTP header extensions, and an RTX ssrc-group for video.
	BrowserLikeOffer bool

	// Worker is the index of the media worker that takes the call (see
	// Options.Workers); 0 is the first in an owned topology.
	// In external mode the number is the literal registration name: the zero
	// value CallOptions{} pins to "0", which must exist.
	// -1 leaves placement unpinned on relay/control-plane topologies.
	Worker int
}

type CandidatePairChecks struct {
	Local             string        `json:"local"`
	Remote            string        `json:"remote"`
	ChecksSent        uint64        `json:"checks_sent"`
	ResponsesReceived uint64        `json:"responses_received"`
	FirstCheck        time.Duration `json:"first_check_ns,omitempty"`
	LastCheck         time.Duration `json:"last_check_ns,omitempty"`
	LastResponse      time.Duration `json:"last_response_ns,omitempty"`
}

type ClockProbe struct {
	CallerSend    time.Time `json:"caller_send"`
	CallerReceive time.Time `json:"caller_receive"`
	ServerReceive time.Time `json:"server_receive"`
	ServerSend    time.Time `json:"server_send"`
}

type ClockRateInterval struct {
	LowerPPM float64 `json:"lower_ppm"`
	UpperPPM float64 `json:"upper_ppm"`
}

type ClockTracker struct {
	// contains filtered or unexported fields
}

type ConsentReport struct {
	// RequestsSent and ResponsesReceived are the totals until hangup.
	RequestsSent      uint64
	ResponsesReceived uint64

	// Since is when the window below starts: the end of the last move, or
	// when the call connected if nothing moved. ObservedFor runs from there
	// to hangup, or to when the caller's connection closed or failed if that
	// came first.
	Since       time.Duration
	ObservedFor time.Duration

	// ResponsesAfter counts responses received in the window, and
	// LongestWithoutResponse is the longest stretch of it without a new
	// response, the stretch from the last response to the end of the window
	// included. The caller checks every 2 s; with no packet at all for 5 s
	// its connection goes "disconnected".
	ResponsesAfter         uint64
	LongestWithoutResponse time.Duration
}

type ContentDelivery struct {
	Sent, Returned, Lost, Unsettled int
	LostAt                          []time.Duration
	LostOverflow                    int
}

type ContentLossCounts struct {
	Sent, Lost     int
	Trusted        bool
	LongestLostRun int
	RunTrusted     bool
}

type ContentLossEvidence struct {
	Event     ContentLossWindow
	Baselines []ContentLossWindow
}

type ContentLossWindow struct {
	Start, End   time.Duration
	Audio, Video ContentLossCounts
}

type DecodeFailure string

type DecryptionFailures struct {
	AuthTag int // authentication tag did not verify (wrong key, index or rollover counter)
	Replay  int // rejected by the replay window
	Other   int
}

type DialError struct {
	Report DialReport
	// contains filtered or unexported fields
}

type DialReport struct {
	Outcome string `json:"outcome"`
	// Failure is the kind of a failed dial (DialFailure*); empty if the
	// dial connected. Error is the dial's error.
	Failure string `json:"failure,omitempty"`
	Error   string `json:"error,omitempty"`
	// Session is the call's session ID, the server's ICE username fragment;
	// empty if no answer was applied.
	Session string `json:"session,omitempty"`
	// Elapsed is when the dial connected or failed.
	Elapsed time.Duration `json:"elapsed_ns"`

	// The ICE, DTLS and PeerConnection states when the dial connected or
	// failed, and every change of each before then.
	ICEState         string        `json:"ice_state"`
	DTLSState        string        `json:"dtls_state"`
	ConnectionState  string        `json:"connection_state"`
	ICEStates        []StateChange `json:"ice_states"`
	DTLSStates       []StateChange `json:"dtls_states"`
	ConnectionStates []StateChange `json:"connection_states"`

	// CandidatePairs counts the caller's connectivity checks on each
	// candidate pair, as observed on the caller's socket.
	CandidatePairs []CandidatePairChecks `json:"candidate_pairs"`
}

type DistributedEvent struct {
	Identity  OperationIdentity       `json:"identity"`
	Kind      string                  `json:"kind"`
	Start     time.Time               `json:"start"`
	End       time.Time               `json:"end"`
	Result    controlplane.MoveResult `json:"result"`
	Uncertain bool                    `json:"uncertain,omitempty"`
}

type DistributedGap struct {
	BaselinePossible []time.Duration `json:"baseline_possible_ns"`
	BaselineCertain  []time.Duration `json:"baseline_certain_ns"`

	Kind        string           `json:"kind"`
	BaselineP95 DurationInterval `json:"baseline_p95"`
	EventGap    DurationInterval `json:"event_gap"`
	Outcome     string           `json:"outcome"`
	Causes      []string         `json:"causes,omitempty"`
}

type DistributedMeasurement struct {
	Durations map[string]DurationInterval `json:"durations,omitempty"`
	// Evaluations counts start/end/floor cells, each checked against all first baselines.
	Evaluations    int              `json:"evaluations"`
	FirstBaselines []FirstBaselines `json:"first_baselines,omitempty"`
	BaselineFloor  DurationInterval `json:"baseline_floor"`

	Mapped bool `json:"mapped"`

	AudioLoss MetricVerdict `json:"audio_loss"`
	VideoLoss MetricVerdict `json:"video_loss"`

	WindowOutcome string `json:"window_outcome"`

	Start      TimeInterval      `json:"start"`
	End        TimeInterval      `json:"end"`
	KillToLive *DurationInterval `json:"kill_to_live,omitempty"`
	Gaps       []DistributedGap  `json:"gaps"`
	Outcome    string            `json:"outcome"`
	Causes     []string          `json:"causes,omitempty"`
}

type DistributedOptions struct {
	RunID string
	Clock *ClockTracker
	// Host minus frontend offsets. These are measured input bounds, not a
	// claim that /clock observes control or worker time.
	ControlOffset OffsetInterval
	WorkerOffset  OffsetInterval
}

type DistributedRecording struct {
	ObservedRate *ClockRateInterval `json:"observed_rate_ppm,omitempty"`
	DriftPPM     float64            `json:"drift_ppm"`

	Armed   []OperationIdentity `json:"armed"`
	Missing []OperationIdentity `json:"missing_receipts,omitempty"`

	RunID         string         `json:"run_id"`
	ControlOffset OffsetInterval `json:"control_offset"`
	WorkerOffset  OffsetInterval `json:"worker_offset"`
	Probes        []ClockProbe   `json:"probes"`
	ClockError    string         `json:"clock_error,omitempty"`
	Outcome       string         `json:"outcome"`
	Causes        []string       `json:"causes,omitempty"`
}

type DurationInterval struct {
	Lower time.Duration `json:"lower_ns"`
	Upper time.Duration `json:"upper_ns"`
}

type EventMeasurement struct {
	ContentLoss                                                   ContentLossEvidence
	FirstContentIdentity, FirstNewContentIdentity                 uint64
	VideoExpected                                                 bool
	AudioPause, VideoPause                                        time.Duration
	WindowStart, WindowEnd, SettledAt, ObservedUntil              time.Duration
	SettleWindow                                                  time.Duration
	LostAudio, LateAudio                                          time.Duration
	LostVideoFrames, LateVideoFrames                              int
	AudioLoss, VideoLoss                                          MetricVerdict
	Audio, Video                                                  FreshnessReport
	MediaResumedAt                                                time.Duration
	ResumeVerdict                                                 MetricVerdict
	FirstLiveFrame, FirstNewFrame                                 time.Duration
	FirstContent, FirstNewContent                                 string
	FirstContentPictureID, FirstNewContentPictureID               uint16
	FirstContentSentAt, FirstNewContentSentAt                     time.Duration
	FirstContentVerdict, FirstNewContentVerdict, FirstLiveVerdict MetricVerdict
	DecodedFrames                                                 int
	DecodedSamples                                                int
	Inconclusive, Failed                                          bool
	Reasons                                                       []string
}

type ExternalTopology struct {
	Distributed *DistributedOptions

	SignalingURL string
	RelayAddr    netip.AddrPort
	// HTTPClient supplies signaling and control requests, including status and
	// hangup. Nil uses the ordinary ten-second client. The caller owns the
	// client and its transport; the harness neither changes nor closes them.
	HTTPClient *http.Client
	// CallerSocket creates the caller's UDP4 media socket. Nil preserves the
	// loopback socket and candidates. A supplied socket must bind a specific
	// IPv4 address; the harness owns and closes it. Signaling stays separate.
	CallerSocket func() (net.PacketConn, error)
	// Status optionally supplies a shared status view for external callers.
	// Nil keeps the ordinary per-call HTTP reads and local harness behavior.
	Status func(context.Context) (controlplane.Status, error)
	// FinalStatus optionally refreshes the shared status view at Hangup with
	// a final-collection timeout. Nil preserves the ordinary Status path.
	FinalStatus func(context.Context) (controlplane.Status, error)
}

type FirstBaselines struct {
	Audio FreshnessBaseline `json:"audio"`
	Video FreshnessBaseline `json:"video"`
}

type FreshnessBaseline struct {
	Samples int           `json:"samples"`
	Median  time.Duration `json:"median_ns"`
	P95     time.Duration `json:"p95_ns"`
}

type FreshnessPolicy struct {
	RecoveryLimit, StabilityWindow          time.Duration
	AbsoluteLatencyCeiling, LiveLatenessCap time.Duration
}

type FreshnessReport struct {
	Verdict                                            MetricVerdict
	RecoveryLimit, StabilityWindow, EvaluationEnd      time.Duration
	StabilityObserved                                  time.Duration
	AbsoluteLatencyCeiling, LiveLatenessCap            time.Duration
	AbsoluteLag                                        bool
	LateWindowUnits, LateWindowLimit, LatePercentLimit int
	LiveUnits, LateLiveUnits                           int
	JitterUnits                                        int
	JitterMaxExcess                                    time.Duration
	FirstBaselineTrusted                               bool
	LastAboveTolerance                                 time.Duration
	FirstBaselineSamples                               int
	FirstBaselineMedian, FirstBaselineP95              time.Duration
	LastingLag                                         bool
	BaselineStart                                      time.Duration
	BaselineSamples, PostEventSamples                  int
	BaselineMedian, BaselineP95                        time.Duration
	PeakLatency, PeakAboveBaseline                     time.Duration
	BackToBaseline                                     time.Duration
	Recovered                                          bool
	Tolerance                                          time.Duration
	SustainedUnits                                     int
	SpreadLimit                                        time.Duration
}

type FullDecode struct {
	// Skipped says why the decode did not finish (for example, a timeout or
	// ffmpeg not on PATH); empty when it completed.
	Skipped string

	Decoder       string // the ffmpeg binary
	FramesIn      int    // frames given to the decoder
	FramesDecoded int    // frames the decoder output
	Errors        string // the decoder's error output; empty when clean
	Failure       DecodeFailure
}

type HandoverOptions struct {
	// To is the index of the worker that takes the call over (0 is the
	// worker calls start on).
	To int

	// SequenceMargin moves the echoed tracks' sequence numbers forward by
	// this much across the move; see mediaworker.ResumeOptions. Zero, the
	// right value for a planned handover, keeps them continuous.
	SequenceMargin uint16
}

type Harness struct {
	// contains filtered or unexported fields
}

type KeyframeRequest int

type LongRunOptions struct {
	Duration, EventEvery, SampleEvery time.Duration
	Event                             func(context.Context, int) error
	HeapAfterGC                       bool
	ObserveMemory                     func(MemorySample)
}

type LongRunReport struct {
	Call           *Report
	Memory         []MemorySample
	SamplesDropped int
}

type MediaGap struct{ EndedAt, Duration time.Duration }

type MemorySample struct {
	At        time.Duration
	HeapAlloc uint64
	Recording RecordingReport
}

type MetricVerdict struct {
	Trusted, Failed bool
	Reasons         []string
}

type MoveReport struct {
	Receipt *DistributedEvent `json:"receipt,omitempty"`

	Identity    *OperationIdentity      `json:"identity,omitempty"`
	Distributed *DistributedMeasurement `json:"distributed,omitempty"`

	Lost      bool   `json:"lost,omitempty"`
	LossCause string `json:"loss_cause,omitempty"`
	// Recovery measures video recovery from the caller's first post-margin RTP
	// packet, including replay received while ResumeSession is still returning.
	Recovery VideoRecovery

	// Measurement is the caller content yardstick, independent of sequence
	// margins and of the system account in Result.
	Measurement EventMeasurement

	Kind          string        // "move" or "takeover"
	DetectionTime time.Duration // failure action to control-plane detection

	DecryptionFailuresAfterResume int
	From, To                      int // worker indexes

	// Start and End bracket the handover call, as offsets from dialing.
	Start, End time.Duration

	// Error is the handover's error; empty when it succeeded.
	Error string

	// Result is the system's account of the move: exported state size,
	// caller packets held and timings.
	Result mediaworker.HandoverResult

	// Tracks describe each received track around the move.
	Tracks []MoveTrackReport
	// contains filtered or unexported fields
}

type MoveTrackReport struct {
	Kind string

	// Gap is the longest interval between consecutive packets around the
	// move: the media gap the move caused. TypicalInterval is the track's
	// median interval between packets, for comparison.
	BaselineGapP95     time.Duration
	BaselineGapSamples int
	Gap                time.Duration
	TypicalInterval    time.Duration

	// SkippedSequenceNumbers counts sequence numbers missing around the
	// move: a sequence margin's jump, or lost packets.
	SkippedSequenceNumbers int

	// LargestTimestampStep is the largest RTP timestamp step between
	// consecutive packets around the move; TypicalTimestampStep is the
	// track's median step between packets of different frames. With
	// continuous timestamps the first is no larger than one frame's step.
	LargestTimestampStep uint32
	TypicalTimestampStep uint32

	// PacketsAfter counts packets that arrived after the move ended.
	PacketsAfter int

	// FirstDecodableFrameAfter is, for video, the time from the end of the
	// move to the first decodable frame after it; zero if none arrived.
	FirstDecodableFrameAfter time.Duration
	// contains filtered or unexported fields
}

type OffsetInterval struct {
	Lower time.Duration `json:"lower_ns"`
	Upper time.Duration `json:"upper_ns"`
}

type OnlineDecodeReport struct {
	Every                                                         int
	Sampled, Decoded, UniqueDecoded, Errors, Dropped, Unavailable int
	LastError                                                     string
}

type OperationIdentity struct {
	RunID       string `json:"run_id"`
	OperationID string `json:"operation_id"`
	SessionID   string `json:"session_id"`
	Worker      string `json:"worker"`
	Epoch       uint64 `json:"epoch"`
}

type Options struct {
	// External selects a process topology instead of starting local workers.
	External *ExternalTopology

	// WorkerLoggerFactory is passed to the media workers (and the relay).
	// Defaults to Pion's default logger factory (PION_LOG_* environment
	// variables).
	WorkerLoggerFactory logging.LoggerFactory

	// Workers is how many media workers run. Without Relay, one (the
	// default) owns its UDP socket; two or more share one UDP socket, calls
	// start on the first, and Call.Handover moves a call between them.
	// With Relay, each worker owns a private socket behind the relay, and a
	// call picks its worker with CallOptions.Worker. Call.Handover uses the
	// control plane to transfer ownership and re-point the relay.
	Workers int

	// Relay runs every call through a relay with a session-owner store
	// (Memory by default): answers advertise the relay's public address, and the workers
	// bind only private sockets behind it.
	Relay bool
	// SessionStore selects the relay topology's store. Nil uses Memory.
	// The caller owns its lifetime; it must outlive Harness.Close.
	SessionStore sessionstore.Store
	// FrameCache selects a shared cache, including Redis. Nil uses Memory.
	// The caller owns its lifetime and must keep it open through Harness.Close.
	FrameCache framecache.Store
	// SnapshotInterval sets the worker snapshot cadence for crash tests.
	// TakeoverConfig overrides control-plane bounds for fault scenarios.
	TakeoverConfig   controlplane.Config
	SnapshotInterval time.Duration
	// DisableFrameCache and DisableResumePLI independently select the video
	// recovery paths. Both paths are enabled by default.
	DisableFrameCache bool
	DisableResumePLI  bool
	// ReplayMaxBurstDuration overrides the worker's one-frame replay cap.
	ReplayMaxBurstDuration time.Duration
}

type RTPSequenceNumbers struct {
	Audio uint16
	Video uint16
}

type RecordingOptions struct {
	History     time.Duration
	DecodeEvery int
	// MaintenancePhase delays the call's one-second recording maintenance
	// (automatic event discovery and history pruning) by this much, so it
	// runs at connect + phase + k seconds. Zero keeps connect + k seconds.
	// Load generators give each call its own phase in [0, 1s), so many
	// callers do not run this work on the same instant (#85).
	MaintenancePhase time.Duration
}

type RecordingReport struct {
	History                                                      time.Duration
	HistoryStart                                                 time.Duration
	Packets, ContentUnits, Assemblies, FrameMarks, OfflineFrames int
	EventSummaries                                               int
	DecodedPictures                                              int
	HistoryBytes                                                 int64
	Delivery                                                     *WholeCallDelivery `json:",omitempty"`
}

type Report struct {
	// ReportBuildDuration measures evidence snapshot, evaluation and judgment.
	// It excludes call teardown, optional offline decoding and JSON transport.
	ReportBuildDuration time.Duration         `json:"report_build_duration_ns,omitempty"`
	Distributed         *DistributedRecording `json:"distributed,omitempty"`

	Recording RecordingReport
	// StartedAt aligns packet observations across calls sharing a worker.
	StartedAt time.Time
	// OfferAnswerExchanges counts the HTTP offer/answer exchanges the caller
	// made to start the call.
	OfferAnswerExchanges int

	// Offer is the caller's SDP offer, and Answer describes the SDP answer
	// the caller received.
	Offer  string
	Answer AnswerFacts

	// RemoteAddr is the remote end ("ip:port") of the caller's selected ICE
	// candidate pair at hangup: the one address the caller sent to and
	// accepted media from.
	RemoteAddr string

	// ConnectedAt is when the caller's connection state first reached
	// "connected"; zero if it never did.
	ConnectedAt time.Duration
	// HungUpAt is when the caller hung up.
	HungUpAt time.Duration

	// ConnectionStates and ICEConnectionStates are the caller's
	// PeerConnection and ICE connection state changes up to hangup.
	ConnectionStates    []StateChange
	ICEConnectionStates []StateChange

	// DecryptionFailures counts SRTP and SRTCP packets the caller received
	// but could not decrypt.
	DecryptionFailures DecryptionFailures
	// SRTPDiagnostics is optional independent packet evidence. DecryptionFailures
	// remains the authoritative rejection count from Pion.
	SRTPDiagnostics *SRTPDiagnosticReport `json:",omitempty"`

	// Renegotiations counts offer/answer rounds (or negotiationneeded events)
	// after the initial exchange. ICERestarts counts ICE restarts: ICE going
	// back to checking after it connected, or changed ICE credentials.
	Renegotiations int
	ICERestarts    int

	// SentAudio and SentVideo are the caller's own tracks. SentVideo is the
	// zero value for a call without video. FirstVideoSentAt is when the
	// caller sent its first video frame.
	SentAudio        SentTrack
	SentVideo        SentTrack
	FirstVideoSentAt time.Duration

	// KeyframeRequestsSent counts the PLI and FIR packets the caller sent for
	// the echoed video (see Call.RequestKeyframe).
	KeyframeRequestsSent int

	// Tracks are the tracks the caller received, in arrival order.
	Tracks []TrackReport

	// Moves are planned handovers and automatic crash takeovers during the call,
	// as the caller observed them. Consent is what the caller observed of
	// its ICE consent checks. See handover.go.
	Moves   []MoveReport
	Consent ConsentReport
}

type SRTPDiagnosticReport struct {
	Ready          bool
	Unavailable    string `json:",omitempty"`
	Packets        uint64
	Skipped        uint64
	Failures       DecryptionFailures
	Samples        []SRTPFailureSample
	SamplesOmitted uint64
}

type SRTPFailureSample struct {
	At                 time.Duration
	Protocol           string
	SSRC               uint32
	Sequence           uint16 `json:",omitempty"`
	Timestamp          uint32 `json:",omitempty"`
	PayloadType        uint8  `json:",omitempty"`
	EstimatedIndex     uint64
	PreviousIndex      uint64
	PreviousIndexKnown bool
	AuthenticatedIndex *uint64 `json:",omitempty"`
	CiphertextSHA256   string
	Bytes              int
	Error              string
}

type SentTrack struct {
	SSRC uint32
	// Frames counts the frames sent: Opus packets for audio (one frame per
	// packet), VP8 frames for video. Keyframes counts VP8 keyframes.
	Frames    int
	Keyframes int
	// KeyframeRequests counts the PLI and FIR packets the caller received
	// for this track's SSRC.
	KeyframeRequests int
}

type StateChange struct {
	At    time.Duration
	State string
}

type TimeInterval struct {
	Earliest time.Time `json:"earliest"`
	Latest   time.Time `json:"latest"`
}

type TrackReport struct {
	MediaGaps         []MediaGap
	MediaGapsRecorded bool
	MediaGapOverflow  int
	Kind              string
	SSRC              uint32
	PayloadType       uint8

	// Packets counts all packets the caller decrypted on this track.
	// Arrivals holds the rolling history named by Report.Recording.
	Packets      int
	Arrivals     []time.Duration
	FirstArrival time.Duration
	LastArrival  time.Duration

	// MediaGap is the longest interval between consecutive successfully
	// decrypted packets on the track; MediaGapEndedAt is when it ended.
	MediaGap        time.Duration
	MediaGapEndedAt time.Duration

	// SequenceDiscontinuities counts packets whose sequence number does not
	// follow the previous packet's.
	SequenceDiscontinuities int

	// DuplicatePackets and OutOfOrderPackets distinguish stale sender traffic
	// from forward sequence gaps caused by lost packets.
	DuplicatePackets  int
	OutOfOrderPackets int
	// UnmatchedPayloads counts audio packets whose payload is not one the
	// caller sent, i.e. packets that are not an echo of the caller's media.
	// Video is matched frame by frame instead (VideoReport.UnmatchedFrames).
	UnmatchedPayloads int

	// Video describes the frames of a video track; nil for audio.
	Video *VideoReport
}

type VideoRecovery struct {
	// SourceVideoSkippedSequenceNumbers measures the old-live to new-live
	// sequence gap excluding inserted replay packets. The first replay index
	// uses a stale snapshot, so its observed jump can be smaller than the
	// margin; the resumed source stream must still carry the full margin.
	SourceVideoSkippedSequenceNumbers int
	ReplayPackets                     int

	// CachedPictureIDs includes even incomplete replayed frames, identified
	// from received RTP payload descriptors after media resumed. This proves
	// an interrupted keyframe's packets were never replayed.
	CachedPictureIDs []uint16
	MediaResumedAt   time.Duration
	// Both common-start metrics begin at the kill, for every mode. Cached
	// output can precede control-plane completion, so completion is unsuitable.
	FirstDecodedAfterKill time.Duration
	// FirstDecodedRepeated says the first returned decodable picture reuses
	// a prior decode. Its cache provenance is known, but no new decode ran.
	FirstDecodedRepeated bool
	// FirstDecodedLiveAfterKill measures a decoded frame sent at/after
	// MediaResumedAt, and is zero when no such live frame decoded.
	FirstDecodedLiveAfterKill time.Duration
	LivePath                  string
	// FirstDecodedPLIAfterKill measures the first newly decoded response to a
	// keyframe request received by the caller at/after the kill. It is zero
	// without that evidence, even when a natural keyframe restores video first.
	FirstDecodedPLIAfterKill     time.Duration
	KeyframeInterval             time.Duration
	FirstDecodedAfterMediaResume time.Duration
	FrameInterval                time.Duration
	WithinFrameInterval          bool
	Path                         string // "Cache", "Keyframe", "Live", or empty if no decoded frame
	PictureID                    uint16
	FrameSentAt                  time.Duration
}

type VideoReport struct {
	OnlineDecode OnlineDecodeReport
	// Frames counts complete frames (every packet, in order, ending with the
	// marker bit). IncompleteFrames counts frames that lost packets.
	Frames           int
	Keyframes        int
	IncompleteFrames int
	// RepeatedFrames counts exact pictures already decoded. They remain
	// complete receipts, but are excluded from decoder inputs and samples.
	RepeatedFrames int
	// FrameGaps counts complete frames that did not directly follow the
	// previous complete frame: frames were lost or reordered between them.
	FrameGaps int
	// NonMonotonicTimestamps counts complete frames whose RTP timestamp did
	// not advance from the previous complete frame (modulo the RTP clock).
	NonMonotonicTimestamps int
	// UnmatchedFrames counts frames that are not byte for byte a frame the
	// caller sent.
	UnmatchedFrames int

	// KeyframesDecoded counts keyframes decoded in pure Go;
	// KeyframeDecodeErrors counts keyframes that failed, the last with
	// LastDecodeError.
	KeyframesDecoded     int
	KeyframeDecodeErrors int
	LastDecodeError      string

	// DecodableFrames counts unique frames that decode: decoded keyframes, and
	// interframes in an unbroken run of complete frames since one.
	// FramesBeforeFirstKeyframe counts frames that arrived before any
	// keyframe decoded (a receiver waits for a keyframe). UndecodableFrames
	// counts later frames whose references were lost.
	DecodableFrames           int
	FramesBeforeFirstKeyframe int
	UndecodableFrames         int

	// FirstDecodedFrameAt is when the first frame decoded; zero if none did.
	// Width and Height are that keyframe's size.
	FirstDecodedFrameAt time.Duration
	Width, Height       int

	// FullDecode is ffmpeg's complete short-call check. Long calls select
	// OnlineDecode; offline history is capped and a truncated check is skipped.
	FullDecode FullDecode
}

type WholeCallDelivery struct {
	Audio, Video ContentDelivery
}