.. _gettingStartedProcessorsOneDoc:

.. index:: single: Example; Processors

=====================================================
Built-In Processors, Constants, and Switches (Part I)
=====================================================

Let's improve on our :ref:`previous example <exampleStream>` and add level control to the output signal.

::

	signal Microphone {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Microphone input'
	}
	
	signal MainOutput [2] {
		default:	0.0
		rate:		AudioRate
		reset:		MasterReset
		meta:		'Main stereo output'
	}
	
	AudioIn[1] >> Microphone;
	
	MainOutput >> AudioOut[1:2];
	
	# Amplify the microphone signal 3.98 times (12 dB) using the Level() processor
	Microphone
	>> Level (
		gainType:	'Linear'
		gain:		3.98
		offset:		0.0
		bypass: 	off
	) 
	>> MainOutput;

:ref:`Level() <Level_SCP>` is a :ref:`built-in processor block <builtinProcessorsDoc>`. As its name indicates, ``Level()`` amplifies or attenuates an audio stream when active. Just like Stride blocks, Stride processors have ports and properties. 

The ``Level()`` processor has six ports and four properties.

+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+
|      |                |           |                     |            |            |                 |               |
+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+
| Port | Name           | Direction | Type                | Connection | Access     | Default         | Required      | 
+======+================+===========+=====================+============+============+=================+===============+
| 1    | input          | input     | SRP                 | single     | >> LABEL   | ``none``        | no :sup:`(1)` |
+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 2    | output         | output    | SRP                 | multiple   | LABEL >>   | ``none``        | no :sup:`(1)` |
+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 3    | ``gainType``   | input     | CSP                 | single     | property   | ``Linear``      | yes           |
+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 4    | ``gain``       | input     | CIP, CRP, SIP, SRP  | single     | property   | ``1.0``         | yes           |
+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 5    | ``offset``     | input     | CIP, CRP, SIP, SRP  | single     | property   | ``0.0``         | yes           |
+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+
| 6    | ``bypass``     | input     | CBP, SBP            | single     | property   | ``off``         | yes           |
+------+----------------+-----------+---------------------+------------+------------+-----------------+---------------+

|

:CBP:	constant boolean port

:CIP:	constant integer port

:CRP:	constant real port

:CSP:	constant string port

:CBP:	constant boolean port

:SIP:	stream integer port

:SRP:	stream real port
	
:LABEL:	block label	

:sup:`1` Warning issued during compilation if the port is left unconnected.

The input and output ports of ``Level()`` are not exposed using properties. Connection with the processor block are possible with the stream operator.

The ``gainType`` property, sets the amplification or attenuation level in dB (Decibel). ``gain`` exposes an input port that can accept connections from output ports of type `control real` or `constant real`. In this example, the property has been assigned a :ref:`real <Real>`. Real is one of the :ref:`basic types <basicTypesDoc>`. All basic types are :ref:`constant blocks <constantDoc>`. in case of real, its output type is `constant real`. 

The ``bypass`` property, as its name indicates, allows bypassing the processor block and establishing a direct connection between its `audio stream` input and output ports. ``bypass`` exposes an input port that can accept connections from output ports of type `boolean`. In this example, it is assigned the keyword :ref:`off`. ``off`` represents one of the two boolean values in Stride, the other one being ``on``. They both connect to `boolean` input ports.

.. _exampleProcessorFixed:

::

	constant LevelGainValue {
		value:	3.98
		meta:	'The gain value of Level()'
	}
	
	switch LevelBypassSwitch {
		default:	off
		reset:		MasterReset
		meta:		"Switch to control the bypass port of Level()"
	}
	
	AudioIn[1] >> Microphone;
	
	MainOutput >> AudioOut[1:2];
	
	# Amplify the microphone signal 3.98 times (12 dB) using the Level() processor
	Microphone
	>> Level (
		gainType:	'Linear'
		gain:		LevelGainValue
		offset:		0.0
		bypass: 	LevelBypassSwitch
	) 
	>> MainOutput;