rfscope

type Analyzer interface {
	Name() string
	Synopsis() string
	DependsOn() []string
	Analyze(ctx context.Context, sc *Scene, in *Input) error
}

type Anomaly struct {
	Severity  string `json:"severity"` // "note" | "warn" | "alert"
	Kind      string `json:"kind"`     // "intermittent" | "hopper" | "wide-carrier" | …
	FreqHz    uint32 `json:"freq_hz,omitempty"`
	EmitterID uint64 `json:"emitter_id,omitempty"`
	Detail    string `json:"detail"`
}

type Bin struct {
	TSec       float64 `json:"t_sec"`
	PowerDbFS  float32 `json:"power_dbfs"`
	Occupied   bool    `json:"occupied"`
	BurstCount int     `json:"burst_count"`
}

type Burst struct {
	ID       uint64  `json:"id"`
	FreqHz   uint32  `json:"freq_hz"`
	StartSec float64 `json:"start_sec"`
	EndSec   float64 `json:"end_sec"`
	PeakDbFS float32 `json:"peak_dbfs"`
	SNRDb    float32 `json:"snr_db"`

	OccupiedBwHz     uint32  `json:"occupied_bw_hz"`
	ChannelPowerDBFS float64 `json:"channel_power_dbfs"`
	ACPRUpperDB      float64 `json:"acpr_upper_db"`
	ACPRLowerDB      float64 `json:"acpr_lower_db"`
	// SpectralFlatness is the Wiener entropy 0..1: ≈1 noise-like/spread, ≪1 a
	// tone or narrow carrier — a high-value protocol-agnostic discriminator.
	SpectralFlatness float64 `json:"spectral_flatness"`

	Class    survey.SignalClass   `json:"class"`
	Features survey.ClassFeatures `json:"features"`

	// EmitterID back-references the owning emitter once clustered (0 = none).
	EmitterID uint64 `json:"emitter_id,omitempty"`
}

type Channel struct {
	FreqHz          uint32             `json:"freq_hz"`
	OccupiedBwHz    uint32             `json:"occupied_bw_hz"`
	DominantClass   survey.SignalClass `json:"dominant_class"`
	BurstCount      int                `json:"burst_count"`
	AirtimeSec      float64            `json:"airtime_sec"`
	DutyCycle       float64            `json:"duty_cycle"`
	OccupancyPct    float64            `json:"occupancy_pct"`
	BurstRatePerMin float64            `json:"burst_rate_per_min"`
	MedianPowerDbFS float32            `json:"median_power_dbfs"`
	MedianFlatness  float64            `json:"median_flatness"`

	Timeline []Bin `json:"timeline,omitempty"`

	BurstLenHist     Hist    `json:"burst_len_hist"`
	InterArrivalHist Hist    `json:"inter_arrival_hist"`
	PeriodSec        float64 `json:"period_sec"`
	PeriodConfidence float64 `json:"period_confidence"`
}

type Conversation struct {
	ID          uint64   `json:"id"`
	EmitterIDs  []uint64 `json:"emitter_ids"`
	Kind        string   `json:"kind"`
	Correlation float64  `json:"correlation"`
	Exchanges   int      `json:"exchanges"`
}

type Emitter struct {
	ID              uint64      `json:"id"`
	Label           string      `json:"label"`
	Fingerprint     Fingerprint `json:"fingerprint"`
	BurstIDs        []uint64    `json:"burst_ids,omitempty"`
	FirstSec        float64     `json:"first_sec"`
	LastSec         float64     `json:"last_sec"`
	TotalAirtimeSec float64     `json:"total_airtime_sec"`
	// HopSet holds >1 frequency when the emitter is a frequency hopper.
	HopSet []uint32 `json:"hop_set,omitempty"`
}

type EntropyResult struct {
	EmitterID          uint64  `json:"emitter_id"`
	FreqHz             uint32  `json:"freq_hz"`
	Bytes              int     `json:"bytes"`
	Class              string  `json:"class"`
	Confidence         float64 `json:"confidence"`
	EntropyBits        float64 `json:"entropy_bits"`
	IndexOfCoincidence float64 `json:"index_of_coincidence"`
	ChiSquareUniform   float64 `json:"chi_square_uniform"`
	KeyLen             int     `json:"key_len,omitempty"`
	LooksRandom        bool    `json:"looks_random"`
	Recommended        string  `json:"recommended"`
	// contains filtered or unexported fields
}

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

type Fingerprint struct {
	CenterHz          uint32  `json:"center_hz"`
	OccupiedBwHz      uint32  `json:"occupied_bw_hz"`
	ClassFamily       string  `json:"class_family"`
	MedianPowerDbFS   float32 `json:"median_power_dbfs"`
	MedianBurstLenSec float64 `json:"median_burst_len_sec"`
	SpectralFlatness  float64 `json:"spectral_flatness"`
	PeriodSec         float64 `json:"period_sec"`
}

