FreqSpectrum | SuperCollider 3.13.0 Help

Description

A FreqSpectrum represents a sampled function in the frequency domain, in a polar form.

Create a new instance with the given magnitude and phase.// frequency sampled allpass filter design ~size = 128; ~cosTable = Signal.fftCosTable(~size); // design phase for REAL allpass ~randRadian = Array.fill(~size/2 - 1, { pi.bilinrand }); ~phase = Array.with(0.0) ++ ~randRadian ++ Array.with(0.0) ++ (~randRadian.reverse.neg); // 0.0 at DC & Nyquist, otherwise, symmetric random // design allpass spectrum ~spectrum = FreqSpectrum.new(phase: ~phase); // synthesize REAL kernel ~signal = ~spectrum.real.ifft(~spectrum.imag, ~cosTable).real; ~signal.plot("frequency sampled allpass")

Arguments:

magnitude	Frequency domain magnitude. If `nil` set to 1.
phase	Frequency domain phase. If `nil` set to 0.

FreqSpectrum.newComplex(complex)

Create a new instance given a spectrum in complex form.~size = 128; ~cosTable = Signal.fftCosTable(~size); // real signal ~real = Array.fill(~size, { 1.0.bilinrand }).as(Signal); ~imag = Signal.zeroFill(~size); ~real.plot("time domain"); // complex spectrum - cartesian ~complex = ~real.fft(~imag, ~cosTable); // spectrum ~spectrum = FreqSpectrum.newComplex(~complex); ~spectrum.magnitude.plot("magnitude");

FreqSpectrum.logShelf(size, freq0, freq1, gainDC, gainNy, sampleRate)

Create a new Array whose slots are filled with linearly spaced magnitudes to create a log shelf filter.¹ See also: Signal: *logShelf.

Arguments:

size	The size of the spectrum to return.
freq0	The frequeny, at which to begin transition from gainDC to gainNy, in Hz.
freq1	The frequeny, at which to end transition from gainDC to gainNy, in Hz.
gainDC	The gain at DC, in dB.
gainNy	The gain at Nyquist, in dB.
sampleRate	The sample rate, in Hz.

FreqSpectrum.powerLaw(size, beta: 0)

Return a power-law spectrum. Magnitude at Nyquist is normalized to 1.

Arguments:

size

The size of the spectrum to return.

beta

Power spectral density.

color	beta	dB / octave
brown	2	-6
pink	1	-3
white	0	0
blue	-1	+3
violet	-2	+6

Ambisonic Toolkit

FreqSpectrum.hoaProx(size, radius, order, sampleRate, speedOfSound)

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/Classes/extFreqSpectrum.sc

Return an Array of Higher Order Ambisonic signal (HOA) near-field effect (NFE), proximity radial filter spectra collected by Associated Legendre degree (ℓ).

Arguments:

size	The size of the spectra to return.
radius	Radius, in meters.
order	Ambisonic order.
sampleRate	Sample rate, in Hz.
speedOfSound	Speed of sound, in meters per second.

Discussion:

Offers FIR coefficients, equivalent to the IIR coefficients returned by NFECoeffs: -prox. Implemented as a frequency sampling design, with coefficients returned by HoaOrder: -proxWeights.

NOTE: In most cases, users will use the high level near-field effect (NFE) pseudo-UGen: HoaNFProx.

WARNING: The near-field effect proximity spectra contains infinite magnitudes, and is ill suited for signal processing.

FreqSpectrum.hoaDist(size, radius, order, sampleRate, speedOfSound)

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/Classes/extFreqSpectrum.sc

Return an Array of Higher Order Ambisonic signal (HOA) near-field effect (NFE), distance radial filter spectra collected by Associated Legendre degree (ℓ).

Arguments:

size	The size of the spectra to return.
radius	Radius, in meters.
order	Ambisonic order.
sampleRate	Sample rate, in Hz.
speedOfSound	Speed of sound, in meters per second.

Discussion:

Offers spectra, equivalent to those returned by NFECoeffs: -dist. Implemented as a frequency sampling design, with coefficients returned by HoaOrder: -distWeights. See also: Signal: *hoaDist.

NOTE: In most cases, users will use the high level near-field effect (NFE) pseudo-UGen: HoaNFDist.

FreqSpectrum.hoaCtrl(size, encRadius, decRadius, order, sampleRate, speedOfSound)

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/Classes/extFreqSpectrum.sc

