audioeffects.digitaldelay

DigitalDelay - a clean digital delay with the Boss DD-2’s control law.

Your dry signal passes untouched, and one clean repeat follows it, fed back for more.

Controls. Time is the delay, from 12.5 to 800 ms, and Feedback is how much of each repeat goes round again, up to 0.99. Mix is the echo level: the dry stays at unity up to Mix 1, Mix 2 is the repeats alone, and at Mix 0 the output is the input. Turn Time while it plays and the repeats bend in pitch and settle, instead of clicking. Glide is how long a full-range Time move takes, from 800 ms to 8 s. Glide 0 is an instant knob, and its price is a click. Repeat Tone is a low-pass and Repeat Cut a high-pass inside the loop, so each repeat is a little darker or thinner than the last. Repeat Tone’s top stop and Repeat Cut’s bottom stop take them out. With Sync on, Time is Division of the host’s beat, up to 800 ms; with no host tempo, Time stays where the knob is. After a tempo change Time takes the new beat when the host calls transport_changed(), or when a control moves or a patch loads.

The pedal. Patch 5 puts the DD-2’s 7 kHz and 40 Hz corners in the loop. The DD-2’s compander and its HOLD are not here.

Where it stops. At 48 kHz the repeats of a Time you have stopped turning do not darken. At 44.1 and 22.05 kHz a few Times land a hair off the whole frame, and at those each repeat spills a little onto the frame beside it. A rising Time move at the fastest Glides can read more than 10 cents off the ideal bend, because the node walks its read head in single precision. At 22.05 kHz the top positions of Repeat Tone sit on one clamp below Nyquist and sound the same. The dry sits at unity and the repeats add to it, so a hot input can reach the int16 rail. With Repeat Cut out and Mix below 1, an input that peaks at or below floor(32767 (1 - Mix)) - 1 cannot reach the rail, at any Time or Feedback. Keep the input under -6 dBFS and the defaults and patches stay off the rails.

Limits shared by the family. Mix walks a jump over 20 ms, but any other control that jumps makes the output step: move it in small steps from the host if you need it smooth. When your source ends, the tail rings out as it would on silence.

Latency, tail, portability. Latency is zero samples: nothing looks ahead. tail_samples is an upper bound on how long the output takes to reach exact zero once your input stops, at every Feedback and every setting of Repeat Tone and Repeat Cut. With Repeat Cut in circuit, as at patch 5, the bound is twice as many repeats as with it out, a margin measured rather than derived. Pass a lower max_time_ms for a shorter line: Time then stops at that ceiling, and get_macro(0) shows where it stopped. A constructor Time of 0 is the bottom of its span, and a Repeat Tone or Repeat Cut of 0 is that filter out. reset() empties the line and returns to patch 0. The class reads the host’s transport only while Sync is on. The class needs audiodsp’s audioecho, and on a board without it construction raises ImportError.

audioeffects.digitaldelay.TIME_MIN_MS = 12.5

12.5-800 ms, log.

Type:

The Time map, fixed on every instance (dossier T4)

audioeffects.digitaldelay.FULL_RANGE_MS = 787.5

Glide is the time a full-range Time move takes; the node’s delay_slew (delay-seconds per second) is FULL_RANGE_MS / glide_ms (dossier section 6).

audioeffects.digitaldelay.GLIDE_MIN_MS = 800.0

The Glide knob’s span, log, with grid 0 the jump. A constructor Glide slower than the top is clamped to it, the way Time clamps at max_time_ms, so get_macro(3) always names the Glide that plays.

audioeffects.digitaldelay.SLEW_PIN = 0.99

At slew 1 a rising Time stands the read head still, and past it the line plays backwards. A constructor Glide under 795.45 ms is pinned here; no grid position gets there (grid 1 is slew 0.967).

audioeffects.digitaldelay.GLIDE_FLOOR = 0.007874015748031496

The Glide knob’s position for a constructor Glide faster than grid 1: grid 1 itself (814.6 ms, slew 0.967), the knob’s fastest walk. Grid 0 is the jump, and a position just above it reads back as a MIDI value that rounds to 0 on any 7-bit path (fix round 2).

audioeffects.digitaldelay.FEEDBACK_MAX = 0.99

157`).

Type:

The node’s own loop ceiling (`audiodsp_feedback_delay.c

audioeffects.digitaldelay.LINE_HEADROOM_MS = 1.0

the node clamps a delay at line_frames - 2, so a line of exactly max_time_ms could not reach it.

Type:

The line’s headroom over max_time_ms

audioeffects.digitaldelay.LINE_PEAK = 32768

The largest magnitude one line sample can hold (int16).

audioeffects.digitaldelay.FEEDBACK_MARGIN = 1.52587890625e-05

laps_to_zero reckons with a Feedback this much larger, relatively, so the node’s single-precision feedback and product, and a board’s single-precision Python, can only make the bound longer, never shorter.

audioeffects.digitaldelay.STALL_CLEARANCE = 9.5367431640625e-07

