modulation

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

type MfskOptions struct {
	// Name identifies the profile; see ProfileByName.
	Name string
	// Tones is the alphabet size and must be a power of two, so that an integer
	// number of bits maps to a tone with no wasted symbols.
	Tones int
	// FirstHz is the lowest tone. It must sit above the region where laptop
	// speakers roll off.
	FirstHz float64
	// SpacingHz is the tone spacing. It is overridden to exactly sampleRate /
	// SymbolSamples so that orthogonality holds exactly; the requested value
	// only sets the symbol length.
	SpacingHz float64
	// SymbolSamples is the symbol window length. Payload timing derives entirely
	// from it, so it is validated against the tone spacing rather than trusted.
	SymbolSamples int
	// EdgeRampSamples is the fade applied to both ends of a burst, in samples.
	// requires at least 5 ms; clicks are perceived as far louder
	// than their energy implies, which is precisely the kind of noise the
	// non-intrusiveness requirement exists to avoid.
	EdgeRampSamples int
	// Amplitude is the linear peak. caps the default at -20 dBFS and
	// this is enforced rather than advised.
	Amplitude float32
	// SampleRate is the device rate.
	SampleRate int
}

type Profile struct {
	Name          string
	Scheme        string
	Band          [2]float64 // Hz, inclusive
	BitsPerSymbol int
	SymbolRate    float64 // symbols per second
	RawBitRate    float64 // bits per second, before framing and FEC
	FEC           string
	Interleave    int     // interleaver depth in codewords
	PeakDBFS      float64 // transmit peak level, negative
	Notes         string
}

type Scheme interface {
	// Profile describes the scheme for capability exchange and rate control.
	Profile() Profile
	// SampleCount is the burst length, in samples, for a frame of frameLen bytes.
	SampleCount(frameLen int) int
	// Capacity is the largest frame that fits in sampleCount samples.
	Capacity(sampleCount int) int
	// Encode renders a complete burst: preamble, sync, data, ready for the
	// transmit chain. frame is the output of mac.EncodeFrame.
	Encode(frame []byte) ([]float32, error)
	// Decode searches samples for a burst and returns at most maxBytes of frame
	// bytes. maxBytes exists because the receiver cannot know the frame length
	// before it has decoded the header, so the caller passes its buffer size and
	// trims afterwards.
	Decode(samples []float32, maxBytes int) ([]byte, Stats, error)
}

type SoftDecoded struct {
	// Data is the recovered bytes.
	Data []byte
	// Confidence is the per-byte margin described on SoftDecoder, one entry per
	// byte of Data.
	Confidence []float64
	// Stats describes how the burst was received.
	Stats Stats
}

type SoftDecoder interface {
	Scheme
	DecodeSoft(samples []float32, maxBytes int) (SoftDecoded, error)
}

type Stats struct {
	// SyncOffset is where the preamble was found, in samples from the start of
	// the supplied buffer.
	SyncOffset int
	// SyncScore is the normalized correlation at that offset. It is the single
	// best indicator of whether the channel is clean or marginal.
	SyncScore float64
	// Symbols is how many data symbols were demodulated.
	Symbols int
	// Erasures is how many of those were too weak to trust. A burst with many
	// erasures may still pass CRC, but its arrival means the rate should drop.
	Erasures int
	// SNRDB is an estimate of the per-symbol signal-to-noise ratio. It is an
	// indicator, not a calibrated measurement: it compares the winning tone's
	// magnitude against the mean of the rest, which is a useful proxy and not a
	// substitute for instrumentation.
	SNRDB float64
	// PeakDBFS is the peak sample level of the received burst. Comparing this
	// against what the sender intended is how microphone AGC is detected.
	PeakDBFS float64
}