SignalBox : Read Me
========================
_A set of tools for signal analysis and design in the Time and Frequency domains._

Methods of the _extension_ __FreqSpectrum__ class include:

### Frequency

| Method | Description |
| ----------- | ----------- |
| `averageFreq` | Energy weighted average frequency. |
| `bandwidth` | Return bandwidth, in Hz. |


### Magnitude & Energy

| Method | Description |
| ----------- | ----------- |
| `peakMagnitude` | Return the peak magnitude. |
| `averageMagnitude` | Return energy weighted average magnitude. |
| `energyDensity` | Return the energy density. |
| `totalEnergy` | Return the total energy. |
| `rms` | Return the RMS. |
| `normalize` | Normalize the magnitude in place to 1. |
| `allpass` | Reset the magnitude in place to 1. |


### Phase & Delay
| Method | Description |
| ----------- | ----------- |
| `rotatePhase` | Rotate the phase by a value in radians, in place. |
| `rotateWave` | Rotate the time domain waveform by a value in radians, in place. |
| `principalPhase` | Return a spectrum with phase wrapped, preserving the magnitude, in place. |
| `continuousPhase` | Return a spectrum with phase unwrapped, preserving the magnitude, in place. |
| `linearPhase` | Return a linear phase spectrum, preserving the magnitude, in place. |
| `minimumPhase` | Return a minimum phase spectrum, preserving the magnitude, in place. |
| `gaussianPhase` | Return a gaussian noise phase spectrum, preserving the magnitude, in place. |
| `phaseDelay` | Return phase delay analysis, in samples. |
| `groupDelay` | Return group delay analysis, in samples. |
| `phaseOffset` | Return phase offset analysis, aka intercept phase, in radians. |
| `averagePhaseDelay` | Return energy weighted average phase delay analysis, in samples. |
| `averageGroupDelay` | Return energy weighted average group delay analysis, in samples. |
| `averagePhaseOffset` | Return energy weighted average phase offset analysis, aka intercept phase, in radians. |



Extensions to the __Buffer__ class include:

### Wave packet

| Method | Description |
| ----------- | ----------- |
| `packet1` | Fill this buffer with a series of Hann enveloped cosine wave harmonics using specified amplitudes. |
| `packet2` | Fill this buffer with a series of Hann enveloped cosine wave harmonics using specified frequencies and amplitudes. |
| `packet3` | Fill this buffer with a series of Hann enveloped cosine wave harmonics using specified frequencies, amplitudes, and initial phases. |


Extensions to the __SequenceableCollection__ class include:

| Method | Description |
| ----------- | ----------- |
| `schroederIntegrate` | Returns the Schroeder Integral of a collection (also known as inversed time integration). |


Extensions to the __Signal__ class include:


### Cosine basis

| Method | Description |
| ----------- | ----------- |
| `*cosineFill` | Fill a Signal of the given size with a sum of cosines at the given amplitudes and phases. |
| `cosineFill` | A sum of cosines with the given amplitudes and phases, returned in place. |
| `cosineFill2` | A sum of cosines with the given harmonics, amplitudes and phases, returned in place. |


### Wave packet

| Method | Description |
| ----------- | ----------- |
| `*readPacket` | Read a Hann enveloped wave packet from a soundfile. |
| `*packetFill` | Fill a Signal of the given size with a sum of Hann enveloped cosines at the given amplitudes and phases. |
| `packetFill` | A sum of Hann enveloped cosines at the given amplitudes and phases, returned in place. |
| `packetFill2` | A sum of Hann enveloped cosines with the given harmonics, amplitudes and phases, returned in place. |


### Waveshaping

| Method | Description |
| ----------- | ----------- |
| `*chebyTFill` | Fill a Signal of the given size with a sum of Chebyshev polynomials of the first kind at the given amplitude scaling. |
| `*chebyUFill` | Fill a Signal of the given size with a sum of Chebyshev polynomials of the second kind at the given amplitude scaling. |
| `*chebyTUFill` | Return an array of two Signals of the given size. The first signal is a sum of Chebyshev polynomials of the first kind, while the second is a sum of the second kind. |
| `*chebyTUFill2` | Return an array of two Signals of the given size. The first signal is a sum of Chebyshev polynomials of the first kind, while the second is a sum of the second kind. |
| `addChebyshevT` | Add a single Chebyshev polynomials of the first kind to myself with the given harmonic and amplitude scaling. |
| `addChebyshevU` | Add a single Chebyshev polynomials of the second kind to myself with the given harmonic and amplitude scaling. |
| `*shaperT` | Performs waveshaping of a cosine wave by indexing into the supplied table, returning a sum of cosine waves. |
| `*shaperU` | Performs waveshaping of a cosine wave by indexing into the supplied table, followed by multiplication with a sine wave. Returns a sum of sine waves. |
| `*shaperTU` | Performs quadrature waveshaping of an analytic cosine wave by indexing into the supplied tables. Returns a sum of cosine and sine waves. |
| `normalizeShaperT` | Given a Signal filled with a sum of Chebyshev polynomials of the first kind, return a table to normalize the amplitude or power of a waveshaped result returned by Shaper. |
| `normalizeShaperU` | Given a Signal filled with a sum of Chebyshev polynomials of the second kind, return a table to normalize the amplitude or power of a waveshaped result returned by Shaper. |
| `normalizeShaperTU` | Given a Signal filled with a sum of Chebyshev polynomials of the first kind, and another filled with a sum of Chebyshev polynomials of the second kind, return a table to normalize the amplitude or power of a waveshaped result returned by Shaper. |


