.. _gettingStartedOscillatorDoc:

.. index:: single: Example; Oscillators and Generator Modules

=================================
Oscillators and Generator Modules
=================================

The following is an example of a simple sine wave Oscillator running at the hardware audio rate. An Oscillator is a :ref:`built-in generator <builtinGeneratorsDoc>`. A generator runs at the rate of the block connected to its output.  

::

	# Declare an Oscillator
	# Connect its output to audio output 1 using a stream operator
	Oscillator (
		type: 		'Sine'
		amplitude: 	1.0
		frequency: 	440.0
		phase: 		0.0
		reset:		off
	) 
	>> AudioOut[1:2];


The following is an example of two simple sine wave Oscillator running at audio rate with relative frequencies (unison and fifth).

::
	
	constant Frequency {
		value:	220.0
		meta:	none
	}

	Oscillator (
		type: 		'Sine'
		amplitude: 	0.5
		frequency: 	Frequency
		phase: 		0.0
		reset:		off
	)
	+ Oscillator (
		type: 		'Sine'
		amplitude: 	0.4
		frequency: 	Frequency * 1.5
		phase: 		0.0
		reset:		off
	)
	>> AudioOut[1:2];

The same program can be written as follows:
(Notice the addition of the Mix() processor to sum the Oscillator outputs)

::
	
	constant Frequency {
		value:	220.0
		meta:	none
	}

	Oscillator (
		type: 		[ 'Sine', 'Sine' ]
		amplitude: 	[ 0.5, 0.4 ]
		frequency: 	[ Frequency , Frequency * 1.5]
		phase: 		[ 0.0, 0.0 ]
		reset:		[ off, off]
	)
	>> Mix ()
	>> AudioOut[1:2];

If the Mix() processor is left out of the stream expression, the unison (Frequency) Oscillator will go to output 1 and the fifth (Frequency * 1.5) will go to output 2. 
	
There is no need for a list if all list values are identical. It is also possible to perform multiplication on a list. 
	
::
	
	constant Frequency {
		value:	220.0
		meta:	none
	}

	Oscillator (
		type: 		'Sine'
		amplitude: 	[ 0.5, 0.4 ]
		frequency: 	[ 1.0 , 1.5] * Frequency
		phase: 		0.0
		reset:		off
	)
	>> Mix ()
	>> AudioOut[1:2];
	
In the following example the Oscillators are connected to signal blocks.
	
::
	
	constant Frequency {
		value:	220.0
		meta:	none
	}
	
	signal SineWaveUnison {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Sine wave Oscillator with base frequency.'
	}
	
	signal SineWaveFifth {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Sine wave Oscillator with relative frequency.'
	}
	
	Oscillator (
		type: 		'Sine'
		amplitude: 	1.0
		frequency: 	Frequency
		phase: 		0.0
		reset:		off
	)	
	>> SineWaveUnison;
	
	Oscillator (
		type: 		'Sine'
		amplitude: 	1.0
		frequency: 	Frequency * 1.5
		phase: 		0.0
		reset:		off
	)
	>> SineWaveFifth;
	
	[ SineWaveUnison, SineWaveFifth ]
	>> Level(
		gainType:	'Linear'
		gain: 		[ 0.5, 0.4 ]
		offset:		0.0
		bypass:		off
	)
	>> Mix ()
	AudioOut[1:2];

The following example builds on the preceding example. A 2 Hz triangle wave running at 1024 Hz is connected to the ``position`` property of a Panning processor ``Pan()``.
	
::

	constant Range {
		value: 	0.75
		meta:	'Panning limits.'
	}

	signal PanPosition {
		default:	0.0
		rate:		1024
		reset:		MasterReset
		meta:		'Pan position control'
	}
	
	Oscillator (
		type: 		'Triangle'
		amplitude: 	1.0
		frequency: 	2.0
		phase: 		0.0
		reset:		off
	)
	>> Map (
		mode:		'Linear'
		minimum:	-Range
		maximum:	Range
		bypass:		off
	)
	>> Round (
		mode:		'Truncate'
		increment:	0.01
		bypass:		off
	)
	>> PanPosition;
	
	[ SineWaveUnison, SineWaveFifth ]
	>> Level(
		gainType:	'Linear'
		gain: 		[ 0.5, 0.4 ]
		offset:		0.0
		bypass:		off
	)
	>> Mix ()
	>> Pan (
		position:	PanPosition
		bypass:		off	
	)
	>> AudioOut[1:2];	
	
Three sine wave Oscillators at audio rate.

::
	
	signal ThreeSineWaves {
		default: 	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Three sine wave Oscillators.'
	}
	
	Oscillator (
		type: 		'Sine'
		amplitude: 	[ 1.0, 0.66, 0.33 ]
		frequency: 	[ 220.0, 440.0, 880.0 ]
		phase: 		0.0
		reset:		off
	)
	>> Mix (
		gainType:	'Linear'
		gain: 		0.5
		offset:		0.0
		bypass:		off	
	)
	>> ThreeSineWaves;

Three sine wave Oscillator at audio rate with variable frequency controlled over OSC.

