The drift resampler
audiopump.DriftResampler plays a Ring that something else fills on its
own clock: a USB microphone, a network stream, a second codec. You hand it
the Ring and play it instead of the Ring, and it keeps the Ring at a target
fill for as long as the two clocks run, without a gap or a skip:
ring = audiopump.Ring(sample_rate=48000, channel_count=2, frames=256, capacity=8)
drift = audiopump.DriftResampler(ring) # holds the Ring at 1024 frames
mixer.voice[0].play(drift)
This page is why it is built the way it is, and what it measured.
Why a fixed ratio isn’t enough
Two devices that both say 48 kHz differ by tens of parts per million, and up to a few hundred for cheap crystals. At 100 ppm a Ring between them gains or loses 4.8 frames a second, so a 1024-frame cushion is gone in under four minutes. The fix is to read the Ring very slightly faster or slower than nominal, by exactly the clocks’ difference, which nobody knows in advance and which wanders with temperature.
audiospeed.SpeedChanger holds its rate in 16.16 fixed point, a step of
about 15 ppm: the size of the error being corrected. Here the read position
and the ratio are 32.32 fixed point, a step of about 0.0002 ppm, so the
ratio can sit where the clocks are rather than hunting between two steps
either side of it.
Where it lives
The node is in audiopump, beside Ring, rather than beside
audiospeed.Resampler. CircuitPython has its own audiospeed, and a module
of ours never shadows one of CircuitPython’s
(the correctness standard). audiopump is ours
on all three runtimes, and the node only reads a Ring, so it belongs with
the Ring.
Interpolation
The read position falls between input samples, so the node interpolates
with a 32-tap Kaiser-windowed sinc (beta 9, cutoff 0.45 of the input rate).
The filter is tabulated at 128 fractional positions, plus one more so a
neighbour always exists, and the node blends linearly between the two rows
either side of the read position. Each row is scaled to sum to exactly 1, so
a constant input comes out unchanged at every position. The table is
src/shared/audiodsp_drift_table.h,
written by tools/design_drift_table.py;
it is a checked-in constant rather than something each runtime computes,
because CircuitPython’s floats are single precision and its libm is not
glibc’s, and every target has to render the node identically.
The cutoff is set for the input rate, so the node converts up or across, never down: an output rate from the Ring’s own up to twice it. Converting down would fold everything between the two Nyquist frequencies back into the band.
Cost. Per output frame: 32 coefficient blends, then 32 multiply-adds a channel, all single-precision float. That is about 96 floating-point multiply-adds a stereo frame, 4.6 million a second at 48 kHz, or roughly 3% of one ESP32-P4 core at 360 MHz. That figure is an estimate from the operation count; it has not been timed on a board. The work buffer is the block plus 36 frames, as floats.
Control
Once a block, the node measures the fill: the frames the Ring holds plus
those already taken into the filter beyond its look-ahead, less the
fractional read position. The ring’s level jumps by a whole packet each
time the producer writes, so the measurement goes through two one-pole
smoothers before a PI loop. The loop’s output is the ratio’s offset from
nominal, clamped to max_ppm (1000 by default), and the integrator is
clamped to the same bound so it cannot wind up.
The loop is a second-order system with damping 0.8 and natural frequency
bandwidth (0.01 Hz by default, 0.001 to 0.1 allowed). It starts at eight
times that and narrows with a 15-second time constant, so it locks in
seconds and then holds still. The smoothers sit at four times the loop’s
frequency. Above about 0.1 Hz the loop starts following the producer’s
packets instead of its clock, and the ratio swings by hundreds of ppm from
one block to the next, so the bound stops there.
Playback starts when the fill first reaches the target, and anything beyond it is dropped on that block, so the loop does not start by draining an excess. If the Ring runs short of a block, the node plays a block of silence, counts an underrun on itself and on the Ring, and waits for the target again. It keeps the rate it had learned, since the clocks have not changed.
What it measured
On the desktop, through the CPython build, with a producer writing a Ring of 8 blocks of 256 frames (target 1024) on a clock offset from the output’s. Two packet sizes: 48 frames (1 ms, a USB microphone) and 480 (10 ms, a network or Bluetooth burst). 90 to 120 seconds each, default settings.
Producer’s clock |
Packet |
Underruns, overruns |
Within 8 frames of target after |
Ratio after lock |
|---|---|---|---|---|
+100 ppm |
48 |
0, 0 |
2.3 s |
100.00 ± 0.36 ppm |
−100 ppm |
48 |
0, 0 |
6.2 s |
−99.94 ± 0.36 ppm |
+300 ppm |
48 |
0, 0 |
5.6 s |
— |
+100 ppm |
480 |
0, 0 |
32 s |
101.7 ± 6.4 ppm |
−100 ppm |
480 |
0, 0 |
28 s |
−98.1 ± 5.2 ppm |
±100 ppm over 2 minutes |
48 and 480 |
0, 0 |
tracks within 54 frames |
follows it |
The 480-frame cases take longer because the first measurement lands somewhere in the packet’s sawtooth, up to about 100 frames from where the smoothed fill settles. The ±5 ppm left on the ratio there is the packets showing through the smoothers, a fraction of a cent of pitch moving below 1 Hz.
THD+N, a 0.9 full-scale sine in, everything from 20 Hz to 20 kHz but the fundamental out: −93.7 to −95.2 dB at 1 kHz and 10 kHz across every case above. A sine quantized once to 16 bits measures −97.5 dB at 1 kHz on the same analysis, and the node’s input and its output are each 16-bit, so two roundings alone come to about −94.5 dB. The interpolation adds little to what 16-bit audio already has.
tests/test_cpython_drift.py holds these as traits, with bars a little
looser than the figures, and tests/parity/drift_probe.py checks that
MicroPython, CircuitPython and CPython render the node byte for byte.