conventional

type CTCSSConfig struct {
	// SampleHz is the IQ sample rate (typically 2.4e6 for RTL-SDR).
	SampleHz float64
	// TargetHz is the CTCSS frequency to detect. Standard values
	// range from 67.0 to 254.1 Hz; the EIA list has 50 codes but
	// only 38 + 12 are widely used.
	TargetHz float64
	// AudioCutoffHz sets the single-pole IIR low-pass cutoff. The
	// LPF rolls off the audio band so it doesn't alias into the
	// sub-audible band when the Goertzel samples at its block
	// rate. Defaults to 500 Hz when zero — comfortably above the
	// highest CTCSS frequency and below the lowest voice formant.
	AudioCutoffHz float64
	// BlockSize is the Goertzel block size in IQ samples. Larger
	// blocks → finer frequency resolution at the cost of slower
	// detection. Defaults to SampleHz / 5 (≈ 5 Hz bin resolution
	// and ~200 ms detection latency, comfortably under typical
	// CTCSS reaction times on commercial radios).
	BlockSize int
}

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

type Channel struct {
	Label       string
	FrequencyHz uint32
	// Mode is "fm" or "nfm" — the latter narrows the post-demod
	// audio LPF; both share the IQ-power squelch.
	Mode string
	// SquelchDbFS is the threshold above which the scanner declares
	// "carrier present". A typical value for an RTL-SDR-class
	// receiver is around -50 dBFS; tune per channel as needed.
	SquelchDbFS float64
	// Hangtime is how long below threshold must elapse before the
	// scanner declares the call over and resumes hopping. Default
	// 1500 ms keeps the scanner from clipping the tail of normal
	// FM transmissions.
	Hangtime time.Duration
	// Priority is forwarded to the synthetic talkgroup so the
	// engine's preemption logic respects it relative to other
	// conv-scanner channels.
	Priority int
	// Tone is the optional CTCSS / DCS gate. When set, the
	// scanner only declares "carrier present" while BOTH the
	// IQ-power squelch is open AND the configured sub-audible
	// tone is detected. Zero value (Mode="" / "none") disables
	// tone gating and the scanner behaves identically to its
	// pre-tone version. DCS mode parses + validates but the
	// detector is a tracked follow-up — see ctcss.go.
	Tone ToneConfig
}

type ChannelStatus struct {
	Index       int    `json:"index"`
	Label       string `json:"label"`
	FrequencyHz uint32 `json:"frequency_hz"`
	Mode        string `json:"mode"`
	Active      bool   `json:"active"`
	// LockedOut reports whether the channel is excluded from the
	// scan cycle by operator action. Runtime-only — the field is
	// not persisted across daemon restarts.
	LockedOut   bool      `json:"locked_out,omitempty"`
	LastBreakAt time.Time `json:"last_break_at,omitempty"`
}

type DCSConfig struct {
	// SampleHz is the IQ sample rate (typically 2.4e6 for RTL-SDR).
	SampleHz float64
	// Code is the 3-digit octal DCS code (e.g. "023", "754"). The
	// 38 EIA codes are widely deployed; the standard accepts any
	// 3-digit octal value.
	Code string
	// AudioCutoffHz sets the single-pole IIR low-pass cutoff.
	// Defaults to 250 Hz — well above the 134.4 baud Nyquist
	// rate and below any voice formant.
	AudioCutoffHz float64
}

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

type Engine interface {
	HandleSyntheticCall(g trunking.Grant, deviceSerial string)
	EndSyntheticCall(deviceSerial string, reason trunking.EndReason) bool
	Touch(deviceSerial string)
}

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

type Options struct {
	Log          *slog.Logger
	Tuner        Tuner
	IQ           IQSource
	Engine       Engine
	Recorder     Recorder
	DeviceSerial string
	SystemName   string // surfaces on the synthetic Grant.System
	Channels     []Channel
	// DwellChunkLen is the IQ-power measurement window in samples
	// during SCANNING. Default 4096 (≈ 1.7 ms at 2.4 MS/s).
	DwellChunkLen int
	// MinDwellPerChannel is the minimum time on each channel during
	// SCANNING before advancing — even if squelch never opens. Default
	// 100 ms; let signals settle after retune.
	MinDwellPerChannel time.Duration
	// SampleRateHz is the IQ sample rate the IQ source delivers
	// (typically 2.4e6 for RTL-SDR). Required when any configured
	// channel has Tone gating — without it the CTCSS detector
	// can't pick the right Goertzel bin. Zero is fine when no
	// tone gating is in play; the field is otherwise inert.
	SampleRateHz float64
	// Now is injectable for tests; defaults to time.Now.
	Now func() time.Time
}

type Recorder interface {
	WritePCM(deviceSerial string, samples []int16) error
}

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

type State string

type Status struct {
	State        State           `json:"state"`
	Channels     []ChannelStatus `json:"channels"`
	CursorIndex  int             `json:"cursor_index"`
	DeviceSerial string          `json:"device_serial,omitempty"`
}

type ToneConfig struct {
	// Mode is "ctcss", "dcs", or "" / "none" (default). Unknown
	// values are rejected at validation time.
	Mode string
	// CTCSSHz is the target CTCSS frequency (50–300 Hz). Required
	// when Mode is "ctcss". Standard EIA codes range from 67.0 to
	// 254.1 Hz; 38 are widely deployed.
	CTCSSHz float64
	// DCSCode is the three-digit octal DCS code (e.g. "023",
	// "754"). Required when Mode is "dcs". Detector wiring is
	// deferred — see Workstream D follow-up.
	DCSCode string
}

type Tuner interface {
	SetCenterFreq(hz uint32) error
}