lanceputnam/gamma

Generic (Sound) Synthesis Library

Gamma

Generic Synthesis C++ Library

About

Gamma is a cross-platform, C++ library for doing generic synthesis and filtering of signals. It contains helpful mathematical functions, types, such as vectors and complex numbers, an assortment of sequence generators, and many other objects for signal processing tasks. It is oriented towards real-time sound and graphics synthesis, but is equally useful for non-real-time tasks.

Compilation Instructions

The source code can either be built into a library or directly compiled from source into an application. In the following, the base directory is where this README file is located.

Building a Library

Make (Linux, OS X, mingw)

In most cases, simply running

make

will build the library with automatically detected platform settings. See Makefile.config for other build options.

There are several other rules within Makefile. These are:

make			- builds static library
make install		- installs library into DESTDIR
make clean		- removes binaries from build folder
make test		- performs unit tests

The script run.sh can be used to compile and run examples and other source files against the Gamma library. For example,

./run.sh examples/oscillator/sine.cpp

To only compile the source file without running, include AUTORUN=0 after the source file. Binaries are located in the automatically generated build/ directory. On OSX, the Gamma library will be linked to the pre-compiled dependent libraries in external/lib_osx. On Linux, use apt-get to install the necessary dependent libraries.

Xcode (OS X)

You may also build the library using the supplied Xcode project.

1. Open project/xcode/gamma.xcodeproj
2. Build the target libgamma{.a, .dylib}. The library will be in project build folder.

Compiling Directly From Source

Gamma can easily be compiled directly from source into an existing project.

Make sure to pass in the following flags to the compiler:

-D__STDC_CONSTANT_MACROS
-finline-functions (or -O3)
-fpeel-loops

Dependencies

PortAudio is required ONLY if you are using Gamma's AudioIO class (defined in Gamma/AudioIO.h). If you do not wish to use audio i/o, then pass the flag

NO_AUDIO_IO=1

into make or, if not using make, exclude src/AudioIO.cpp from your project.

libsndfile may be used as the backend for the SoundFile class by passing the flag

USE_LIBSNDFILE=1

into make.

License

Gamma is distributed under a permissive free software license. Please see the LICENSE file for details.

gamma's Issues

Singleton master domain not enforced

Whenever master() is called, a new instance is allocated rather than reused:

https://github.com/LancePutnam/Gamma/blob/devel/src/Domain.cpp#L114

Make it easier to find via cmake or pkg-config?

It would be nice to add a GammaConfig.cmake and a gamma.pc file to make this easier to use as a dependency.

Sequence Interpolation Doxygen module?

Lance, how do you feel about adding a Sequence Interpolation module for classes in namespace iplSeq?
We already have one for the classes in namespace ipl called Interpolation.

It would require the addition of the following Doxygen comment to each class:

/// \ingroup Sequence Interpolation

or maybe just:
/// \ingroup iplSeq

members of iplSeq:: :
Base,Trunc,Linear,Cubic,Cosine

LFO Line2 Mod Errors

The Line2() output for the LFO class behaves incorrectly with mod values >.98 and <.02. Behavior should be predictable for all values -1 to +1.

Curve: reorder start and end arguments

Curve
LJP: The Curve arguments are ordered end then start due to a complicated history; basically the addition of new features. It makes the most sense to reverse them at this point.
MW: I support changing the order of arguments to make it make more sense.
DA: Which line(s) of code need changing?

Inconsistent LFO heights

The LFO class has inconsistent amplitudes for the various shape outputs.

As an example, LFO.pulse() runs from -.5 to +.5, while LFO.cos() runs from -1.0 to +1.0.

It would be great if these were standardized. Currently, writing an LFO selector means testing the height of each shape and adding a scalar for the inconsistent shapes.

My vote would be for -.5 to +.5 for all bipolar LFOs, as these would maintain the same amplitude as the unipolar LFOs. I can submit a pull request with code, but I'd like to know the intended design before I do so.

unable to run example.

ALSA lib pcm_dsnoop.c:638:(snd_pcm_dsnoop_open) unable to open slave
ALSA lib pcm_dmix.c:1108:(snd_pcm_dmix_open) unable to open slave
ALSA lib pcm.c:2565:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.rear
ALSA lib pcm.c:2565:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.center_lfe
ALSA lib pcm.c:2565:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.side
ALSA lib pcm_oss.c:377:(_snd_pcm_oss_open) Unknown field port
ALSA lib pcm_oss.c:377:(_snd_pcm_oss_open) Unknown field port
ALSA lib pcm_usb_stream.c:486:(_snd_pcm_usb_stream_open) Invalid type for card
ALSA lib pcm_usb_stream.c:486:(_snd_pcm_usb_stream_open) Invalid type for card
ALSA lib pcm_dmix.c:1108:(snd_pcm_dmix_open) unable to open slave
Expression 'alsa_snd_pcm_hw_params_set_period_size_near( pcm, hwParams, &alsaPeriodFrames, &dir )' failed in 'src/hostapi/alsa/pa_linux_alsa.c', line: 933
Press 'enter' to quit...