Return an Array of Higher Order Ambisonic signal (HOA) near-field effect (NFE), control radial filter spectra collected by Associated Legendre degree (ℓ).

Arguments:

size	The size of the spectra to return.
encRadius	Encoding radius, in meters.
decRadius	Decoding radius, in meters.
order	Ambisonic order.
sampleRate	Sample rate, in Hz.
speedOfSound	Speed of sound, in meters per second.

Discussion:

Offers spectra, equivalent to those returned by NFECoeffs: -ctrl. Implemented as a frequency sampling design, with coefficients returned by HoaOrder: -ctrlWeights. See also: Signal: *hoaCtrl.( ~size = 4096; ~order = 2; ~sampleRate = 44100; ~speedOfSound = AtkHoa.speedOfSound; ~refRadius = AtkHoa.refRadius; ~theta = (pi/4).rand2; ~phi = (pi/4).rand2; ~radius = 1.0.rrand(2.0); // design spectra ~hoaOrder = ~order.asHoaOrder; ~angularCoeffs = ~hoaOrder.sph(~theta, ~phi); ~radialSpectra = FreqSpectrum.hoaCtrl(~size, ~radius, ~refRadius, ~order, ~sampleRate, ~speedOfSound); // design encoding spectra @ [ ~theta, ~phi, ~radius ] ~encodingSpectra = ~radialSpectra[~hoaOrder.l].collect({ arg spectrum, index; var newSpec = spectrum.deepCopy.scale(~angularCoeffs[index].abs); ~angularCoeffs[index].isNegative({ newSpec = newSpec.neg }); newSpec }); // view! ~encodingSpectra.do({ arg spectra, index; (spectra.magnitude.keep((~size/2 + 1).asInteger) + -120.dbamp).ampdb.plot(format("Encoding magnitude [ %, %, % ] index: %.", ~theta.raddeg.round(1e-2), ~phi.raddeg.round(1e-2), ~radius.round(1e-2), index))}) )

NOTE: In most cases, users will use the high level near-field effect (NFE) pseudo-UGen: HoaNFCtrl.

FreqSpectrum.hoaFocl(size, radius, order, window: 'reg', sampleRate, speedOfSound)

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/Classes/extFreqSpectrum.sc

Return an Array of Higher Order Ambisonic signal (HOA) near-field effect (NFE), focalisation radial filter spectra collected by Associated Legendre degree (ℓ).

Arguments:

size

The size of the spectra to return.

radius

Radius, in meters.

order

Ambisonic order.

window

Angular weighting window.

`\reg`	Regularised²
`\hp`	(Butterworth) High Pass³
`\cos`	Cosine⁴
`\sin`	Sine⁵

sampleRate

Sample rate, in Hz.

speedOfSound

Speed of sound, in meters per second.

Discussion:

Offers zero phase spectra; implemented as a frequency sampling design, with coefficients returned by HoaOrder: -foclWeights. See also: Signal: *hoaFocl.

FreqSpectrum.hoaMultiBandFocl(size, radius, beamDict, dim: 3, match: 'amp', numChans, order, window: 'reg', sampleRate, speedOfSound)

From extension in /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/Classes/extFreqSpectrum.sc

Return an Array of Higher Order Ambisonic signal (HOA) filter spectra combining multi-band beamforming and near-field effect (NFE) focalisation, collected by Associated Legendre degree (ℓ).

Arguments:

size

The size of the spectra to return.

radius

Radius, in meters. Set to nil to exclude focalisation.

beamDict

A dictionary specifying beam shapes and edge frequencies.

See Beaming & Decoder Matching and discussion below.

dim

The number of dimensions: 2D or 3D.

match

Matching criteria, see Beaming & Decoder Matching:

`\amp`	pressure (loudspeaker sum)
`\rms`	spherical harmonic energy
`\energy`	loudspeaker energy

NOTE: Prepend f to include focalisation in normalisation. E.g., \frms.

numChans

Number of loudspeakers.

NOTE: Must be set when choosing match: \energy.

order

Ambisonic order.

window

Focalisation angular weighting window. See *hoaFocl.

NOTE: Ignored if radius is set to nil.

sampleRate

Sample rate, in Hz.

speedOfSound

Speed of sound, in meters per second.

Discussion:

Offers zero phase spectra; implemented as a frequency sampling design, with coefficients returned by *logShelf and *hoaFocl. See also: Signal: *hoaMultiBandFocl.

One band, with focalisation normalized for spherical harmonic energy.~size = 4096; ~sampleRate = 44100; ~order = 3; // --- // one band ~beamDict = Dictionary.with(*[ // beams shapes \beamShapes-> [ \basic ], ]); ~radius = (AtkHoa.refRadius / 2); ~match = \frms; ~spectra = FreqSpectrum.hoaMultiBandFocl(~size, ~radius, beamDict: ~beamDict, match: ~match, order: ~order, sampleRate: ~sampleRate); ~spectra.do({ arg spectrum, i; (spectrum.magnitude + -120.0.dbamp).ampdb.plot("Deegree: % ".format(i), minval: -60.0, maxval: 10.0) });

Two bands, normalized for spherical harmonic energy, with focalisation normalized for pressure.~size = 4096; ~sampleRate = 44100; ~order = 3; // --- // two band ~beamDict = Dictionary.with(*[ // beams shapes \beamShapes-> [ \basic, \energy ], // \basic: 0.0 - 1400.0 Hz // \energy: 2800.0 - 22050.0 Hz \edgeFreqs-> [ 1400.0, 2800.0 ], ]); ~radius = (AtkHoa.refRadius / 2); ~match = \rms; ~spectra = FreqSpectrum.hoaMultiBandFocl(~size, ~radius, beamDict: ~beamDict, match: ~match, order: ~order, sampleRate: ~sampleRate); ~spectra.do({ arg spectrum, i; (spectrum.magnitude + -120.0.dbamp).ampdb.plot("Deegree: % ".format(i), minval: -60.0, maxval: 10.0) });

Three bands, normalized for pressure, with focalisation normalized for pressure.~size = 4096; ~sampleRate = 44100; ~order = 3; // --- // three band ~beamDict = Dictionary.with(*[ // beams shapes \beamShapes-> [ \basic, \energy, \controlled ], // \basic: 0.0 - 700.0 Hz // \energy: 1400.0 - 4000.0 Hz // \controlled: 8000.0 - 22050.0 Hz \edgeFreqs-> [ 700.0, 1400.0, 4000.0, 8000.0 ], ]); ~radius = (AtkHoa.refRadius / 2); ~match = \amp; ~spectra = FreqSpectrum.hoaMultiBandFocl(~size, ~radius, beamDict: ~beamDict, match: ~match, order: ~order, sampleRate: ~sampleRate); ~spectra.do({ arg spectrum, i; (spectrum.magnitude + -120.0.dbamp).ampdb.plot("Deegree: % ".format(i), minval: -60.0, maxval: 10.0) });

Three bands, normalized for spherical harmonic energy. No focalisation.~size = 4096; ~sampleRate = 44100; ~order = 3; // --- // three band ~beamDict = Dictionary.with(*[ // beams shapes \beamShapes-> [ \basic, \energy, \controlled ], // \basic: 0.0 - 700.0 Hz // \energy: 1400.0 - 4000.0 Hz // \controlled: 8000.0 - 22050.0 Hz \edgeFreqs-> [ 700.0, 1400.0, 4000.0, 8000.0 ], ]); ~match = \rms; ~spectra = FreqSpectrum.hoaMultiBandFocl(~size, beamDict: ~beamDict, match: ~match, order: ~order, sampleRate: ~sampleRate); ~spectra.do({ arg spectrum, i; (spectrum.magnitude + -120.0.dbamp).ampdb.plot("Deegree: % ".format(i), minval: -60.0, maxval: 10.0) });

Inherited class methods

Instance Methods

.size

FreqSpectrum size.

Frequeny

.freqs(sampleRate)

Coefficient frequencies.

.ks

Coefficient numbers.

.averageFreq(sampleRate)

Energy weighted average frequency.

.bandwidth(fraction, sampleRate)

Return bandwidth, in Hz.

Arguments:

fraction

If < 1.0, return fractional power containment bandwidth.

If nil, return equivalent bandwidth.

sampleRate

The sample rate, in Hz.

Magnitude & Energy

.magnitude

.magnitude = value

Set or return the magnitude.

.peakMagnitude

Return the peak magnitude.

.averageMagnitude(mindb: -120.0)

Return energy weighted average magnitude.

Arguments:

mindb

a minimum value in dB to clip amplitude response to. Prevents singularities.

.rho

Synonym for -magnitude

.energyDensity

Return the energy density.

.totalEnergy

Return the total energy.

.rms

Return the RMS.

.scale(scale)

Scale the magnitude in place.

.normalize

Normalize the magnitude in place to 1.~size = 128; ~cosTable = Signal.fftCosTable(~size); // real signal ~real = Array.fill(~size, { 1.0.bilinrand }).as(Signal); ~imag = Signal.zeroFill(~size); // complex spectrum - cartesian ~complex = ~real.fft(~imag, ~cosTable); // spectrum ~spectrum = FreqSpectrum.newComplex(~complex).normalize; ~spectrum.magnitude.plot("magnitude");

.allpass

Reset the magnitude in place to 1.

Phase & Delay

.phase

.phase = value

Set or return the phase.

.theta

Synonym for -phase

.angle

Synonym for -phase

.neg

Add pi to phase.

.invert

Add pi to phase in place.

.rotatePhase(phase)

Rotate the phase by a value in radians, in place. See also Signal: -rotatePhase.

.rotateWave(phase)

Rotate the time domain waveform by a value in radians, in place. See also Signal: -rotateWave.

.principalPhase

Return a spectrum with phase wrapped, preserving the magnitude, in place. See also -continuousPhase.

.continuousPhase(groupDelay)

Return a spectrum with phase unwrapped, preserving the magnitude, in place.⁶ See also -principalPhase.

Arguments:

groupDelay

group delay analysis, in samples.

.linearPhase(sym: false)

Return a linear phase spectrum, preserving the magnitude, in place. See also Signal: -linearPhase.

Arguments:

sym	a Boolean indicating whether the window is symmetric or periodic. Default is false.

.minimumPhase(mindb: -120.0)

Return a minimum phase spectrum, preserving the magnitude, in place.⁷ See also Signal: -minimumPhase.

Arguments:

mindb

a minimum value in dB to clip amplitude response to. Reduces time aliasing.

.gaussianPhase

Return a gaussian noise phase spectrum, preserving the magnitude, in place. See also Signal: -gaussianPhase.

.phaseDelay

Return phase delay analysis, in samples.

NOTE: Measure at DC is returned as the mean of the delay at k = +/-1.

WARNING: For correct analysis, phase should be continuous.

.groupDelay(mindb: -90.0)

Return group delay analysis, in samples.⁸

Arguments:

mindb

a minimum value in dB to clip amplitude response to. Prevents singularities.

NOTE: If set to -inf, returns group delay via central fininte difference, assuming phase is continuous.⁹

.phaseOffset(mindb: -90.0, sampleRate)

Return phase offset analysis, aka intercept phase, in radians.¹⁰

WARNING: For correct analysis, phase should be continuous.

Arguments:

mindb	a minimum value in dB to clip amplitude response to. Prevents singularities. NOTE: If set to `-inf`, returns group delay via central fininte difference, assuming phase is continuous. See also -groupDelay
sampleRate	The sample rate, in Hz.

.averagePhaseDelay

Return energy weighted average phase delay analysis, in samples. See also -phaseDelay

WARNING: For correct analysis, phase should be continuous.

.averageGroupDelay(mindb: -90.0)

Return energy weighted average group delay analysis, in samples. See also -groupDelay

Arguments:

mindb

a minimum value in dB to clip amplitude response to. Prevents singularities.

NOTE: If set to -inf, returns group delay via central fininte difference, assuming phase is continuous.

.averagePhaseOffset(mindb: -90.0, sampleRate)

Return energy weighted average phase offset analysis, aka intercept phase, in radians. See also -phaseOffset

WARNING: For correct analysis, phase should be continuous.

Arguments:

mindb	a minimum value in dB to clip amplitude response to. Prevents singularities. NOTE: If set to `-inf`, returns group delay via central fininte difference, assuming phase is continuous. See also -groupDelay
sampleRate	The sample rate, in Hz.

Conversion & Complex

.asPolar

Return Polar.

.asComplex

Return Complex.

.real

Return the real part of the complex spectrum.

.imag

Return the imaginary part of the complex spectrum.

Inherited instance methods

Examples

TBD

[1] - Baird, J; Jackson, B; and D McGrath. “Raised Cosine Equalization Utilizing Log Scale Filter Synthesis.“ 117th Audio Engineering Society Convention, San Francisco, USA. October 2004. Permalink: http://www.aes.org/e-lib/browse.cfm?elib=12914

[2] - S. Favrot and J. Buchholz. 2010. “Impact of Regularization of near Field Coding Filters for 2D and 3D Higher-Order Ambisonics on Auditory Distance Cues.” in Proc. of the 2nd International Symposium on Ambisonics and Spherical Acoustics. Paris.

[3] - J. Daniel. 2003. “Spatial sound encoding including near field effect: Introducing distance coding filters and a viable, new ambisonic format,” in Proc. of the 23rd International Conference of the Audio Engineering Society.

[4] - J. Ahrens and S. Spors. 2009. “Spatial encoding and decoding of focused virtual sound sources,” in Proc. of the 1st Ambisonics Symposium. Paris.

[5] - A sine function variation of the window proposed by Ahrens & Spors.

[6] - Panzer, J; and L Ferekidis. “The Use of Continuous Phase for Interpolation, Smoothing and Forming Mean Values of Complex Frequency Response Curves.” 116th Audio Engineering Society Convention, Berlin, Germany. May 2004. Permalink: http://www.aes.org/e-lib/browse.cfm?elib=12652

[7] - Damera-Venkata, N, and B.L Evans. “Optimal Design of Real and Complex Minimum Phase Digital FIR Filters.” 1999 IEEE International Conference on Acoustics, Speech, and Signal Processing. Proceedings. ICASSP99 (Cat. No.99CH36258), vol. 3, 1999, pp. 1145–1148 vol.3.

[8] - Smith, J.O. "Numerical Computation of Group Delay", in Introduction to Digital Filters with Audio Applications, https://ccrma.stanford.edu/~jos/filters/Numerical_Computation_Group_Delay.html, online book, September 2007 edition, accessed 16 July 2019.

[9] - Boashash, B. “Estimating and Interpreting the Instantaneous Frequency of a Signal. II. Algorithms and Applications.” Proceedings of the IEEE, vol. 80, no. 4, 1992, pp. 540–568.

[10] - Preis, D. "Phase Distortion and Phase Equalization in Audio Signal Processing—A Tutorial Review", Journal Audio Engineering Society, vol. 30, no. 11, 1982, pp. 774-794. Permalink: http://www.aes.org/e-lib/browse.cfm?elib=3810

helpfile source: /Library/Application Support/SuperCollider/downloaded-quarks/SignalBox/HelpSource/Classes/FreqSpectrum.schelp
link::Classes/FreqSpectrum::

FreqSpectrum : Number : Magnitude : Object Extension

FreqSpectrum.new(magnitude, phase)

Arguments:

FreqSpectrum.newComplex(complex)

FreqSpectrum.logShelf(size, freq0, freq1, gainDC, gainNy, sampleRate)

Arguments:

FreqSpectrum.powerLaw(size, beta: 0)

Arguments:

FreqSpectrum.hoaProx(size, radius, order, sampleRate, speedOfSound)

Arguments:

Discussion:

FreqSpectrum.hoaDist(size, radius, order, sampleRate, speedOfSound)

Arguments:

Discussion:

FreqSpectrum.hoaCtrl(size, encRadius, decRadius, order, sampleRate, speedOfSound)

Arguments:

Discussion:

FreqSpectrum.hoaFocl(size, radius, order, window: 'reg', sampleRate, speedOfSound)

Arguments:

Discussion:

FreqSpectrum.hoaMultiBandFocl(size, radius, beamDict, dim: 3, match: 'amp', numChans, order, window: 'reg', sampleRate, speedOfSound)

Arguments:

Discussion:

.size

.freqs(sampleRate)

.ks

.averageFreq(sampleRate)

.bandwidth(fraction, sampleRate)

Arguments:

.magnitude

.magnitude = value

.peakMagnitude

.averageMagnitude(mindb: -120.0)

Arguments:

.rho

.energyDensity

.totalEnergy

.rms

.scale(scale)

.normalize

.allpass

.phase

.phase = value

.theta

.angle

.neg

.invert

.rotatePhase(phase)

.rotateWave(phase)

.principalPhase

.continuousPhase(groupDelay)

Arguments:

.linearPhase(sym: false)

Arguments:

.minimumPhase(mindb: -120.0)

Arguments:

.gaussianPhase

.phaseDelay

.groupDelay(mindb: -90.0)

Arguments:

.phaseOffset(mindb: -90.0, sampleRate)

Arguments:

.averagePhaseDelay

.averageGroupDelay(mindb: -90.0)

Arguments:

.averagePhaseOffset(mindb: -90.0, sampleRate)

Arguments:

.asPolar

.asComplex

.real

.imag

FreqSpectrum : Number : Magnitude : Object
Extension