fix mistaken "do not roll" conclusion in TransportFSM::compute_should_roll()
[ardour.git] / scripts / HiAndLowPass.lua
index f9e18f491264d9be2daf6fcb39c5bb98ebddd3aa..75704d97016577d5d3ece380903f2db726bf7005 100644 (file)
@@ -4,7 +4,7 @@ ardour {
        category    = "Filter",
        license     = "GPLv2",
        author      = "Ardour Team",
-       description = [[High Low Pass filter with up to 48dB / octave]]
+       description = [[High and Low Pass Filter with de-zipped controls, written in Ardour-Lua]]
 }
 
 function dsp_ioconfig ()
@@ -52,6 +52,8 @@ local filt = nil -- the biquad filter instance (GUI, response)
 local cur = {0, 0, 0, 0, 0, 0} -- current parameters
 local lpf = 0.03 -- parameter low-pass filter time-constant
 local chn = 0 -- channel/filter count
+local lpf_chunk = 0 -- chunk size for audio processing when interpolating parameters
+local max_freq = 20000
 
 local mem = nil -- memory x-fade buffer
 
@@ -59,13 +61,32 @@ function dsp_init (rate)
        -- allocate some mix-buffer
        mem = ARDOUR.DSP.DspShm (8192)
 
+       -- max allowed cut-off frequency
+       max_freq = .499 * rate
+
        -- create a table of objects to share with the GUI
        local tbl = {}
        tbl['samplerate'] = rate
+       tbl['max_freq'] = max_freq
        self:table ():set (tbl)
 
