Skip to content

chebyshevpoly2

Evaluates a weighted sum of Chebyshev polynomials directly for each audio sample.

Use it for waveshaping with changing harmonic weights, especially when you need many terms. It accepts a list of coefficients or a numeric array.

Syntax

aout = chebyshevpoly2(ain, k0 [, k1 [, k2 [...]]])
aout = chebyshevpoly2(ain, kcoefficients)
aout = chebyshevpoly2(ain, icoefficients)

aout chebyshevpoly2 ain, k0 [, k1 [, k2 [...]]]
aout chebyshevpoly2 ain, kcoefficients
aout chebyshevpoly2 ain, icoefficients

Performance

ain is the audio input and aout is the audio output. The opcode evaluates the following sum, where x is the current input sample.

output = c0*T0(x) + c1*T1(x) + c2*T2(x) + ...
T0(x) = 1
T1(x) = x
T2(x) = 2*x*x - 1
Tn(x) = 2*x*T[n-1](x) - T[n-2](x)

k0, k1, k2, ... are the weights for successive polynomials. Supply at least one coefficient. k0 is the constant term, not the fundamental. A single coefficient produces a constant output. Two coefficients produce k0 + k1*ain. Coefficients can change at control rate.

kcoefficients and icoefficients are one-dimensional numeric arrays. Element 0 is c0, element 1 is c1, and so on. An array of length N includes terms through T[N-1]. The array must contain at least one element. Empty, uninitialized or multidimensional arrays cause an error. The k-rate form reads the current array values and length each control cycle.

For example, this i-rate array gives the same weights as the list 0, 1, 0, 0.5.

icoefficients[] fillarray 0, 1, 0, 0.5
aout = chebyshevpoly2(ain, icoefficients)

For a cosine input of amplitude 1, Tn(cos(phase)) is cos(n*phase). Each coefficient then sets the weight of one harmonic, with c0 adding a DC offset. Changing the input amplitude or waveform changes that relationship. Apply an output envelope after waveshaping if you want to keep the chosen harmonic balance.

For ordinary waveshaping, keep the input between -1 and 1. These are literal sample values, independent of 0dbfs. The opcode does not clamp the input or normalize the output. Values outside that range can grow very large at high orders. Scale the output to avoid clipping, and keep the generated harmonics below half the sample rate to avoid aliasing.

How it differs from chebyshevpoly

Both opcodes describe the same mathematical sum and use the same coefficient order. chebyshevpoly first expands the sum into powers of x, then evaluates that polynomial. At high orders, the expanded coefficients can become very large. Rounding and overflow can spoil a result even when the final Chebyshev sum is finite.

chebyshevpoly2 uses Clenshaw recurrence to evaluate the series without that expansion. It uses double precision for the intermediate calculations in both float and double builds. This improves high-order evaluation, but does not guarantee a finite result for every input or coefficient.

chebyshevpoly can be faster for low orders. It keeps its established behavior for existing pieces. chebyshevpoly2 adds the array forms and can give different rounding results, so the two are not guaranteed to produce identical samples.

Examples

The example starts with a 220 Hz tone and gradually adds its third harmonic at 660 Hz. A coefficient list produces the left channel and a k-rate array produces the right channel. Both use the same weights and should sound the same.

The input stays at amplitude 1. An envelope and output gain control the volume after waveshaping, so the fade does not change the harmonic balance.

It uses chebyshevpoly2.csd.

Add a harmonic with list and array coefficients
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<CsoundSynthesizer>
<CsOptions>
-d -odac
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 2
0dbfs = 1

instr AddHarmonic
  ; A quarter-cycle starting phase turns the built-in sine into a cosine.
  aInput = oscili(1, 220, -1, 0.25)
  kThird = line(0, p3, 0.5)

  ; The four weights are DC, fundamental, second and third harmonic.
  aList = chebyshevpoly2(aInput, 0, 1, 0, kThird)

  kWeights[] fillarray 0, 1, 0, 0
  kWeights[3] = kThird
  aArray = chebyshevpoly2(aInput, kWeights)

  ; Shape the output volume without changing the input amplitude.
  aEnvelope = linseg(0, 0.02, 1, p3 - 0.04, 1, 0.02, 0)
  outs(0.25 * aList * aEnvelope, 0.25 * aArray * aEnvelope)
endin
</CsInstruments>
<CsScore>
i "AddHarmonic" 0 4
e
</CsScore>
</CsoundSynthesizer>

See also

chebyshevpoly, polynomial, GEN13, Waveshaping

Credits

Author Hlöðver Sigurðsson, 2026.

The original chebyshevpoly opcode is by Anthony Kozar.

New in Csound 7.