Read audio data from computer's audio device - Simulink

Library

Sources

dspsrcs4

Description

The From Audio Device block reads audio data from an audio device in real time. This block is not supported for use with the Simulink^® Model block.

Use the Device parameter to specify the device from which to acquire audio. This parameter is automatically populated based on the audio devices installed on your system. If you plug or unplug an audio device from your system, type clear mex at the MATLAB^® command prompt to update this list.

Use the Number of channels parameter to specify the number of audio channels in the signal. For example:

Enter 2 if the audio source is two channels (stereo).
Enter 1 if the audio source is single channel (mono).
Enter 6 if you are working with a 5.1 speaker system.

The block's output is an M-by-N matrix, where M is the number of consecutive samples and N is the number of audio channels.

Use the Sample rate (Hz) parameter to specify the number of samples per second in the signal. If the audio data is processed in uncompressed pulse code modulation (PCM) format, it should typically be sampled at one of the standard audio device rates: 8000, 11025, 22050, 44100, or 48000 Hz.

The range of supported audio device sample rates and data type formats, depend on both the sound card and the API which is chosen for the sound card.

Use the Device data type parameter to specify the data type of the audio data that the device is placing in the buffer. You can choose:

8-bit integer
16-bit integer
24-bit integer
32-bit float
Determine from output data type

If you choose Determine from output data type, the following table summarizes the block's behavior.

Output Data Type	Device Data Type
Double-precision floating point or single-precision floating point	32-bit floating point
32-bit integer	24-bit integer
16-bit integer	16-bit integer
8-bit integer	8-bit integer

If you choose Determine from output data type and the device does not support a data type, the block uses the next lowest precision data type supported by the device.

Use the Frame size (samples) parameter to specify the number of samples in the block's output. Use the Output data type parameter to specify the data type of audio data output by the block.

The generated code for this block relies on prebuilt .dll files. You can run this code outside the MATLAB environment, or redeploy it, but be sure to account for these extra .dll files when doing so. The packNGo function creates a single zip file containing all of the pieces required to run or rebuild this code. See packNGo (Simulink Coder) for more information.

Buffering

The From Audio Device block buffers the data from the audio device using the process illustrated by the following figure.

At the start of the simulation, the audio device begins writing the input data to a buffer. This data has the data type specified by the Device data type parameter.
When the buffer is full, the From Audio Device block writes the contents of the buffer to the queue. Specify the size of this queue using the Queue duration (seconds) parameter.
As the audio device appends audio data to the bottom of the queue, the From Audio Device block pulls data from the top of the queue to fill the Simulink frame. This data has the data type specified by the Output data type parameter.

Select the Automatically determine buffer size check box to allow the block to calculate a conservative buffer size using the following equation:

$s i z e = 2^{⌊ \log_{2} \frac{s r}{10} ⌋}$

In this equation, size is the buffer size, and sr is the sample rate. If you clear this check box, the Buffer size (samples) parameter appears on the block. Use this parameter to specify the buffer size in samples.

When the simulation throughput rate is lower than the hardware throughput rate, the queue, which is initially empty, fills up. If the queue is full, the block drops the incoming data from the audio device. You can monitor dropped samples using the optional Overrun output port. When the simulation throughput rate is higher than the hardware throughput rate, the From Audio Device block waits for new samples to become available.

Channel Mapping

The term Channel Mapping refers to a 1-to-1 mapping that associates channels on the selected audio device to channels of the data. When you record audio, channel mapping allows you to specify which channel of the audio data directs input to a specific channel of audio. You can specify channel mapping as a vector of audio channel indices corresponding to each channel of data being read. The default value in the Device Input Channels parameter is 1:MAXINPUTCHANNELS. If you do not select the default mapping, you must specify the Device Input Channels parameter in the dialog box.

Example: The selected input audio device contains 8 channels. You want to read data from only channels 2, 4, 6, and redirect the data as follows:

Audio Device channel 2 to first data channel
Audio Device channel 4 to second data channel
Audio Device channel 6 to third data channel

Thus you would specify the Device Input Channels as [2 4 6].

Troubleshooting

Not Keeping Up in Real Time

When Simulink cannot keep up with an audio device that is operating in real time, the queue fills up and the block begins to lose audio data. Select the Output number of samples by which the queue was overrun check box to add an output port indicating when the queue was full. Here are several ways to deal with this situation:

Increase the queue duration.
The Queue duration (seconds) parameter specifies the duration of the signal, in seconds, that can be buffered during the simulation. This is the maximum length of time that the block's data demand can lag behind the hardware's data supply.
Increase the buffer size.
The size of the buffer processed in each interrupt from the audio device affects the performance of your model. If the buffer is too small, a large portion of hardware resources are used to write data to the queue. If the buffer is too big, Simulink must wait for the device to fill the buffer before it moves the data to the queue, which introduces latency.
Increase the simulation throughput rate.
Two useful methods for improving simulation throughput rates are increasing the signal frame size and compiling the simulation into native code:
- Increase frame sizes and convert sample-based signals to frame-based signals throughout the model to reduce the amount of block-to-block communication overhead. This can increase throughput rates in many cases. However, larger frame sizes generally result in greater model latency due to initial buffering operations.
- Generate executable code with Simulink Coder™ code generation software. Native code runs much faster than Simulink and should provide rates adequate for real-time audio processing.

Other ways to improve throughput rates include simplifying the model and running the simulation on a faster PC processor. For other ideas on improving simulation performance, see Delay and Latency and Optimize Performance (Simulink).

Running an Executable Outside MATLAB

To run your generated standalone executable application in Shell, you need to set your environment to the following:

Platform Command

Mac

Platform	Command
Mac	`setenv DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maca64 (csh/tcsh on Apple silicon)` `export DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maca64 (Bash on Apple silicon)` `setenv DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maci64 (csh/tcsh on Mac Intel^®)` `export DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maci64 (Bash on Mac Intel)`
Linux	`setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/glnxa64 (csh/tcsh)` `export LD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/glnxa64 (Bash)`
Windows	`set PATH = $MATLABROOT\bin\win64;%PATH%`

setenv DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maca64 (csh/tcsh on Apple silicon)

export DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maca64 (Bash on Apple silicon)

setenv DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maci64 (csh/tcsh on Mac Intel^®)

export DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maci64 (Bash on Mac Intel)

Linux

setenv LD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/glnxa64 (csh/tcsh)

export LD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/glnxa64 (Bash)

Windows

set PATH = $MATLABROOT\bin\win64;%PATH%

Audio Hardware API

In order to communicate with the audio hardware on a given computer, the To Audio Device and From Audio Device blocks use the open-source PortAudio library. The PortAudio library supports a range of APIs designed to communicate with the audio hardware on a given platform. The following API choices were made when building the PortAudio library for the DSP System Toolbox™ product:

Windows^®: DirectSound, WDM—KS, ASIO™
Linux^®: OSS, ALSA
Mac: CoreAudio

For Windows, the default is DirectSound, for Linux, the default is ALSA, and for Mac there is only one choice.

To determine the audio hardware API currently selected, type the following command in the MATLAB command prompt.

getpref('dsp','portaudioHostApi')

The output is a scalar indicating the choice of the API.

1 — DirectSound
3 — ASIO
7 — OSS
8 — ALSA
11 — WDM-KS

To select a particular API, type the following command in the MATLAB command prompt.

setpref('dsp','portaudioHostApi',N)

where N is a scalar. Choose N based on the API choice above.

Parameters

Device: Specify the device from which to acquire audio data.
Use default mapping between Device Input Channels and Data: Select this check box to have the default mapping, where the data from the first channel of audio device is sent to the first channel of the input data, data from second channel of audio device is sent to second channel of data and so on. The maximum number of channels in the input data is determined by the Number of channels property.
Number of channels: Specify the number of audio channels. This parameter is visible when the Use default mapping between Device Input Channels and Data check box is enabled.
Device Input Channels: Specify the channel mapping. This parameter is visible when the Use default mapping between Device Input Channels and Data check box is disabled.
Sample rate (Hz): Specify the number of samples per second in the signal.
Device data type: Specify the data type used by the device to acquire audio data.
Automatically determine buffer size: Select this check box to enable the block to use a conservative buffer size.
Buffer size (samples): Specify the size of the buffer that the block uses to communicate with the audio device. This parameter is visible when the Automatically determine buffer size check box is cleared.
Queue duration (seconds): Specify the size of the queue in seconds.
Output number of samples by which the queue was overrun: Select this check box to output the number of samples lost to queue overrun since the last transfer of a frame from the audio device. You can use this value to debug throughput problems and adjust the queues and buffers in your model. To learn how to improve throughput, see Troubleshooting.
Frame size (samples): Specify the number of samples in the block's output signal.
Output data type: Select the data type of the block's output.

Supported Data Types

Port	Supported Data Types
Output	Double-precision floating point Single-precision floating point 32-bit signed integers 16-bit signed integers 8-bit unsigned integers
Overrun	32-bit unsigned integer