type Format int

type HierNode struct {
	Depth    int                `json:"depth"` // 0=class, 1=bandwidth bucket, 2=protocol candidate
	Label    string             `json:"label"`
	Class    survey.SignalClass `json:"class,omitempty"`
	Protocol string             `json:"protocol,omitempty"`
	Stats    HierStats          `json:"stats"`
}

type HierStats struct {
	EmitterCount int     `json:"emitter_count"`
	BurstCount   int     `json:"burst_count"`
	AirtimeSec   float64 `json:"airtime_sec"`
	SpectrumPct  float64 `json:"spectrum_pct"`
	TimePct      float64 `json:"time_pct"`
	SymbolVolume int64   `json:"symbol_volume"`
	ByteVolume   int64   `json:"byte_volume"`
}

type Hist struct {
	Counts []int     `json:"counts,omitempty"`
	Edges  []float64 `json:"edges,omitempty"`
}

type Input struct {
	// SampleRateHz is the capture's IQ sample rate.
	SampleRateHz float64
	// Window is the observation window in seconds (the scene's time span).
	Window float64
	// Log is the run logger; never nil (Run substitutes a discard logger).
	Log *slog.Logger
	// BurstIQ returns the decimated baseband IQ of one burst and its rate, or an
	// error if the source can no longer be read. Analyzers that only need the
	// burst metadata (timeline, timing) ignore it; classifiers/identifiers call
	// it on demand.
	BurstIQ func(b Burst) (iq []complex64, rateHz float64, err error)
}

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

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

type ProtocolHierarchy struct {
	Total HierStats  `json:"total"`
	Nodes []HierNode `json:"nodes,omitempty"`
}

type Scene struct {
	Source     string    `json:"source"`
	StartedAt  time.Time `json:"started_at"`
	FinishedAt time.Time `json:"finished_at"`
	CenterHz   uint32    `json:"center_hz"`
	SpanHz     uint32    `json:"span_hz"`
	// WindowSec is the observation window: how much signal time the scene covers.
	WindowSec float64 `json:"window_sec"`
	// NoiseFloorDbFS is the scene-wide robust noise floor (spectrum.Percentile).
	NoiseFloorDbFS float32 `json:"noise_floor_dbfs"`

	Bursts        []Burst           `json:"bursts,omitempty"`
	Channels      []Channel         `json:"channels,omitempty"`
	Emitters      []Emitter         `json:"emitters,omitempty"`
	Conversations []Conversation    `json:"conversations,omitempty"`
	Hierarchy     ProtocolHierarchy `json:"hierarchy"`
	Anomalies     []Anomaly         `json:"anomalies,omitempty"`

	AnalyzerOutputs map[string]any `json:"analyzer_outputs,omitempty"`
}

type SegmentConfig struct {
	// FFTSize is the wideband FFT used for carrier discovery (power of two).
	FFTSize int
	// ChannelTargetRateHz is the per-channel decimated baseband rate the
	// downconverter targets. ~50 kHz comfortably holds any land-mobile / IoT
	// narrowband channel while keeping per-burst buffers small.
	ChannelTargetRateHz float64
	// PeakThresholdDb / MinSpacingHz tune carrier discovery (carriers.DetectPeaks).
	PeakThresholdDb float32
	MinSpacingHz    uint32
	// MaxChannels caps how many discovered carriers are analyzed (strongest first).
	MaxChannels int
	// EnvelopeRateHz is the per-channel power-envelope frame rate the onset state
	// machine runs at. Higher resolves shorter bursts at more CPU.
	EnvelopeRateHz float64
	// OnThreshDb/OffThreshDb/Debounce/NoiseAlpha are the onset state-machine knobs,
	// lifted from the DMR onset detector.
	OnThreshDb  float64
	OffThreshDb float64
	Debounce    int
	NoiseAlpha  float64
	// MinBurstSec drops bursts shorter than this (debounce noise).
	MinBurstSec float64
	// MaxSamples caps how many wideband samples are read (0 = whole capture). The
	// CLI sets this from a -window/-duration flag.
	MaxSamples int
	// Now stamps the scene; nil ⇒ time.Now.
	Now func() time.Time
}

type Source interface {
	// Next returns the next chunk of up to n complex samples. The returned slice
	// may be shorter than n only at end-of-stream; an empty slice with io.EOF
	// marks the end. ctx cancellation is honored.
	Next(ctx context.Context, n int) ([]complex64, error)
	// CenterHz is the source's absolute center frequency.
	CenterHz() uint32
	// SampleRateHz is the IQ sample rate.
	SampleRateHz() float64
}