### Reading & writing

| Method | Description |
| ----------- | ----------- |
| `*read` | Read a soundfile. |
| `*readWave` | Read a periodic waveform from a soundfile. |
| `write` | Writes the entire Signal to a soundfile. |
| `writeFile` | Writes the entire Signal to a file, where every chunk of four bytes is a 32-bit floating point sample. |


### Fourier Transform

| Method | Description |
| ----------- | ----------- |
| `*rfftCosTable` | Fill a Signal with the cosine table needed by the Real-FFT methods. |
| `*rfftTwoCosTable` | Fill a Signal with the cosine table needed by the Real-FFT-Two methods. |
| `fftToRfft` | Return a complex Real-FFT spectrum from a complex FFT spectrum. |
| `rfftToFft` | Return a complex FFT spectrum from a complex Real-FFT spectrum. |
| `rfft` | Perform a Real-FFT on a real signal. |
| `irfft` | Perform an inverse Real-FFT on a real and imaginary signal. |
| `rfftTwo` | Perform a Real-FFT on two real signals. |
| `irfftTwo` | Perform an inverse Real-FFT on two real and imaginary signals. |
| `dft` | Perform a DFT on a real and imaginary signal. |
| `idft` | Perform an inverse DFT on a real and imaginary signal. |
| `dftZoom` | Perform a Zoom DFT on a real and imaginary signal. |
| `rdftZoom` | Perform a Zoom DFT on a real signal. |
| `goertzel` | Return individual terms of a DFT on a real and imaginary signal. |
| `rgoertzel` | Return individual terms of a DFT on a real signal. |
| `harmsAmpsPhases` | Returns a rank 2 List containing harmonic numbers, amplitudes and phases, suitable for use with -sineFill2, -cosineFill2 and -packetFill2. |


### Chirp z-Transform

| Method | Description |
| ----------- | ----------- |
| `czt` | Perform a Chirp z-Transform on a real and imaginary signal. |
| `rczt` | Perform a Chirp z-Transform on a real signal. |


### Cepstrum

| Method | Description |
| ----------- | ----------- |
| `rceps` | Return the real part of the cepstrum of a real signal. |
| `irceps` | Return the real part of the inverse of the real part of the cepstrum. |


### Analytic & Hilbert

| Method | Description |
| ----------- | ----------- |
| `*analyticFill` | Return a complex analytic Signal of the given size with a sum of cosines and a sum of sines at the given amplitudes and phases. |
| `*hilbert` | Hilbert Transform: Return complex Hilbert Transform coefficients. |
| `analytic` | Hilbert Transform: Return a complex analytic signal from a real signal. |
| `instantaneousFreq` | Return the instantaneous frequency from a real signal. |


### Rotation & Phase

| Method | Description |
| ----------- | ----------- |
| `rotateWave` | Rotate the Signal by a value in radians, in place. |
| `rotatePhase` | Rotate the phase of Signal by a value in radians, in place. |
| `linearPhase` | Return a linear phase kernel, preserving the magnitude, in place. |
| `minimumPhase` | Return a minimum phase kernel, preserving the magnitude, in place. |
| `even` | Return the even part of a signal. |
| `odd` | Return the odd part of a signal. |

### RMS & Magnitude

| Method | Description |
| ----------- | ----------- |
| `rms` | Return the RMS of a signal. |
| `peakMagnitude` | Return the peak of the frequency domain magnitude of a signal. |
| `normalizeMagnitude` | Normalize the Signal in place such that the maximum magnitude in the frequency domain is 1. |

### Convolution

| Method | Description |
| ----------- | ----------- |
| `convolve` | Convolve myself with a signal. |
| `periodicConvolve` | Periodic convolve myself with a signal. |
| `partConvolve` | Partition convolve myself with a signal. |
| `estimateFreq` | Estimate periodic frequency via autocorrelation in the time domain. |

### Resampling

| Method | Description |
| ----------- | ----------- |
| `resize` | Returns a new Signal resampled in the frequency domain to a new size. |


Extensions to the __Wavetable__ class include:

| Method | Description |
| ----------- | ----------- |
| `*chebyTFill` | Fill a Wavetable of the given size with a sum of Chebyshev polynomials of the first kind at the given amplitude scaling. |
| `*chebyUFill` | Fill a Wavetable of the given size with a sum of Chebyshev polynomials of the second kind at the given amplitude scaling. |
| `*chebyTUFill` | Return an array of two Wavetables of the given size. The first wavetable is a sum of Chebyshev polynomials of the first kind, while the second is a sum of the second kind. |
| `*chebyTUFill2` | Return an array of two Wavetables of the given size. The first wavetable is a sum of Chebyshev polynomials of the first kind, while the second is a sum of the second kind. |