::
	
	constant OscInAddresses { value: 'Fundamental' }

	# Declare a control block
	# The rate is set to none since OSC messages are asynchronous
	signal Fundamental {
		default:	110.0
		rate:		none
		reset:		MasterReset
		meta:		'Fundamental frequency change over OSC.'  
	}
	
	# Connect the 'OSC' block to the 'Fundamental' control block
	OscIn ( 
		addressList:	OscInAddresses
		address: 	'/Fundamental' 
	) 
	>> Clip (
		minimum:	22.5
		maximum:	7040.0
		bypass:		off
	)
	>> Round (
		mode:		'Floor'
		increment:	0.01
		bypass:		off
	)
	>> Fundamental;

	Oscillator (
		type: 		'Sine'
		amplitude: 	[ 1.0, 0.66, 0.33 ]
		frequency: 	[ 1.0 , 2.0, 3.0 ] * Fundamental
		phase: 		0.0
		reset:		off
	)
	>> Mix (
		gainType:	'Linear'
		gain: 		0.45
		offset:		0.0
		bypass:		off	
	)
	>> AudioOut[1];
	
Creating a generator block and reusing it.
	
::

	constant Fundamental {
		value: 55.0
		meta: 'Fundamental frequency.'
	}

	module ThreeHarmonicPartials {
		input:			none
		output:			Output
		propertyName:		[ 'fundamental', 'outputLevel', 'reset' ]
		propertyDirection:	in
		propertyBlock:		[ 
			constant FundamentalFrequency { value: 440.0 meta: 'Default frequency.' },
			constant GainValue { value: 0.5 meta: 'Default level.' },
			trigger Reset {}
		]
		internalBlock:		[
			signal Output {
				default:	0.0
				rate:		streamRate
				reset:		Reset
				meta:		none
			}
		]
		streams:		[
			Oscillator (
				type: 		'Sine'
				amplitude: 	[ 1.0, 0.66, 0.33 ]
				frequency: 	[ 1.0 , 2.0, 3.0 ] * FundamentalFrequency  
				phase: 		0.0
				reset:		Reset
			) 
			>> Mix (
				gainType:	'Linear'
				gain: 		GainValue
				offset:		0.0
				bypass:		off	
			)
			>> Output;
		]
		meta:			'Three harmonic partials with fundamental frequency and level control.'	
	}
	
	signal HarmonicPartialsPlusFifths {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Sum of three harmonic partials and their fifths'
	}
	
	ThreeHarmonicPartials (
		fundamental:	[ 1.0, 1.5 ] * Fundamental
		outputLevel:	[ 0.45, 0.35 ]
		reset:		off
	)
	>> Mix ()
	>> HarmonicPartialsPlusFifths;

Another user defined generator and use case 
	
::

	module AlarmPatch {
		input:			none
		output:			Output
		propertyName:		[ 'carFreq', 'modFreq', 'modPhase', 'reset' ]
		propertyDirection:	in
		propertyBlock:		[ 	
			constant CFreq { value:	440.0 meta: none }, 
			constant MFreq { value: 2.0 meta: none }, 
			constant MPhase { value: 0.0 meta: none },
			trigger Reset {}
		]
		internalBlock:		[
			signal Output {
				default:	0.0
				rate:		streamRate
				reset:		Reset 
				meta:		none
			} 	
			signal Amplitude {
				default:	0.0
				rate:		streamRate / 20
				reset:		Reset
				meta:		none
				}
		]	
		streams:		[	
			Oscillator (
				type: 		'Square'
				amplitude:	1.0
				frequency:	MFreq
				phase:		MPhase
				reset:		Reset
			)
			>> LowPass( 					
				cutOff: 50
				reset:	Reset
				bypass:	off
			)
			>> Map (
				mode:		'Linear'
				minimum:	0.0
				maximum:	1.0
				bypass:		off
			)
			>> Amplitude;
			,
			Oscillator (
				type: 		'Sine'
				amplitude:	Amplitude
				frequency:	CFreq
				phase:		0.0
				reset:		Reset				
			)
			>> Output;
		]
		meta:			none
	}

	
	AlarmPatch ( 
		carFreq:	[600.0, 800.0]		
		modFreq:	2.0
		modPhase:	[0.0, 180.0]
		reset:		off
	)
	>> Mix ()
	>> AudioOut[1:2];
	
Exciting a BiQuad filter with an impulse train:
	
::

	constant UpdateRate {
		value:	10.0
		meta:	none
	}
	
	signal CutOffFreqValue {
		default:	0.0
		rate: 		UpdateRate
		reset:		MasterReset
		meta:		'BiQuad CutOff Frequency Control.'
	}

	Oscillator (
		type:		'Sine'
		amplitude:	1.0
		frequency:	1.0 / 2.0 * M_PI * UpdateRate
		phase:		0.0
		reset:		off
	)
	>> Rectify (
		mode: 		'Full'
		bypass:		off
	)
	>> Map (
		mode:		'Linear'
		minimum:	0.0
		maximum:	4000.0
		bypass:		off
	)
	>> CutOffFreqValue;

	ImpulseTrain (
		amplitude:	1.0
		frequency: 	UpdateRate
		count:		none
		start:		none
		stop:		none
		reset:		off
	) 
	>> BiQuad (
		type:			'LowPass'
		centerFrequency:	CutOffFreqValue	
		resonance:		2.0
		reset:			off
		bypass:			off
	)
	>> Level(
		gainType:	'Linear'
		gain: 		0.5
		offset:		0.0
		bypass:		off
	)
	>> AudioOut[1:2];