gam::Saw output range: has DC offset and exceeds 1.0

output of below program is:

min: -0.625428, max: 1.02889

is there a way to normalize this output to [-1.0 : 1.0] ?

#include "Gamma/Domain.h"
#include "Gamma/Oscillator.h"

#include <cfloat>
#include <iostream>

using namespace std;

int main()
{
    gam::Domain::master().spu(44100.0f);
    gam::Saw<> saw;
    saw.freq(440.0f);

    float max_s = -FLT_MAX;
    float min_s = FLT_MAX;

    for (int i = 0; i < 44100; i += 1)
    {
        float s = saw();
        if (s > max_s) max_s = s;
        if (s < min_s) min_s = s;
    }

    cout << "min: " << min_s << ", max: " << max_s << endl;
}

Multiple AudioIO Objects and syncing data

I want to be able to bring in audio from multiple AudioIO sources and do processing on the streams in the same space.

I have been reading through the AudioIO.h class and have been thinking I can create a master AudioIO object that has an active callback after calling start(). On additional AudioIO I can open() the device and then call the callback manually to get at the data. Somehow I will want to write this data to a location that the master callback has access to. If I understand correctly these are in different threads when the callback is called. So this makes getting the data from each AudioIO interesting.

Is there a way to use the AudioIO object itself to get a sample/frame? This way I don't have separate threads to pull data from. I will keep the sample rates consistent so it should keep the data itself in sync fairly well.

I was thinking about using this library to make a more sophisticated visual audio tool. It would allow me to connect different objects with wires to build up a synthesizer. However, I am not sure if this library is able to be used that way. Would this library work for this? I am unsure, but this library seems pretty rigid on how it can be used. Is there a different library that might be easier to build a visual editor with?

MSVC 2015 compilation

Gamma compilation is broken again on MS Visual Studio 2015. Replacing pstdint.h with the latest version fixes most of the errors:
http://www.azillionmonkeys.com/qed/pstdint.h

I'm looking to see if the rest of the errors are related to our code, JUCE, or Gamma.

Low Pass filter exploding near Nyquist

gam::Biquad<> (set to type gam::LOW_PASS) is exploding when given feedback. So far, in my testing, I've had it explode in the range of 21-22 kHz with a sampling rate of 44.1 kHz (it stabilizes around 20 kHz). This occurs without any input. You can just feed the previous filter output value back in as the new input.

The feedback noise is extremely high frequency. It's not a stable sine wave, but rather noise. It is hard to hear, but you can see it with a scope or amplitude meter.

DSF antialias() not compiling on Windows

I'm running into an unusual compilation issue on Windows when using the DSF oscillator. If I attempt to call the antialias() function, compilation fails when trying to resolve this->freq() inside of DSF::maxHarmonics().

I've attached two images below. The compiler seems to not see the getter freq() inherited from AccumPhase and is instead complaining that the setter freq(TV v) is missing arguments.

Once I remove the call to antialias() the project compiles as expected.

More consistency with templating

Gamma uses in most of its classes a template type Tv to identify the value type and a Tp type to identify parameter types.

There are a few classes that don't follow this convention (that I have found in a quick scan, there may be others...):

• Chorus, FreqShift, Quantizer, Pluck, in Effects.h : parameters are float not Tp
• ChebyN, Chirp in Effects.h : both parameters and values are templated to the same type
• MonoSynth, Biquad3 in Effects.h : parameters and values are float.
• Pan, AM in Effects.h : is only templated with T used for parameters. The value is templated not for the class but for the individual functions. Maybe for consistency the class should be templated as others?

I think making this consistent throughout will add significant ease in the usage of Gamma as the documentation will have to be checked less often.

macOS 11 build breaks

Hey! I just upgraded to macOS 11 and it seems like it can't find the cmath header anymore.

> make 
CXX src/arr.cpp build/obj/arr.o
clang: warning: include path for libstdc++ headers not found; pass '-stdlib=libc++' on the command line to use the libc++ standard library instead [-Wstdlibcxx-not-found]
src/arr.cpp:4:10: fatal error: 'cmath' file not found
#include <cmath>
         ^~~~~~~