&nbsp;

&nbsp;

Installing
==========

Distributed via
[SC3 SignalBox](https://gitlab.com/dxarts/projects/SignalBox.quark).

Start by reviewing the Quark installation instructions
[found here](https://github.com/supercollider-quarks/quarks#installing). See
also [Using Quarks](http://doc.sccode.org/Guides/UsingQuarks.html).

With [git](https://git-scm.com/) installed, you can easily install the
[SC3 SignalBox](https://gitlab.com/dxarts/projects/SignalBox.quark)
directly by running the following line of code in SuperCollider:

    Quarks.install("https://gitlab.com/dxarts/projects/SignalBox.quark");



Feedback and Bug Reports
========================

Known issues are logged at
[GitLab](https://gitlab.com/dxarts/projects/SignalBox.quark/issues).

&nbsp;


List of Changes
---------------

Version 0.1.15

*  New features:
    *  Buffer:-packet1, -packet2, -packet3, -packet1Msg, -packet2Msg, -packet3Msg
    *  Signal:-estimateFreq, -harmsAmpsPhases
    *  Signal:*chebyTFill, *chebyUFill, *chebyTUFill, *chebyTUFill2
    *  Signal:-chebyTFill, -chebyUFill
    *  Signal:-addChebyshevT, -addChebyshevU
    *  Signal:*shaperT, *shaperU, *shaperTU
    *  Signal:-shaper, -shaperT, -shaperU, -shaperTU
    *  Signal:-normalizeShaper, -normalizeShaperT, -normalizeShaperU, -normalizeShaperTU
    *  Wavetable:*chebyTFill, *chebyUFill, *chebyTUFill, *chebyTUFill2


Version 0.1.14

*  Issue fixes:
    *  Signal:-resize: fix DC aliasing & Nyquist scaling


Version 0.1.13

*  New features:
    *  SequenceableCollection:-schroederIntegrate


Version 0.1.12

*  New features:
    *  FreqSpectrum:-averageMagnitude

*  Issue fixes:
    *  FreqSpectrum:-bandwidth: fix Integer overflow

*  Refactor:
    *  remove inline warnings
    *  Signal:-dft: direct method


Version 0.1.11

*  New features:
    *  FreqSpectrum:-rms
    *  FreqSpectrum:-bandwidth


Version 0.1.10

*  New features:
    *  Signal:-instantaneousFreq
    *  FreqSpectrum:-energyDensity
    *  FreqSpectrum:-totalEnergy
    *  FreqSpectrum:-phaseOffset
    *  FreqSpectrum:-averageGroupDelay
    *  FreqSpectrum:-averagePhaseDelay
    *  FreqSpectrum:-averagePhaseOffset
    *  FreqSpectrum:-averageFreq

*  Refactor:
    *  continuousPhase: optimized angle conform
    *  groupDelay: include direct differentiation


Version 0.1.9

*  New features:
    *  FreqSpectrum:-continuousPhase


Version 0.1.8

*  New features:
    *  power law chirps


Version 0.1.7

*  New features:
    *  power law magnitude
    *  periodic power law noise
    *  gaussian white noise
    *  gaussian noise phase
    *  periodic & partition convolution

*  Refactor:
    *  rfftTwo & irfftTwo now returns IdentityDictionary

*  Issue fixes:
    *  Signal: hilbert correct zero padding


Version 0.1.6

*  New features:
    *  windowed sinc lowpass method
    *  gaussian filter bank method

*  Issue fixes:
    *  Signal:-hilbert correct zero padding

Version 0.1.5

*  Refactor:
    *  Migrate repository from [GitHub](https://github.com/ambisonictoolkit/SignalBox) to [GitLab](https://gitlab.com/dxarts/projects/SignalBox.quark)

Version 0.1.4

*  Issue fixes:
    *  Spectrum name collision with TuningLib, rename as FreqSpectrum

Version 0.1.3

*  New features:
    *  Spectrum class
    *  Allpass instance method
    *  Phase and Group delay analysis

*  Refactor:
    *  Deprecate Array class methods
    *  Deprecate linear and minimum phase class methods

*  Issue fixes:
    *  Signal:-read numFrames calculation

Version 0.1.2

*  New features:
    *  log shelf filter coefficients

Version 0.1.1

*  New features:
    *  constant-overlap-add (COLA) windowing

*  Documentation Updates:
    *  Added algorithm citations
    *  Correct Signal -readWave example

Version 0.1.0

*  First Public Release.

&nbsp;

Credits
=======

Joseph Anderson 2019-2026.

* J Anderson : [[e-mail]](mailto:joanders[at]uw.edu)

&nbsp;

The development of SignalBox for SuperCollider3 is
supported by
[DXARTS, Center for Digital Arts and Experimental Media](https://dxarts.washington.edu/).

&nbsp;


Contributors
------------

Version 0.1.13 - 0.1.15
*  Joseph Anderson (@joslloand)

Version 0.1.12
*  Joseph Anderson (@joslloand)
*  Michael McCrea (@mtmccrea)

Version 0.1.0 - 0.1.11
*  Joseph Anderson (@joslloand)
