Main Content

audioOscillator

Generate sine, square, and sawtooth waveforms

expand all in page

Description

The audioOscillator System object™ generates tunable waveforms. Typical uses include the generation of test signals for test benches, and the generation of control signals for audio effects. Properties of the audioOscillator System object specify the type of waveform generated.

To generate tunable waveforms:

  1. Create the audioOscillator 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

osc = audioOscillator
osc = audioOscillator(signalTypeValue)
osc = audioOscillator(signalTypeValue,frequencyValue)
osc = audioOscillator(___,Name,Value)

Description

osc = audioOscillator creates an audio oscillator System object, osc, with default property values.

osc = audioOscillator(signalTypeValue) sets the SignalType property to signalTypeValue.

osc = audioOscillator(signalTypeValue,frequencyValue) sets the Frequency property to frequencyValue.

osc = audioOscillator(___,Name,Value) sets each property Name to the specified Value. Unspecified properties have default values.

Example: osc = audioOscillator('SignalType','sine','Frequency',8000,'DCOffset',1) creates a System object, osc, which generates 8 kHz sinusoids with a DC offset of one.

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.

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

Type of waveform generated by your audioOscillator object, specified as 'sine', 'square', or 'sawtooth'.

The waveforms are generated using the algorithms specified by the sin, square, and sawtooth functions.

Tunable: No

Data Types: char | string

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

  • For sine waveforms, specify Frequency as a scalar or as a vector of length NumTones.

  • For square waveforms, specify Frequency as a scalar.

  • For sawtooth waveforms, specify Frequency as a scalar.

Tunable: Yes

Data Types: single | double

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

  • For sine waveforms, specify Amplitude as a vector of length NumTones.

  • For square waveforms, specify Amplitude as a scalar.

  • For sawtooth waveforms, specify Amplitude as a scalar.

The generated waveform 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 waveform, specified as a real scalar or vector of real scalars with values in the range [0, 1]. The range is a normalized 2π-radian interval.

  • For sine waveforms, specify PhaseOffset as a vector of length NumTones.

  • For square waveforms, specify PhaseOffset as a scalar.

  • For sawtooth waveforms, specify PhaseOffset as a scalar.

Tunable: No

Data Types: single | double

Value added to each element of generated waveform, specified as a real scalar or vector of real scalars.

  • For sine waveforms, specify DCOffset as a vector of length NumTones.

  • For square waveforms, specify DCOffset as a scalar.

  • For sawtooth waveforms, specify DCOffset as a scalar.

Tunable: Yes

Data Types: single | double

Number of pure sine waveform tones summed and then generated by the audio oscillator.

Individual tones are generated based on values specified by Frequency, Amplitude, PhaseOffset, and DCOffset.

Tunable: No

Dependencies

To enable this property, set SignalType to 'sine'.

Data Types: single | double

Square waveform duty cycle, specified as a scalar in the range [0, 1].

Square waveform duty cycle is the percentage of one period in which the waveform is above the median amplitude. A DutyCycle of 1 or 0 is equivalent to a DC offset.

Tunable: Yes

Dependencies

To enable this property, set SignalType to 'square'.

Data Types: single | double

Sawtooth width, specified as a scalar in the range [0, 1].

Sawtooth width determines the point in a sawtooth waveform period at which the maximum occurs.

Tunable: Yes

Dependencies

To enable this property, set SignalType to 'sawtooth'.

Data Types: single | double

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

This property determines the vector length that your audioOscillator object outputs.

Tunable: Yes

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

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

Sample rate of generated waveform in Hz, specified as a positive scalar greater than twice the value specified by Frequency.

Tunable: Yes

Data Types: single | double

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

Tunable: Yes

Data Types: char | string

Usage

Syntax

waveform = osc()

Description

waveform = osc() generates a waveform output, waveform. The type of waveform is specified by the algorithm and properties of the System object, osc.

example

Output Arguments

expand all

Waveform output from the audio oscillator, returned as a column vector with length specified by the SamplesPerFrame 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

createAudioPluginClassCreate audio plugin class that implements functionality of System object
parameterTunerTune object parameters while streaming
configureMIDIConfigure MIDI connections between audio object and MIDI controller
disconnectMIDIDisconnect MIDI controls from audio object
getMIDIConnectionsGet MIDI connections of audio object
cloneCreate duplicate System object
isLockedDetermine if System object is in use
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
stepRun System object algorithm

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