How far outside a Repeat Tone stall window clear_of_stalls puts the Feedback it hands the node, relative to the window’s edge: many times a single-precision float’s step (2^-24), so a board’s arithmetic lands on the same side, and far under the window’s own width (2-4 x 10^-5) and the knob’s 7-bit step (0.0078). This class stopped stepping at audiodsp v0.6.3rc1, whose node lands a stalled damping state (audiodsp#157).

audioeffects.digitaldelay.STALL_FUZZ = 2.384185791015625e-07

stall_window widens each window by this much, relatively, either side, so a Feedback on an edge that laps_to_zero’s own rounding puts inside (a constructor value that comes back through the macro 10^-17 away) is moved too. Four times under STALL_CLEARANCE, so a moved value is never itself on the widened edge.

audioeffects.digitaldelay.CUT_LAP_FACTOR = 2

With Repeat Cut in circuit tail_samples counts this many times laps_to_zero’s laps. The high-pass sends a lap’s value less the mean the loop has been carrying, which can be larger than any value on the line, so the per-lap argument (each lap’s peak below the last) does not hold, and no count of its own is derived here. The factor is measured. On full-scale noise, at every Feedback from 0.40 to 0.99 in steps of 0.01, Repeat Cut from 20.3 to 400 Hz, 48 and 22.05 kHz, ten noises each, and again on random full-scale signs and sparse clicks, mono and stereo, Repeat Tone out and at 800 Hz, and on PingPongDelay at both ends of Spread, the longest tail took 1.35 times the count with the filter out (PingPongDelay, Feedback 0.5, Spread 1, Cut 20.3 Hz), and at Feedback 0.99 1.06 (721 laps against 685). Twice the count leaves nearly half again over the worst.

audioeffects.digitaldelay.DIVISION_BEATS = (0.125, 0.16666666666666666, 0.1875, 0.25, 0.3333333333333333, 0.375, 0.5, 0.6666666666666666, 0.75, 1.0, 1.3333333333333333, 1.5, 2.0, 2.6666666666666665, 3.0, 4.0)

1/32, 1/16T, 1/32., 1/16, 1/8T, 1/16., 1/8, 1/4T, 1/8., 1/4, 1/2T, 1/4., 1/2, 1/1T, 1/2., 1/1.

Type:

Division’s sixteen note values, in quarter-note beats, rising

audioeffects.digitaldelay.DEFAULTS = (350.0, 0.35, 0.3, 4000.0, 0.0, 6.0, 16000.0, 20.0)

patch 0’s steps, rounded. An option left out plays the step itself.

Type:

_build’s defaults in the macros’ units

audioeffects.digitaldelay.nominal_cut_hz(corner_hz, sample_rate)[source]

cut_hz whose one-pole high-pass -3 dB is corner_hz at sample_rate. 0 stays 0, which is the filter out of circuit.

The node’s high-pass is y -= lp(y) with the low-pass coefficient a = 1 - exp(-2 pi hz / fs) (audiodsp_feedback_delay.c:33-40, :498-501 at v0.6.2), so with b = 1 - a it is H = b (1 - z^-1) / (1 - b z^-1). |H|^2 = 1/2 gives b^2 (3 - 4 cos w) + 2 b cos w - 1 = 0; the root in (0, 1) is the pole, and cut_hz = -fs ln b / 2 pi.

audioeffects.digitaldelay.slew_of(glide_ms)[source]

The node’s delay_slew for a Glide: 0 (the jump) at Glide 0, otherwise 787.5 ms over glide_ms, pinned at 0.99.

audioeffects.digitaldelay.whole_frames(time_ms, sample_rate)[source]

The nearest whole frame at the running rate (dossier section 6).

audioeffects.digitaldelay.laps_to_zero(feedback, excess=0.0)[source]

How many laps of the line can still hold a non-zero sample once the input stops. Finite at every Feedback since audiodsp v0.6.3rc1.

Once the input stops, the node writes to_s16(recirculated(s, f)) for each value s it sends round (audiodsp_feedback_delay.c:529). Since audiodsp v0.6.2 (#154) recirculated (:344) rounds f s to nearest where |s| - |f s| > 0.5 and truncates it toward zero otherwise.

With Repeat Tone out (excess 0) s is a line sample, or a mix of two at a fractional read, so |s| <= x, the line’s peak, and the node guarantees |write| < |s|: a lap maps x to at most min(x - 1, floor(f x + 0.5)). Both halves only grow with x, so the peak of one lap bounds every sample of the next, and iterating from full scale counts the laps to exact zero. That is finite at every Feedback; 0.99 takes 685 laps.

With Repeat Tone in, s is the loop low-pass’s state, which can sit above the line’s peak by up to excess times it (DigitalDelay’s _tone_excess). Then a lap maps x to the node’s write at s = x (1 + excess), whichever branch it takes, and the guarantee is gone: where that write is still x, the peak is handed back. Up to audiodsp v0.6.2 it stayed there for ever (1 LSB at Feedback 0.5, 5 at 0.9, Tone 800 Hz, on a DC input), and this count was None there. From v0.6.3rc1 (audiodsp#157) the node sets a damping state that has stopped moving onto its input, once a block, at or below 64 LSB, which covers every such x (at most 50, at the node’s 0.99). So the peak is counted one more lap there and then leaves as with the filter out, min(x - 1, floor(f x + 0.5)). The extra lap is measured, not derived (the landing waits for a block’s end, and a host picks the block): at every window centre k = 1 … 50, Repeat Tone grid 0, 64 and 126, on a 2 LSB DC and on full scale, in blocks of 64 to 4 096 frames at Time 12.5 ms, each tail ends inside the count with the extra lap left out, 239 frames or more short of it.

audioeffects.digitaldelay.stall_window(feedback, excess)[source]

The Repeat Tone stall window feedback sits in, as (low, high), or None outside every window.

laps_to_zero(f, excess) takes its extra landing lap exactly when some whole peak x it reaches is handed back: the rounding branch taken, x (1 + excess)(1 - f (1 - m)) > 0.5, and the image not below x, f (1 + m) x (1 + excess) + 0.5 >= x, m being FEEDBACK_MARGIN. For each x that is one window, [(1 - 0.5 / x) / ((1 + m)(1 + excess)), (1 - 0.5 / (x (1 + excess))) / (1 - m)), 2-4 x 10^-5 wide around 1 - 0.5 / x; x = 1 … 50 are the ones under the node’s 0.99. Each is returned widened by STALL_FUZZ either side. With Repeat Tone out (excess 0) no lap hands a value back, and there is no window.

audioeffects.digitaldelay.clear_of_stalls(feedback, excess)[source]

feedback moved to the nearer edge of the Repeat Tone stall window it sits in (stall_window), just outside it, or unchanged outside every window. The top window’s upper edge is above the node’s 0.99, so there it always moves down. Every move is under 3 x 10^-5 of Feedback (2.6 x 10^-5 at the 0.99 stop), far inside one step of the 7-bit knob, so get_macro(1) still names the setting that plays.

Not called by this class since audiodsp v0.6.3rc1 (the node lands a stalled damping state, audiodsp#157); only planted faults use it.

class audioeffects.digitaldelay.DigitalDelay(source, *options, **keywords)[source]

Bases: Component

A clean digital delay with the DD-2’s control law: the dry path is a wire, and turning Time pitch-bends the repeats instead of clicking. audiodsp tier; zero latency. The module docstring has the rest.

NAME = 'DigitalDelay'

The stable provider name audioeffects.create() discovers.

TIER = 'audiodsp'

STOCK or AUDIODSP, with REQUIRES naming the audiodsp-own modules an AUDIODSP class needs.

Type:

roadmap §3

CAPABILITIES = ('tempo_sync',)

The contract’s static reads. CAPABILITIES names "tempo_sync" if and only if the class reads self._transport().

INPUT_CEILING_DBFS = -6

The defaults and every patch play the ceiling kit’s materials clean at this level; at -3 dBFS, patch 3 rails on a 100 Hz square.

MACRO_LABELS = ('Time', 'Feedback', 'Mix', 'Glide', 'Sync', 'Division', 'Repeat Tone', 'Repeat Cut')

Knob names, one per macro index; one mode per label; the private engineering spans behind them; and the patches on the 0-127 grid.

PATCHES = {0: ('Clean Repeats', (102, 45, 19, 89, 0, 51, 127, 0)), 1: ('Eighth Notes', (102, 51, 19, 89, 127, 51, 127, 0)), 2: ('Dotted Eighths', (102, 58, 19, 89, 127, 68, 127, 0)), 3: ('Short Doubling', (45, 0, 32, 89, 0, 51, 127, 0)), 4: ('Long Ambient', (125, 90, 16, 89, 0, 51, 127, 0)), 5: ('Band Limited Repeats', (102, 77, 19, 89, 0, 51, 92, 29))}

_component.macro_of of the dossier’s section 6 settings; patch 0 is the constructor’s defaults on the grid.

reset()[source]

Clear every node this class built, tail first, and restore patch 0. The borrowed source is never named here.

property tail_samples

Frames until the output is exactly zero once the input stops, as an upper bound.

laps_to_zero(f) laps, each at most one frame longer than the longest delay the read head may be at (the read interpolates towards the next older frame). While a Glide walk falls, that is the Time it is walking from, not the target, and it stays so until a Glide-0 move or a reset lands the head, because the class cannot see how far the walk has got.

Finite at every Feedback. With Repeat Tone in, each lap is memory frames longer, the time the low-pass takes to forget the lap before, and near the Feedback values where the node once held a small value for ever the count takes one more lap (laps_to_zero). With Repeat Cut in, the laps are counted CUT_LAP_FACTOR times: the high-pass can lift a lap’s peak above the last one’s, so that margin is measured, not derived (CUT_LAP_FACTOR).