1 error generated.
make: *** [build/obj/arr.o] Error 1

I did a bit of digging around, and it seems like the problem lies in Makefile.common:233.

	CFLAGS += -isysroot $(OSX_SDK_PATH)$(OSX_SDK) -mmacosx-version-min=10.$(OSX_VERSION)

My hunch is that target SDK version and the -mmacosx-version-min have to have the same major version number. If I change the above line to the following, it seems to work.

	CFLAGS += -isysroot $(OSX_SDK_PATH)$(OSX_SDK) -mmacosx-version-min=11.$(OSX_VERSION)

Alternatively, if I simply remove the minimum version flag, it build successfully. See below:

	CFLAGS += -isysroot $(OSX_SDK_PATH)$(OSX_SDK)

Taking a closer look at my SDKs directory, I see the following, which would partially explains my hunch.

> ls /Applications/XCode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/
DriverKit20.0.sdk/ MacOSX.sdk/        MacOSX11.0.sdk@

I'm not intimately familiar with how macOS SDK targeting works, but I thought I'd share my initial investigation. Thanks!

STFT

Eventually , after several minutes, STFT in MAG_FREQ or MAG_PHASE , collects artifacts and corrupt buffers (bins auxs) and reset phases method no work at all.

DelayShift setter

It looks like this setter is implemented incorrectly, as the setter code matches the getter:
https://github.com/LancePutnam/Gamma/blob/master/Gamma/Delay.h#L181

Linker errors on macOS ARM64; Update lib_osx/libportaudio.a

OS: macOS Ventura 13.6
ARCH: Apple M1 (ARM64)

The error:

git clone https://github.com/LancePutnam/Gamma
cd Gamma
make
...
./run.sh examples/synths/Vib.cpp
ld: warning: ignoring file '/XXX/Gamma/external/lib_osx/libportaudio.a': fat file missing arch 'arm64', file has 'x86_64,unknown,i386,ppc'
ld: Undefined symbols:
  _Pa_CloseStream, referenced from:
      gam::AudioIO::~AudioIO() in libGamma.a[14](AudioIO.o)
      gam::AudioIO::close() in libGamma.a[14](AudioIO.o)
      gam::AudioIO::reopen() in libGamma.a[14](AudioIO.o)
      gam::AudioIO::reopen() in libGamma.a[14](AudioIO.o)
...

The remedy:

brew install portaudio
cp /opt/homebrew/lib/libportaudio.a external/lib_osx/libportaudio.a
./run.sh examples/synths/Vib.cpp
Press 'enter' to quit...

I don't love having a compiled library in the repository, but given that it is there, I think it needs updating.

OnePole renamed?

from the Google doc:

OnePole - one-pole smoothing LPF. Couldn’t you also have a one pole HPF? If so, then that should be specified in the name.
Suggested name: Lowpass, SimpleLowpass, Smoothing
Matt suggests: OnePoleLPF
LJP: Yes, it could be either high- or low-pass. The same with a one-zero filter. How could we logically name all these possible filters? LPF1p, LPF1z, HPF1p, HPF1z?
DA: the documentation claims it is a smoothing filter. That makes it LP only, no? Maybe I am misinterpreting your response.
I like OnePoleLPF. LPF1p strikes me as awkward. Why not LP, LPF, or Lowpass? We have no other classes of similar name.

C++11 compatibility

There seems to be some issues in Gamma includes (scl.h) if cstdint is added afterwards.
Lots of header inclusions seem also to be C related (math.h, sodlib.h...), and not C++. This means that the library cannot be mixed with proper C++ libraries that abide by the C++03/C++11 standard :/

pstdint.h and Windows

Gamma/pstdint.h conflicts with stdint.h which is now included with VS10+. Either pstdint.h should be updated or other environments (namely MinGW) should be tested against a standard #include <stdint.h> hence removing the need for pstdint.h.

Segfault is no PortAudio devices are available

Trying to use AudioIO if no PortAudio devices are available results in segfaults. It might be good to have more friendly errors.

Generalize Scheduler audio I/O data structure

The Scheduler is currently designed around gam::AudioIOData for accessing sample buffers, frame rate, block size, etc. While this simplifies its use, it also makes it difficult to use with other frameworks using different audio I/O objects.

Can it be generalized for use with other systems without adding too much complexity?

STFT inverse transform of mag/freq

The STFT inverse transform of the mag/freq format is not implemented.

@param to \param?