PropertyRangeMappingUnits
Frequency[0.1, 20000]logHz
Amplitude[0, 10]linearno units
DCOffset[–10, 10]linearno units
DutyCycle (available when you set SignalType to 'square')[0, 1]linearno units
Width (available when you set SignalType to 'sawtooth')[0, 1]linearno units

Examples

collapse all

Open Script

Use the audioOscillator to generate a variable-frequency sine wave.

Create an audio oscillator to generate a sine wave. Use the default settings.

osc = audioOscillator;

Create a time scope to visualize the variable-frequency sine wave generated by the audio oscillator.

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

Place the audio oscillator in an audio stream loop. Increase the frequency of your sine wave in 50-Hz increments.

counter = 0;
while (counter < 1e4)
    counter = counter + 1;
    sineWave = osc();
    scope(sineWave);
    if mod(counter,1000)==0
        osc.Frequency = osc.Frequency + 50;
    end
end

Open Live Script

Tune the frequency of an audio oscillator at regularly spaced intervals to create a melody. Play the melody to your audio output device.

Create a structure to hold the frequency values of notes in a melody.

notes = struct('C4',261.63,'E4',329.63,'G4sharp',415.30,'A4',440,'B4',493.88, ...
    'C5',523.25,'D5',587.25,'D5sharp',622.25,'E5',659.25,'Silence',0);

Create audioOscillator and audioDeviceWriter objects. Use the default settings.

osc = audioOscillator;
aDW = audioDeviceWriter;

Create a vector with the initial melody of Fur Elise.

melody = [notes.Silence notes.Silence,...
    notes.E5 notes.D5sharp notes.E5 notes.D5sharp notes.E5 notes.B4 ...
        notes.D5 notes.C5 notes.A4 notes.A4 notes.Silence ...
    notes.C4 notes.E4 notes.A4 notes.B4 notes.B4 notes.Silence ...
    notes.E4 notes.G4sharp notes.B4 notes.C5 notes.C5 notes.Silence];

Specify the note duration in seconds. In an audio stream loop, call your audio oscillator and write the sound to your audio device. Update the frequency of the audio oscillator in noteDuration time steps to follow the melody. As a best practice, release your objects once complete.

noteDuration = 0.3;
      
i = 1;
tic
while i < numel(melody)
    tone = osc();
    aDW(tone);
    if toc >= noteDuration
        i = i + 1;
        osc.Frequency = melody(i);
        tic
    end
end

release(osc)
release(aDW)
Open Live Script

Create a low-frequency oscillator (LFO) lowpass filter, using the audioOscillator as a control signal.

Create dsp.AudioFileReader and audioDeviceWriter System objects to read from an audio file and write to your audio device. Create an SOS filter object to apply lowpass filtering to your audio signal.

fileReader = dsp.AudioFileReader('Filename','Engine-16-44p1-stereo-20sec.wav');
deviceWriter = audioDeviceWriter('SampleRate',fileReader.SampleRate);
lowpassFilter = dsp.SOSFilter(CoefficientSource='Input port');

Create an audio oscillator object. Your audio oscillator controls the cutoff frequency of the lowpass filter in an audio stream loop.

osc = audioOscillator('SignalType','sawtooth', ...
    'DCOffset',0.05, ...
    'Amplitude',0.03, ...
    'SamplesPerFrame',fileReader.SamplesPerFrame, ...
    'SampleRate',fileReader.SampleRate, ...
    'Frequency',5);

In a loop, filter the audio signal through the lowpass filter. Write the output signal to your audio device.

while ~isDone(fileReader)
    audioIn    = fileReader();
    ctrlSignal = osc();
    [B,A]      = designVarSlopeFilter(48,ctrlSignal(end),Orientation="row");
    audioOut   = lowpassFilter(audioIn,B,A);
    deviceWriter(audioOut);
end

As a best practice, release objects once complete.

release(osc)
release(fileReader)
release(deviceWriter)

For a more complete implementation of an LFO Filter, see audiopluginexample.LFOFilter in the Audio Plugin Example Gallery.

Extended Capabilities

Version History

Introduced in R2016a

expand all

See Also

|