# wavetableSynthesizer

Generate periodic signal from single-cycle waveforms

## Description

The `wavetableSynthesizer` System object™ generates a periodic signal with tunable properties. The periodic signal is defined by a single-cycle waveform cached as the `Wavetable` property of your `wavetableSynthesizer` object.

To generate a periodic signal:

1. Create the `wavetableSynthesizer` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``waveSynth = wavetableSynthesizer``
``waveSynth = wavetableSynthesizer(wavetableValue)``
``waveSynth = wavetableSynthesizer(wavetableValue,frequencyValue)``
``waveSynth = wavetableSynthesizer(___,Name,Value)``

### Description

````waveSynth = wavetableSynthesizer` creates a wavetable synthesizer System object, `waveSynth`, with default property values.```
````waveSynth = wavetableSynthesizer(wavetableValue)` sets the Wavetable property to `wavetableValue`.```
````waveSynth = wavetableSynthesizer(wavetableValue,frequencyValue)` sets the Frequency property to `frequencyValue`.```
````waveSynth = wavetableSynthesizer(___,Name,Value)` sets each property `Name` to the specified `Value`. Unspecified properties have default values.Example: ```waveSynth = wavetableSynthesizer('Amplitude',2,'DCOffset',2.5)``` creates a System object, `waveSynth`, that generates the default sine waveform with an amplitude of 2 and a DC offset of 2.5.```

## Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the `release` function unlocks them.

If a property is tunable, you can change its value at any time.

Single-cycle waveform, specified as a vector of real values. The algorithm of the `wavetableSynthesizer` indexes into the single-cycle waveform to synthesize a periodic wave.

Tunable: Yes

Data Types: `single` | `double`

Frequency of generated signal in Hz, specified as a real scalar greater than or equal to 0.

Tunable: Yes

Data Types: `single` | `double`

Amplitude of generated signal, specified as a real scalar greater than or equal to 0.

The generated signal is multiplied by the value specified by `Amplitude` at the output, before DCOffset is applied.

Tunable: Yes

Data Types: `single` | `double`

Normalized phase offset of generated signal, specified as a real scalar with values in the range [0, 1]. The range is a normalized 2π radians interval.

Tunable: No

Data Types: `single` | `double`

Value added to each element of the generated signal, specified as a real scalar.

Tunable: Yes

Data Types: `single` | `double`

Number of samples per frame, specified as a positive integer in the range [1, 192000].

This property determines the vector length that your `wavetableSynthesizer` object outputs.

Tunable: Yes

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Sample rate of generated signal in Hz, specified as a real positive scalar.

Tunable: Yes

Data type of generated signal, specified as `'double'` or `'single'`.

Tunable: No

Data Types: `char` | `string`

## Usage

### Syntax

``waveform = waveSynth()``

### Description

example

````waveform = waveSynth()` generates a periodic signal, `waveform`. The type of signal is specified by the algorithm and properties of the `wavetableSynthesizer` System object, `waveSynth`.```

### Output Arguments

expand all

Waveform output from the wavetable synthesizer, returned as a column vector with length specified by the SamplesPerFrame property and data type specified by the OutputDataType property.

Data Types: `single` | `double`

## Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `createAudioPluginClass` Create audio plugin class that implements functionality of System object `parameterTuner` Tune object parameters while streaming
 `configureMIDI` Configure MIDI connections between audio object and MIDI controller `disconnectMIDI` Disconnect MIDI controls from audio object `getMIDIConnections` Get MIDI connections of audio object
 `clone` Create duplicate System object `isLocked` Determine if System object is in use `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object `step` Run System object algorithm

The `createAudioPluginClass` and `configureMIDI` functions map tunable properties of the `wavetableSynthesizer` System object to user-facing parameters:

PropertyRangeMappingUnit
`Frequency`[0.1, 20000]logHz
`Amplitude`[0, 10]linearnone
`DCOffset`[–10, 10]linearnone

## Examples

collapse all

Define and plot a single-cycle waveform.

```values = -1:0.1:1; singleCycleWave = ones(100,1) * values; singleCycleWave = reshape(singleCycleWave,numel(singleCycleWave),1); plot(singleCycleWave) xlabel('Index') ylabel('Amplitude')```

Create a wavetable synthesizer, `waveSynth`, to generate a staircase wave using the single-cycle waveform. Specify a frequency of 10 Hz.

`waveSynth = wavetableSynthesizer(singleCycleWave,10);`

Create a time scope to visualize the staircase wave generated by `waveSynth`.

```scope = timescope( ... 'SampleRate',waveSynth.SampleRate, ... 'TimeSpanSource','Property','TimeSpan',0.1, ... 'YLimits',[-1.5,1.5], ... 'TimeSpanOverrunAction','Scroll', ... 'ShowGrid',true, ... 'Title','Variable-Frequency Staircase Wave');```

Place the wavetable synthesizer in an audio stream loop. Increase the frequency of your staircase wave in 10 Hz increments.

```counter = 0; while (counter < 1e4) counter = counter + 1; staircaseWave = waveSynth(); scope(staircaseWave) if mod(counter,1000)==0 waveSynth.Frequency = waveSynth.Frequency + 10; end end```

Sample an audio file and save it to the `Wavetable` property of a `wavetableSynthesizer` System object™. Use the wavetable synthesizer to manipulate your audio sample.

Read in an entire audio file. Clip out an interesting sound from the audio and then play it.

```[audio,fs] = audioread('MainStreetOne-16-16-mono-12secs.wav'); aSound = audio(2.5e4:5e4); sound(aSound,fs)```

Create a wavetable synthesizer using your audio clip. The duration of the `engine` audio clip is `numel(aSound)/fs` seconds. In the `wavetableSynthesizer`, set the `Frequency` property to 1/(clip duration). The generated signal now plays back at the same rate it was recorded at.

```duration = numel(aSound)/fs; waveSynth = wavetableSynthesizer('Wavetable',aSound,'SampleRate',fs, ... 'Frequency',1/duration);```

Create an `audioDeviceWriter` to write to your audio device.

`deviceWriter = audioDeviceWriter('SampleRate',fs);`

In a loop, play the wavetable synthesizer to your device. After three seconds, begin increasing the frequency of the wavetable synthesizer. After six seconds, begin decreasing the frequency of the wavetable synthesizer.

```timeElapsed = 0; while timeElapsed < 9 audioWave = waveSynth(); deviceWriter(audioWave); if (timeElapsed > 3) && (timeElapsed < 6) waveSynth.Frequency = waveSynth.Frequency + 0.001; elseif timeElapsed > 6 waveSynth.Frequency = waveSynth.Frequency - 0.002; end timeElapsed = timeElapsed + waveSynth.SamplesPerFrame*(1/fs); end```

Modify the `Wavetable` property of a `wavetableSynthesizer` object while stream processing. Visualize the wavetable and play the resulting audio.

Create a single-cycle waveform for the `wavetableSynthesizer` to index into. Create a wavetable synthesizer object.

```t = 0:0.001:1; exponent = 5; waveTable = [t.^exponent,fliplr(t.^exponent)] - 0.5; waveSynth = wavetableSynthesizer('Wavetable',waveTable);```

Create a `dsp.ArrayPlot` object to plot the wavetable as it is modified over time. Create an `audioDeviceWriter` object to listen to the signal output by your wavetable synthesizer.

```arrayPlotter = dsp.ArrayPlot('YLimits',[-1,1],'PlotType','Line'); deviceWriter = audioDeviceWriter;```

In an audio stream loop, incrementally modify the `Wavetable` property of the wavetable synthesizer and plot it. Call the synthesizer to output a waveform and play the waveform to your audio device.

```tic while toc < 10 exponent = exponent - 0.01; waveSynth.Wavetable = [t.^abs(exponent),fliplr(t.^abs(exponent))] - 0.5; arrayPlotter(waveSynth.Wavetable') deviceWriter(waveSynth()); end```

`release(deviceWriter)`

Create a `wavetableSynthesizer` to generate a waveform. Create a `timescope` to visualize the waveform. Create an `audioDeviceWriter` to write audio to your sound card.

```fs = 44.1e3; wvSynth = wavetableSynthesizer('SampleRate',fs); scope = timescope( ... 'SampleRate',wvSynth.SampleRate, ... 'TimeSpanSource','Property','TimeSpan',1, ... 'YLimits',[-2,2], ... 'TimeSpanOverrunAction','Scroll', ... 'ShowGrid',true); deviceWriter = audioDeviceWriter('SampleRate',wvSynth.SampleRate);```

Call `parameterTuner` to open a UI to tune parameters of the wavetable synthesizer while streaming.

`parameterTuner(wvSynth)`

In an audio stream loop:

1. Call the wavetable synthesizer without arguments to output one frame of data.

2. Visualize the data using the time scope.

3. Write the frame of audio to your audio device for listening.

While streaming, tune parameters of the wavetable synthesizer and listen to the effect.

```duration = 15; numIterations = round(wvSynth.SampleRate*duration/wvSynth.SamplesPerFrame); for i = 1:numIterations audioOut = wvSynth(); scope(audioOut) deviceWriter(audioOut); drawnow limitrate % required to update parameter end```

As a best practice, release your objects when done.

```release(deviceWriter) release(wvSynth) release(scope)```

## Algorithms

expand all

The `wavetableSynthesizer` System object synthesizes periodic signals using a cached single-cycle waveform, specified waveform properties, and phase memory.