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.

To learn more about how System objects work, see What Are System Objects?

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

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.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Wavetable — Single-cycle waveform

sin(2*pi*(0:511)/512) (default) | vector of real values

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 — Frequency of generated signal (Hz)

100 (default) | real scalar

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

Tunable: Yes

Data Types: single | double

Amplitude — Amplitude of generated signal

1 (default) | real scalar

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

PhaseOffset — Normalized phase offset of generated signal

0 (default) | real scalar

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

DCOffset — Value added to each element of generated signal

0 (default) | real scalar

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

Tunable: Yes

Data Types: single | double

SamplesPerFrame — Number of samples per frame

512 (default) | positive integer

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

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

MaxSamplesPerFrame — Maximum number of samples per frame

192000 (default) | positive integer

Maximum number of samples per frame, specified as a positive integer. Setting this property to a lower value can save memory when using code generation.

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

SampleRate — Sample rate of generated signal (Hz)

44100 (default) | real positive scalar

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

Tunable: Yes

OutputDataType — Data type of generated signal

'double' (default) | 'single'

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

Tunable: No

Data Types: char | string

Usage

Syntax

waveform = waveSynth()

Description

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

waveform — Waveform output from wavetable synthesizer

column vector (default)

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)

Specific to wavetableSynthesizer

createAudioPluginClass	Create audio plugin class that implements functionality of System object
parameterTuner	Tune object parameters while streaming

MIDI

configureMIDI	Configure MIDI connections between audio object and MIDI controller
disconnectMIDI	Disconnect MIDI controls from audio object
getMIDIConnections	Get MIDI connections of audio object

Common to All System Objects

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:

Property	Range	Mapping	Unit
Frequency	[0.1, 20000]	log	Hz
Amplitude	[0, 10]	linear	none
DCOffset	[–10, 10]	linear	none

Examples

Generate Variable-Frequency Staircase Wave

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

Manipulate Audio Samples Using Wavetable Synthesizer

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 Wavetable While Stream Processing

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)

Tune Wavetable Synthesizer Parameters

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

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

Compute Increment

Compute the increment step size:

$$\Delta =\frac{\text{Frequency}}{\text{SampleRate}}\times N,$$

where N is the number of elements in your wavetable.

Compute Wavetable Index

Compute Wavetable index,

$$i[n]=\{\begin{array}{c}i[n-1]+\Delta \\ i[n-1]+\Delta -N\end{array}\begin{array}{c}i[n-1]<N\\ i[n-1]\ge N\end{array},$$

for $$2\le n\le \text{SamplesPerFrame}$$. The PhaseOffset property determines i[n=1].

Linear Interpolation

Index into the Wavetable and perform linear interpolation:

$$w=\{\begin{array}{c}\left(\text{Wavetable}[1]-\text{Wavetable}[i_{\text{L}}]\right)\times \epsilon +\text{Wavetable}[i_{\text{L}}]\\ \left(\text{Wavetable}[i_{\text{H}}]-\text{Wavetable}[i_{\text{L}}]\right)\times \epsilon +\text{Wavetable}[i_{\text{L}}]\end{array}\begin{array}{c}\\ \end{array}\begin{array}{c}{i}_{\text{H}}>N\\ i_{\text{H}}\le N\end{array}.$$

• $$i_{\text{L}}=\mathrm{floor}(i[n]+1)$$

• $$i_{\text{H}}=i_{\text{L}}+1$$

• $$\epsilon =i-\mathrm{floor}(i)$$

Apply Amplitude and DC Offset

Multiply by Amplitude and add DCOffset.

$$waveform=w\times \text{Amplitude}+\text{DCOffset}$$

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

System Objects in MATLAB Code Generation (MATLAB Coder)

Version History

Introduced in R2016a

R2022b: New MaxSamplesPerFrame property

Use the MaxSamplesPerFrame property to specify the maximum number of samples per frame. Setting the property to a lower value can save memory when using code generation.