This example shows how to create components for a system that processes a long stream of audio data. The data is read from a file, filtered, and then played.
A System object™ is a component you can use to create your system in MATLAB. System objects support fixed- or variable-size data. Variable-size data is data whose size can change at run time. By contrast, fixed-size data is data whose size is known and locked at initialization time, and therefore, cannot change at run time.
Note: If you use a function to create and use a System object, specify the object creation using conditional code. This will prevent errors if that function is called within a loop.
These examples use System objects that are predefined in the software. You can also create your own System objects (see Define New System Objects).
The particular predefined components you need are:
dsp.AudioFileReader — Read
the file of audio data
dsp.FIRFilter — Filter the
dsp.AudioPlayer — Play the
filtered audio data
First, you create the component objects, using default property settings:
audioIn = dsp.AudioFileReader; filtLP = dsp.FIRFilter; audioOut = dsp.AudioPlayer;
Next, you configure each System object for your system.
If you did not set an object's properties when you created it and do not want to use default values, you must explicitly set those properties. Some properties allow you to change their values while your system is running. See Reconfigure Your System During Runtime for information.
Most properties are independent of each other. However, some System object properties enable or disable another property or limit the values of another property. To avoid errors or warnings, you should set the controlling property before setting the dependent property.
To display the current property values for an object, type that
object's handle name at the command line (such as
To display the value of a specific property, type
This example shows how to configure the components for your system by setting the component objects' properties.
Use this procedure if you have created your components separately from configuring them. If you have not yet created your components, use the procedure below that describes how to create and configure your components at the same time.
For the file reader object, specify the file to read and set the output data type.
audioIn.Filename = 'speech_dft_8kHz.wav'; audioIn.OutputDataType = 'single';
For the filter object, specify the filter numerator coefficients
fir1 function, which specifies the lowpass
filter order and the cutoff frequency.
filtLP.Numerator = fir1(160,.15);
For the audio player object, specify the sample rate. In this case, use the same sample rate as the input data.
audioOut.SampleRate = audioIn.SampleRate;
This example shows how to create your System object components and configure the desired properties at the same time. To avoid errors or warnings for dependent properties, you should set the controlling property before setting the dependent property. Use this procedure if you have not already created your components.
Create the file reader object, specify the file to read, and set the output data type.
audioIn = dsp.AudioFileReader('speech_dft_8kHz.wav',... 'OutputDataType','single')
Create the filter object and specify the filter numerator
fir1 function. Specify the lowpass filter
order and the cutoff frequency of the
filtLP = dsp.FIRFilter('Numerator',fir1(160,.15));
Create the audio player object and specify the sample rate. In this case, use the same sample rate as the input data.
audioOut = dsp.AudioPlayer('SampleRate',audioIn.SampleRate);
After you create the components, you can assemble them in your system.
After you have determined the components you need and have created and configured your System objects, assemble your system. You use the System objects like other MATLAB variables and include them in MATLAB code. You can pass MATLAB variables into and out of System objects.
The main difference between using System objects and using functions
step method. The
is the processing command for each System object and is customized
for that specific System object. This method initializes your
objects and controls data flow and state management of your system.
You typically use
step within a loop.
You use the output from an object's
as the input to another object's
For some System objects, you can use properties of those objects to
change the number of inputs or outputs. To verify that the appropriate
number of input and outputs are being used, you can use
any System object. For information on all available System object
methods, see System Object Methods.
This example shows how to write the full code for reading, filtering, and playing a file of audio data.
You can type this code on the command line or put it into a program file.
audioIn = dsp.AudioFileReader('speech_dft_8kHz.wav',... 'OutputDataType','single'); filtLP = dsp.FIRFilter('Numerator',fir1(160,.15)); audioOut = dsp.AudioPlayer('SampleRate',audioIn.SampleRate); while ~isDone(audioIn) audio = step(audioIn); % Read audio source file y = step(filtLP,audio); % Filter the data step(audioOut,y); % Play the filtered data end
isDonemethod to read through the entire file. The
stepmethod is used on each object inside the loop.
Now, you are ready to run your system.
Run your code either by typing directly at the command line
or running a file containing your program. When you run the code for
your system, the
step method instructs each object
to process data through that object.
The first call to the
step method initializes
and then locks your object. When a System object has started processing
data, it is locked to prevent changes that would disrupt its processing.
isLocked method to verify whether an object
is locked. When the object is locked, you cannot change:
Number of inputs or outputs
Data type of inputs or outputs
Data type of any tunable property
Dimensions of inputs or tunable properties, except for System objects that support variable-size data
Value of any nontunable property
To make changes to your system while it is running, see Reconfigure Your System During Runtime.
When a System object has started processing data, it is locked
to prevent changes that would disrupt its processing. You can use
any System object to verify whether it is locked or not. When processing
is complete, you can use the
release method to unlock
a System object.
Some object properties are tunable, which enables you to change them even if the object is locked. Unless otherwise specified, System objects properties are nontunable. Refer to the object's reference page to determine whether an individual property is tunable. Typically, tunable properties are not critical to how the System object processes data.
This example shows how to change a tunable property.
You can change the filter type to a high-pass filter as
your code is running by replacing the while loop with the following
while loop. The change takes effect the next time the
is called (such as at the next iteration of the while loop).
reset(audioIn); % Reset audio file filtLP.Numerator = fir1(160,0.15,'high'); while ~isDone(audioIn) audio = step(audioIn); % Read audio source file y = step(filtLP,audio); % Filter the data step(audioOut,y); % Play the filtered data end
During simulation, some System objects do not allow complex data if the object was initialized with real data. You cannot change any input complexity during code generation.
You can change the value of a tunable property without a warning or error being produced. For all other changes at run time, an error occurs.