## Additive Synthesis Actor

The Additive Synthesis Actor performs harmonic-spectrum additive synthesis. At most 30 harmonics ("partials") are computed.

To use the Additive Synthesis Actor, load add.so and create an actor of type AddActor.

### AddActor messages

In addition to the messages understood by all generator actors, the AddActor understands the following messages:

SetFreq `hActor x`
  Set the default fundamental frequency for new instances created by this actor to `x` Hz.
SetAllFreq `hActor x time`
  Set the fundamental frequency of all children to `x` Hz, and also set the default fundamental frequency for all future children to `x` Hz. If `time` is specified, children will modulate to the new frequency over the specified duration. Default frequency is always set immediately regardless of `time`.
SetAmplPartials `hActor array`
  Set the default amplitudes of the first few partials (however many are specified) for new instances created by this actor to `array`.
SetIthAmpl `hActor i x`
  Set the default amplitude of the i'th partial (starting from 0 as the base partial) for new instances created by this actor to `x`.
SetAllIthAmpl `hActor i x time`
  Set the amplitude of the i'th partial of all children to `x`, and set the default amplitude of the i'th partial for all future children. If `time` is specified, children will modulate to the new amplitude over the specified duration. Default amplitude is always set immediately regardless of `time`.
SetFDPartials `hActor array`
  Set the default frequency deviations of the first few partials (however many are specified) for new instances created by this actor to `array`.
  As the FD value for the i'th partial ranges from -1 to 1, the i'th partial will have a frequency ranging from that of the (i-1)'th to that of the (i+1)'th.
  In other words: Frequency deviation is expressed in deviated portion of fundamental frequency with range of [-1, +1]. New partial frequency = original harmonic frequency + FD*fundamental frequency. So FD=-1 brings the partial down to the partial below it, FD=1 up.
SetIthFD `hActor x`
  Set the default frequency deviation of the i'th partial for new instances created by this actor to `x`.
SetAllIthFD `hActor i x time`
  Set the frequency deviation of the i'th partial of all children to `x`, and set the default amplitude of the i'th partial for all future children. If `time` is specified, children will modulate to the new value over the specified duration. Default value is always set immediately regardless of `time`.

### AddActor handler messages

In addition to the messages understood by all handlers, the handler for the additive synthesis algorithm understands the following messages:

SetFreq `hSound x time`
  Set the fundamental frequency to `x` Hz. If `time` is specified, move to the new frequency over the specified duration.
SetAmplPartials `hSound array time`
  Set the amplitudes of the first few partials (however many are specified) to `array`. If `time` is specified, move to the new amplitudes over the specified duration.
SetIthAmpl `hSound i x time`
  Set the `i`'th partial's amplitude to `x`. If `time` is specified, move to the new amplitude over the specified duration. (Note: as of this writing, overlapping SetIthAmpl messages for different partials with different `time`s may cause unexpected results.)
SetFDPartials `hSound array`
  Set the frequency deviations of the first few partials (however many are specified) to `array`.
SetIthFD `hSound x`
  Set the frequency deviation of the i'th partial to `x`.
  As x ranges from -1 to 1, the i'th partial will have a frequency ranging from that of the (i-1)'th to that of the (i+1)'th.
SetFreqPartials `hSound array`
  Set the absolute frequency (in Hz) of the first few partials (however many are specified) to `array`. Valid range is [0, 24000].
SetIthFreq `hSound x`
  Set the absolute frequency of the i'th partial to `x`.

### Examples

`LoadDSO add.so;
a = Create AddActor;
`

Play a fairly quiet pure sine wave at 200 Hz for 5 seconds:

  `s = BeginSound a SetFreq 200 SetAmp .1;
  sleep 5;`

The same, but with another louder sine wave at 1000 Hz:

  `SetIthAmpl a 0 .1;
  SetIthAmpl a 4 .3;
  s = BeginSound a SetFreq 200 SetAmp 1;
  sleep 5;`

Another way to get the same result:

  `s = BeginSoundPaused a SetFreq 200 SetAmp 1;
  SetIthAmpl s 0 .1;
  SetIthAmpl s 4 .3;
  SetPause s 0;
  sleep 5;`

Yet another way to get the same result:

  `s = BeginSoundPaused a SetFreq 200 SetAmp 1;
  SetAmplPartials s [.1 0 0 0 .3];
  SetPause s 0;
  sleep 5;`

This time, fade out the 200 Hz sine wave and fade in a 400 Hz one:

  `s = BeginSoundPaused a SetFreq 200 SetAmp 1;
  SetAmplPartials s [.1 0 0 0 .3];
  SetPause s 0;
  SetAmplPartials s [0 .1 0 0 .3] 5;
  sleep 5;`

How to play an arbitrary collection of frequencies:

  `s = BeginSoundPaused a SetFreq 200 SetAmp 1;
  SetAmplPartials s [.3 .1 .4 .1 .5 .9 ];
  SetFreqPartials s [200 700 100 800 200 800];
  SetPause s 0;
  sleep 5;`