ccdecoder

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

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

type FECObserver interface {
	RecordTetraViterbiCorrections(system, channel string, corrections int)
}

type IQPowerObserver interface {
	RecordIQPowerDbFS(system string, dbfs float64)
	ClearIQPowerDbFS(system string)
	RecordIQDCRatioDb(system string, ratioDb float64)
	ClearIQDCRatioDb(system string)
	RecordIQClipRatio(system string, ratio float64)
	ClearIQClipRatio(system string)
	// RecordDecodeOverrun counts one IQ chunk dropped at the decode queue
	// because decode could not keep up with real time (issue #402). It is
	// distinct from the SDR driver's iq_underruns_total: a non-zero value
	// here means the CPU/host can't sustain the decode, not that the USB
	// delivery channel overran.
	RecordDecodeOverrun()
}

type IQSource interface {
	StreamIQ(ctx context.Context) (<-chan []complex64, error)
}

type Options struct {
	Bus     *events.Bus
	Log     *slog.Logger
	Tuner   Tuner    // currently unused but kept for API symmetry with cchunt
	IQ      IQSource // control SDR providing the live IQ stream
	Systems []trunking.System
	// SampleRateHz is the raw SDR IQ stream rate (e.g. 2_048_000).
	// The decoder's digital down-converter decimates it to a
	// narrowband channel rate (~48 kHz for most protocols); the
	// per-protocol receiver factories are handed that decimated
	// rate, not this one, so they size their matched filters for
	// the channelized stream.
	SampleRateHz float64
	// Metrics is the optional IQ-power observer the pump updates
	// once per iqPowerWindow. Nil disables the gauge but leaves the
	// low-power debug log in place — operators without Prometheus
	// still get a hint when the dongle goes silent.
	Metrics IQPowerObserver
	// FEC is the optional FEC correction-depth observer. Nil (the
	// default) disables the per-protocol FEC histograms; the daemon
	// supplies it only when metrics.detailed_fec is enabled.
	FEC FECObserver
	// IQCorrect enables blind I/Q-imbalance correction on the raw IQ
	// before decimation (issue #402). Off by default; opt-in per device
	// via config. Validate with `replay -iq-correct -diag` on a capture
	// before enabling in production.
	IQCorrect bool
	// Conjugate negates the imaginary part of every raw IQ sample before
	// channelization, undoing a spectrum-inverted / I-Q-swapped front end
	// (issue #264, the same correction as `replay -conjugate`). Off by
	// default; opt-in per device via config (iq_invert). A π/4-DQPSK
	// protocol such as TETRA cannot lock an inverted spectrum because the
	// inversion reverses every differential phase transition.
	Conjugate bool
	// LOOffsetHz is the live LO-offset (DC-spike-avoidance) tuning the daemon
	// applies on the control SDR (issue #402). The hardware LO is tuned
	// LOOffsetHz BELOW the logical control-channel frequency, so the wanted
	// channel sits at +LOOffsetHz in the delivered baseband; the
	// down-converter is built with this same offset so the channel is mixed
	// back to 0 Hz, off the front-end DC spur / 1/f noise / self-image. Zero
	// (the default) builds no NCO and is byte-exact with the pre-offset
	// behaviour — used when the path is disabled or at pass-through rates
	// where there is no room to offset.
	LOOffsetHz float64
	// Autotune, when non-nil, is the per-dongle carrier-error tracker for
	// the control SDR (sdr.autotune enabled). The decoder samples the
	// locked C4FM receiver's AFCOffsetHz once per second, folds it into the
	// running average, and shifts the digital down-converter by that
	// average at each (re)acquisition so the demod's AFC starts near lock.
	// Nil disables autotune at zero cost. See internal/autotune.
	Autotune *autotune.Manager
	// CarrierOffsetWarnHz is the magnitude of the total locked carrier offset
	// (autotune correction + receiver residual) above which the pump emits a
	// throttled WARN that GT may have locked onto an adjacent site's carrier
	// (issue #815). Zero selects defaultCarrierOffsetWarnHz. Raise it for a
	// high-drift dongle to avoid benign warnings.
	CarrierOffsetWarnHz int
	// DDCRecordDir, when non-empty, records the post-DDC narrowband IQ (the
	// channelized stream the active pipeline decodes, at the pipeline rate) to
	// two-channel 16-bit baseband WAVs in this directory. This is the "record
	// the digital down-converter output" tap: a small per-channel recording of
	// exactly the signal being decoded, instead of a fat wideband capture at
	// the SDR rate. Empty (the default) disables it at zero cost. Driven by a
	// baseband record entry with tap: ddc.
	DDCRecordDir string
}

type PipelineFactory func(PipelineOptions) (ProtocolPipeline, error)

type PipelineOptions struct {
	Bus          *events.Bus
	Log          *slog.Logger
	SystemName   string
	FrequencyHz  uint32
	SampleRateHz float64
	System       trunking.System

	// SymbolTap, when non-nil, is invoked with every chunk of recovered
	// symbols a pipeline's receiver emits, just before they enter the
	// control-channel state machine. symbols holds dibits (values 0..3,
	// isBits=false) for the 4-level protocols and bits (values 0..1,
	// isBits=true) for the 2-level protocols; baseIdx is the absolute
	// symbol index the chunk starts at. It is a pure observation hook —
	// production never sets it. The offline siglab toolkit uses it to
	// count symbols and feed its protocol-agnostic signal-quality
	// analyzer for *every* protocol, without re-duplicating receiver
	// construction outside this factory. nil ⇒ zero overhead.
	SymbolTap func(symbols []uint8, isBits bool, baseIdx int)

	// FECObserver, when non-nil, receives a per-burst FEC correction
	// depth (channel bits the decode chain corrected) bound to this
	// system. The decoder supplies it only when metrics.detailed_fec is
	// enabled; today only newTETRAPipeline consumes it. nil ⇒ zero
	// overhead.
	FECObserver func(channel string, corrections int)

	// CarrierBiasHz, when non-nil, returns the frequency correction (Hz) the
	// decoder has already folded into the down-converter for the active
	// acquisition (the autotune-applied shift). newP25Phase1Pipeline adds it
	// to the receiver's residual AFCOffsetHz so the published
	// control_channel_carrier_offset_hz reports the TOTAL offset from the
	// configured frequency — matching the WARN in checkCarrierOffsetLocked —
	// instead of the residual-only value that drops toward 0 once autotune
	// re-centres the carrier (issue #815). Nil ⇒ residual only.
	CarrierBiasHz func() float64
}

type ProtocolPipeline interface {
	Process(iq []complex64)
	Reset()
	Close() error
}

type Tuner interface {
	SetCenterFreq(hz uint32) error
}