-       -- interpolation time constant, ~15Hz @ 64fpp
-       lpf = 5000 / rate
+
+       -- Parameter smoothing: we want to filter out parameter changes that are
+       -- faster than 15Hz, and interpolate between parameter values.
+       -- For performance reasons, we want to ensure that two consecutive values
+       -- of the interpolated "steepness" are less that 1 apart. By choosing the
+       -- interpolation chunk size to be 64 in most cases, but 32 if the rate is
+       -- strictly less than 22kHz (there's only 8kHz in standard rates), we can
+       -- ensure that steepness interpolation will never change the parameter by
+       -- more than ~0.86.
+       lpf_chunk = 64
+       if rate < 22000 then lpf_chunk = 32 end
+       -- We apply a discrete version of the standard RC low-pass, with a cutoff
+       -- frequency of 15Hz. For more information about the underlying math, see
+       -- https://en.wikipedia.org/wiki/Low-pass_filter#Discrete-time_realization
+       -- (here Δt is lpf_chunk / rate)
+       local R = 2 * math.pi * lpf_chunk * 15 -- Hz
+       lpf = R / (R + rate)
 end
 
 function dsp_configure (ins, outs)
@@ -85,6 +106,12 @@ function dsp_configure (ins, outs)
                lp[c] = {}
                -- initialize filters
                -- http://manual.ardour.org/lua-scripting/class_reference/#ARDOUR:DSP:Biquad
+
+               -- A different Biquad is needed for each pass and channel because they
+               -- remember the last two samples seen during the last call of Biquad:run().
+               -- For continuity these have to come from the previous audio chunk of the
+               -- same channel and pass and would be clobbered if the same Biquad was
+               -- called several times by cycle.
                for k = 1,4 do
                        hp[c][k] = ARDOUR.DSP.Biquad (tbl['samplerate'])
                        lp[c][k] = ARDOUR.DSP.Biquad (tbl['samplerate'])
@@ -92,6 +119,21 @@ function dsp_configure (ins, outs)
        end
 end
 
+function santize_params (ctrl)
+       -- don't allow manual cross-fades. enforce enums
+       ctrl[1] = math.floor(ctrl[1] + .5)
+       ctrl[4] = math.floor(ctrl[4] + .5)
+
+       -- high pass, clamp range
+       ctrl[2] = math.min (max_freq, math.max (5, ctrl[2]))
+       ctrl[3] = math.min (6, math.max (0.1, ctrl[3]))
+
+       -- low pass, clamp range
+       ctrl[5] = math.min (max_freq, math.max (20, ctrl[5]))
+       ctrl[6] = math.min (6, math.max (0.1, ctrl[6]))
+       return ctrl
+end
+
 -- helper functions for parameter interpolation
 function param_changed (ctrl)
        for p = 1,6 do
@@ -135,23 +177,24 @@ end
 
 -- the actual DSP callback
 function dsp_run (ins, outs, n_samples)
-       assert (n_samples < 8192)
+       assert (n_samples <= 8192)
        assert (#ins == chn)
+       local ctrl = santize_params (CtrlPorts:array ())
 
        local changed = false
        local siz = n_samples
        local off = 0
 
-       -- if a parameter was changed, process at most 64 samples at a time
-       -- and interpolate parameters until the current settings match
-       -- the target values
-       if param_changed (CtrlPorts:array ()) then
+       -- if a parameter was changed, process at most lpf_chunk samples
+       -- at a time and interpolate parameters until the current settings
+       -- match the target values
+       if param_changed (ctrl) then
                changed = true
-               siz = 64
+               siz = lpf_chunk
        end
 
        while n_samples > 0 do
-               if changed then apply_params (CtrlPorts:array ()) end
+               if changed then apply_params (ctrl) end
                if siz > n_samples then siz = n_samples end
 
                local ho = math.floor(cur[1])
@@ -160,59 +203,59 @@ function dsp_run (ins, outs, n_samples)
                -- process all channels
                for c = 1, #ins do
 
+                       -- High Pass
                        local xfade = cur[1] - ho
 
+                       -- prepare scratch memory
                        ARDOUR.DSP.copy_vector (mem:to_float (off), ins[c]:offset (off), siz)
 
-                       -- initialize output
-                       if cur[1] == 0 then
-                               -- high pass is disabled, just copy data.
-                               ARDOUR.DSP.copy_vector (outs[c]:offset (off), mem:to_float (off), siz)
-                       else
-                               -- clear output, The filter mixes into the output buffer
-                               ARDOUR.DSP.memset (outs[c]:offset (off), 0, siz)
-                       end
-
-                       -- high pass
-                       -- allways run all filters so that we can interplate as needed.
-                       for k = 1,4 do
-                               if xfade > 0 and k == ho + 1 then
-                                       ARDOUR.DSP.mix_buffers_with_gain (outs[c]:offset (off), mem:to_float (off), siz, 1 - xfade)
-                               end
-
+                       -- run at least |ho| biquads...
+                       for k = 1,ho do
                                hp[c][k]:run (mem:to_float (off), siz)
-
-                               if k == ho and xfade == 0 then
-                                       ARDOUR.DSP.copy_vector (outs[c]:offset (off), mem:to_float (off), siz)
-                               elseif k == ho + 1 then
-                                       ARDOUR.DSP.mix_buffers_with_gain (outs[c]:offset (off), mem:to_float (off), siz, xfade)
-                               end
+                       end
+                       ARDOUR.DSP.copy_vector (outs[c]:offset (off), mem:to_float (off), siz)
+
+                       -- mix the output of |ho| biquads (with weight |1-xfade|)
+                       -- with the output of |ho+1| biquads (with weight |xfade|)
+                       if xfade > 0 then
+                               ARDOUR.DSP.apply_gain_to_buffer (outs[c]:offset (off), siz, 1 - xfade)
+                               hp[c][ho+1]:run (mem:to_float (off), siz)
+                               ARDOUR.DSP.mix_buffers_with_gain (outs[c]:offset (off), mem:to_float (off), siz, xfade)
+                               -- also run the next biquad because it needs to have the correct state
+                               -- in case it start affecting the next chunck of output. Higher order
+                               -- ones are guaranteed not to be needed for the next run because the
+                               -- interpolated order won't increase more than 0.86 in one step thanks
+                               -- to the choice of the value of |lpf|.
+                               if ho + 2 <= 4 then hp[c][ho+2]:run (mem:to_float (off), siz) end
+                       elseif ho + 1 <= 4 then
+                               -- run the next biquad in case it is used next chunk
+                               hp[c][ho+1]:run (mem:to_float (off), siz)
                        end
 
-                       -- low pass
+                       -- Low Pass
                        xfade = cur[4] - lo
 
-                       -- copy output of high-pass into "processing memory"
+                       -- prepare scratch memory (from high pass output)
                        ARDOUR.DSP.copy_vector (mem:to_float (off), outs[c]:offset (off), siz)
 
-                       if cur[4] > 0 then
-                               -- Clear output, Low-pass mixes interpolated data into output.
-                               -- (Except if the filter is disabled (0) in which case we just keep the output.)
-                               ARDOUR.DSP.memset (outs[c]:offset (off), 0, siz)
-                       end
-
-                       for k = 1,4 do
-                               if xfade > 0 and k == lo + 1 then
-                                       ARDOUR.DSP.mix_buffers_with_gain (outs[c]:offset (off), mem:to_float (off), siz, 1 - xfade)
-                               end
-
+                       -- run at least |lo| biquads...
+                       for k = 1,lo do
                                lp[c][k]:run (mem:to_float (off), siz)
-
-                               if k == lo and xfade == 0 then
-                                       ARDOUR.DSP.copy_vector (outs[c]:offset (off), mem:to_float (off), siz)
-                               elseif k == lo + 1 then
-                                       ARDOUR.DSP.mix_buffers_with_gain (outs[c]:offset (off), mem:to_float (off), siz, xfade)
-                               end
+                       end
+                       ARDOUR.DSP.copy_vector (outs[c]:offset (off), mem:to_float (off), siz)
+
+                       -- mix the output of |lo| biquads (with weight |1-xfade|)
+                       -- with the output of |lo+1| biquads (with weight |xfade|)
+                       if xfade > 0 then
+                               ARDOUR.DSP.apply_gain_to_buffer (outs[c]:offset (off), siz, 1 - xfade)
+                               lp[c][lo+1]:run (mem:to_float (off), siz)
+                               ARDOUR.DSP.mix_buffers_with_gain (outs[c]:offset (off), mem:to_float (off), siz, xfade)
+                               -- also run the next biquad in case it start affecting the next
+                               -- chunck of output.
+                               if lo + 2 <= 4 then lp[c][lo+2]:run (mem:to_float (off), siz) end
+                       elseif lo + 1 <= 4 then
+                               -- run the next biquad in case it is used next chunk
+                               lp[c][lo+1]:run (mem:to_float (off), siz)
                        end
 
                end
@@ -283,11 +326,12 @@ function render_inline (ctx, w, max_h)
                filt = {}
                filt['hp'] = ARDOUR.DSP.Biquad (tbl['samplerate'])
                filt['lp'] = ARDOUR.DSP.Biquad (tbl['samplerate'])
+               max_freq   = tbl['max_freq']
        end
 
+       local ctrl = santize_params (CtrlPorts:array ())
        -- set filter coefficients if they have changed
-       if param_changed (CtrlPorts:array ()) then
-               local ctrl = CtrlPorts:array ()
+       if param_changed (ctrl) then
                for k = 1,6 do cur[k] = ctrl[k] end
                filt['hp']:compute (ARDOUR.DSP.BiquadType.HighPass, cur[2], cur[3], 0)
                filt['lp']:compute (ARDOUR.DSP.BiquadType.LowPass,  cur[5], cur[6], 0)