|On this page…|
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.
Many System objects are predefined in the software. You can also define 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 audio data
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;
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 audioIn). To display the value of a specific property, type objecthandle.propertyname (such as audioIn.FileName).
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 as described in Create Components for Your System. If you have not yet created your components, use the procedure in Create and Configure 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 using the 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 configure System object property values.
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 using the fir1 function. Specify the lowpass filter order and the cutoff frequency of the fir1 function.
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. See Assemble Components to Create 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 is the step method. The step method 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 step method as the input to another object's step method. 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 getNumInputs and getNumOutputs on 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
The while loop uses the isDone method to read through the entire file. The step method is used on each object inside the loop.
Now, you are ready to run your system. See 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. Use the 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 isLocked on 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 step method 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
This example shows how to change a tunable property.
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.