Lance, what do you think about replacing the ampersand with a backslash for the sake of consistency?

portaudio build error on macOS Monterey

Hi, getting this error when trying to build an example on macOS Monterey.

Is this related to an out-of-date portaudio library?

||PaMacCore (AUHAL)|| Error on line 944: err='-66748', msg=Unknown Error
||PaMacCore (AUHAL)|| OpenStream @ 44100 returned: -9986: Internal PortAudio error
AudioIO::Impl::supportsFPS: Internal PortAudio error
||PaMacCore (AUHAL)|| Error on line 944: err='-66748', msg=Unknown Error
||PaMacCore (AUHAL)|| OpenStream @ 44100 returned: -9986: Internal PortAudio error
AudioIO::Impl::supportsFPS: Internal PortAudio error
||PaMacCore (AUHAL)|| Error on line 944: err='-66748', msg=Unknown Error
Error in AudioIO::open(): Internal PortAudio error
Error in AudioIO::start(): Internal PortAudio error

Cheers

Rename Any to Switchable? (ipl::Switchable or interp::Switchable)

from the Google doc:

Any - “Dynamically switchable random-access interpolation strategy”
The name isn’t very descriptive. It could mean anything. Pardon the pun.
Suggested name:
LJP: Maybe ipl::Dynamic?
MW: To be clear, this is a meta-strategy that can switch among any of the other strategies at runtime. How about “Switchable”?

segExp.cpp example code is outdated

Hello,

Trying to compile the examples, make examples/ * / *.cpp, it stops at segExp.cpp example (from examples/envelop), first complaining about ../examples.h not found, after copying examples.h from examples/synths to examples, and running make again, it complains about RUN_AUDIO_MAIN.
As I couldn't figure out what is RUN_AUDIO_MAIN, I copied the "boilerplate" code from other example and updated it, see the attached file.

