Detailed Description

CALCRATIO Parameters.

The CALCRATIO algorithm estimates the ratio between an input fs and an output fs (e.g., sample-rate conversion, clock scaling, etc.) by measuring timing periods and smoothing them with a two-stage moving-average filter. This structure holds:

User-provided sample rates (fsi, fso) – the nominal input and output rates set by the user.
Target ratio – the ideal fso / fsi ratio computed once at initialization.
Actual ratio – the smoothed ratio produced on every execution of calcRatio_exec(). It converges toward the target ratio as the filters settle.
Two-stage moving-average state – separate buffers, sums, and pointers for the first-stage (coarse) and second-stage (fine) filters.
Auxiliary counters – used to manage filter updates and to discard the first (often noisy) measurement.

The first stage (MA1) uses a long window (CALCRATIO_MA1_LENGTH = 1024) to heavily dampen jitter. Its output feeds the second stage (MA2), which uses a shorter window (CALCRATIO_MA2_LENGTH = 128) for finer smoothing. The final smoothed period yields actual_ratio.

Data Fields
float	fsi
	Input sample rate set by the user (Hz). More...

float	fso
	Output sample rate set by the user (Hz). More...

double	target_ratio
	Target ratio produced by calcRatio_init. More...

double	actual_ratio
	Actual ratio produced by calcRatio_exec on each call. More...

double	movingAvg1Sum
	Accumulator for the first-stage moving-average sum. More...

double	capture_history [CALCRATIO_MA1_LENGTH]
	Circular buffer holding the most recent period measurements for the first-stage moving-average filter. More...

double *	P2_capture_hist
	Pointer into `capture_history` indicating where the next period sample will be written. More...

double	movingAvg2Sum
	Accumulator for the second-stage moving-average sum. More...

double	capture2_history [CALCRATIO_MA2_LENGTH]
	Circular buffer for the second-stage moving-average filter. More...

double *	P2_capture2_hist
	Pointer into `capture2_history` for the next write location. More...

uint32_t	movingAvg2Count
	Counter for the graduated (incremental) update of the second-stage average. More...

uint16_t	one_shot
	One-shot flag to discard the very first captured period. More...

Field Documentation

◆ fsi

float CalcRatio_t::fsi

Input sample rate set by the user (Hz).

◆ fso

float CalcRatio_t::fso

Output sample rate set by the user (Hz).

◆ target_ratio

double CalcRatio_t::target_ratio

Target ratio produced by calcRatio_init.

Computed as target_ratio = (double)fso / (double)fsi. This is the ideal ratio the algorithm tries to track.

◆ actual_ratio

double CalcRatio_t::actual_ratio

Actual ratio produced by calcRatio_exec on each call.

Starts near zero and converges to target_ratio as the two-stage moving-average filters accumulate enough samples.

◆ movingAvg1Sum

double CalcRatio_t::movingAvg1Sum

Accumulator for the first-stage moving-average sum.

◆ capture_history

double CalcRatio_t::capture_history[CALCRATIO_MA1_LENGTH]

Circular buffer holding the most recent period measurements for the first-stage moving-average filter.

Size = CALCRATIO_MA1_LENGTH (1024 entries). Each entry stores the measured period (in seconds) between successive input events.

◆ P2_capture_hist

double* CalcRatio_t::P2_capture_hist

Pointer into capture_history indicating where the next period sample will be written.

Updated in a wrap-around fashion; the filter logic uses (P2_capture_hist - capture_history) as the current index.

◆ movingAvg2Sum

double CalcRatio_t::movingAvg2Sum

Accumulator for the second-stage moving-average sum.

◆ capture2_history

double CalcRatio_t::capture2_history[CALCRATIO_MA2_LENGTH]

Circular buffer for the second-stage moving-average filter.

Holds the per-sample output of the first-stage filter. Size = CALCRATIO_MA2_LENGTH (128 entries).

◆ P2_capture2_hist

double* CalcRatio_t::P2_capture2_hist

Pointer into capture2_history for the next write location.

Behaves identically to P2_capture_hist but for the second stage.

◆ movingAvg2Count

uint32_t CalcRatio_t::movingAvg2Count

Counter for the graduated (incremental) update of the second-stage average.

When the first-stage filter produces a new value, this counter is incremented until it reaches CALCRATIO_MA2_LENGTH; only then is the oldest entry subtracted from movingAvg2Sum. This implements a “graduated average” that avoids abrupt changes when the buffer wraps.

◆ one_shot

uint16_t CalcRatio_t::one_shot

One-shot flag to discard the very first captured period.

The first measurement is often spurious (e.g., due to startup transients). Setting one_shot = 1 causes calcRatio_exec() to ignore it and clear the flag immediately afterward.