Please correct the segExp.cpp example, if you want, just replace it with the one attached (if it's correct...).
The attached file segExp.cpp.txt has the .txt extension because GitHub "doesn't support" .cpp.

Rename namespace ipl to interp?

from the Google doc conversation:

Allpass
Suggested name: AllpassInterpolationStrategy
LJP: I propose we leave it as is. First, I’m not a fan of long names in user code (I don’t have autocomplete). Second, this is in the ipl:: namespace so should really be referred to as ipl::AllPass.
MW: Leave ????::AllPass as AllPass; reconsider “ipl” abbreviation for “interpolation strategy”. Replace with “interp”?
DA: so change namespace ipl to interp?

Can generate doxygen?

For some map to the C++ classes?

File class redundant

The File class currently appears to have no dependents in Gamma (including SoundFile) nor offer anything beyond std::fstream. Removing it would help simplify the library.

Removing or deprecating Multi?

from Google doc:

Multi - name could be more descriptive.
Suggested name:
LJP: I’m not sure this one is worth bothering with. Probably should be deprecated or removed in favor of Vec.
DA: In that case, would you mind if I removed it now? Or would you prefer it be deprecated instead? Or neither?

Artifacts on Pitch Shifter example

When using percussive material, the example pitch shifter code produces artifacts when the pitch shift value is set to .5 (-1 octave).

error C3861: 'uint32_t': identifier not found

#42 The following bug occurs when including

https://github.com/AlloSphere-Research-Group/Gamma (simplegamma branch) with
https://github.com/mbrucher/AudioTK using VS2013 (platform toolkit v120).

So,

#include < ATK/Core/InPointerFilter.h >
#include < ATK/Core/OutPointerFilter.h >
#include < ATK/Dynamic/AttackReleaseFilter.h >
#include < ATK/Dynamic/PowerFilter.h >
#include < ATK/EQ/TimeVaryingSecondOrderFilter.h >

#include "Gamma/Gamma.h"
#include "Gamma/DFT.h"

and compiling produces the errors:

Error 28 error C3861: 'uint32_t': identifier not found c:\developer\libs_cpp\gamma-simplegamma\gamma\scl.h 744 1 MyPlug-vst2 Error 27 error C3861: 'int32_t': identifier not found c:\developer\libs_cpp\gamma-simplegamma\gamma\scl.h 602 1 MyPlug-vst2 Error 29 error C3861: 'int32_t': identifier not found c:\developer\libs_cpp\gamma-simplegamma\gamma\scl.h 1055 1 MyPlug-vst2 Error 30 error C3861: 'int32_t': identifier not found c:\developer\libs_cpp\gamma-simplegamma\gamma\scl.h 1176 1 MyPlug-vst2 Error 31 error C3861: 'int32_t': identifier not found c:\developer\libs_cpp\gamma-simplegamma\gamma\strategy.h 519 1 MyPlug-vst2 Error 34 error C3861: 'int32_t': identifier not found c:\developer\libs_cpp\gamma-simplegamma\gamma\tbl.h 659 1 MyPlug-vst2 Error 5 error C2371: 'uint32_t' : redefinition; different basic types c:\developer\libs_cpp\gamma-simplegamma\gamma\pstdint.h 392 1 MyPlug-vst2 Error 12 error C2371: 'uint_fast16_t' : redefinition; different basic types c:\developer\libs_cpp\gamma-simplegamma\gamma\pstdint.h 634 1 MyPlug-vst2 Error 7 error C2371: 'int32_t' : redefinition; different basic types c:\developer\libs_cpp\gamma-simplegamma\gamma\pstdint.h 422 1 MyPlug-vst2 Error 11 error C2371: 'int_fast16_t' : redefinition; different basic types c:\developer\libs_cpp\gamma-simplegamma\gamma\pstdint.h 633 1 MyPlug-vst2

CSine<> Amplitude drift

We're having issues with CSine<> changing amplitude very slowly over time, even with decay = -1. We're experiencing audible amplitude drift after 30+ minutes.

Class template error in gen.h whan compiling in Xcode....

Hi Lance,

Just updated my computer and have downloaded the latest stable brach of Gamma and trying to link it with my Xcode project. Everything seems fine apart from the error seen below. I have successfully ran the examples from terminal but these 2 errors are stopping me from developing with gamma in my own project. Any idea why Xcode would be complaining about this?

Cheers,
Josh

Android pthread_cancel()

Can't compile the library, because Android doesn't support pthread_cancel().
Is there a workaround for this?

STFT failure after ~30 minutes

The STFT class is failing after approximately 20-30 minutes of use. I'm wondering if this is a similar rounding error as the CSine issue that I reported. Here's an example to test (just drop this into a file in the Examples folder).

Essentially, this example processes the first 7,000,000 samples offline before the audio callback turns on. I'm using SamplePlayer for the first 7,000,000, as it runs more quickly than the Sine oscillator.

`

include "../AudioApp.h"

include "Gamma/Oscillator.h"

include "Gamma/DFT.h"

include "Gamma/SamplePlayer.h"

using namespace gam;

class MyApp : public AudioApp{
public:

STFT stft;
SamplePlayer<> play;
Sine<> osc;

enum
{
    PREV_MAG=0,
    TEMP_MAG,
    TEMP_FRQ
};

MyApp()
    // STFT(winSize, hopSize, padSize, winType, sampType, auxBufs)
:   stft(1024, 1024/4, 0, gam::HAMMING, gam::MAG_FREQ, 3)
{
    play.load("../../sounds/count.wav");
    osc.freq(220);
    gam::Domain::master().spu(44100);

    for (int i = 0; i < 70000000; ++i)
    {
        float s = play(); play.loop();
        //float s = osc();

        if(stft(s))
        {
            //nothing
        }
        s = stft();
    }
}

void onAudio(AudioIOData& io)
{
    while(io())
    {
        float s = osc() * 0.6;

        if(stft(s))
        {
            //nothing   
        }

        io.out(0) = s;
        io.out(1) = stft();
    }
}

};

int main(){
MyApp().start();
}
`

ReverbMS documentation and processing order mismatch

The description for ReverbMS states: "The network consists of a group of
/// parallel comb filters followed by a series of allpass comb filters.
/// The comb filters produce initial echoes and the allpass combs diffuse the
/// echoes by smearing transients and further increasing echo density."

However, in the implementation (ReverbMS::operator()), it looks like the allpass filters are applied before the comb filters.

Am I reading that correctly?

For the JOS implementation diagrams, Freeverb (https://ccrma.stanford.edu/~jos/pasp/Freeverb.html) and SATREV (https://ccrma.stanford.edu/~jos/pasp/Example_Schroeder_Reverberators.html) are shown with allpass filtering after the comb filters. Only the two JCVERB examples follow the Gamma method of allpass before combs.

It might be worth adding a boolean switch to decide which stage happens first. That way, more Schroeder types can be implemented.

Phase Increment Doxygen module?

proposed: the addition of a Doxygen module entitled "Phase Increment Strategies" or just simply "Phase Increment".

Would include all classes in namespace phsInc: Clip, Fold, Pat, Rep, Rap.

It would require the addition of
"/// \ingroup Phase Increment" or maybe just "/// \ingroup phsInc"
to each class.