To Audio Device

Library

Sinks

dspsnks4

Description

The To Audio Device block sends audio data to your computer's audio device. This block is not supported for use with the Simulink^® Model block.

Use the Device parameter to specify the device to which you want to send the audio data. This parameter is automatically populated based on the audio devices installed on your system.

Select the Inherit sample rate from input check box if you want the block to inherit the sample rate of the audio signal from the input to the block. If you clear this check box, the Sample rate (Hz) parameter appears on the block. Use this parameter to specify the number of samples per second in the signal.

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 to specify the data type of the audio data that is sent to the device. You can choose:

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

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

Input 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 input data type and the device does not support the input data type, the block uses the next lowest-precision data type supported by the device.

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 To Audio Device block buffers the data from a Simulink signal using the process illustrated by the following figure.

At the start of the simulation, the queue is filled with silence. Specify the size of this queue using the Queue duration (seconds) parameter. As Simulink runs, the block appends Simulink frames to the bottom of the queue.
At each time step, the blocks sends a buffer of samples from the top of the queue to the audio device. Select the Automatically determine buffer size check box to allow the block to use a conservative buffer size. See the From Audio Device block reference page for the equation the block uses to calculate this buffer size. If you clear this check box, the Buffer size (samples) parameter appears on the block. Use this parameter to specify the size of the buffer in samples.
The block writes the buffer of audio data to the device. If the queue did not contain enough data to completely fill the buffer, the block fills the remaining portion of the buffer with zeros. This data has a the data type specified by the Device data type parameter.

When the simulation throughput rate is lower than the hardware throughput rate, the queue, which is initially full, becomes empty. If the queue is empty, the block sends zeros (silence) to the audio device. You can monitor inserted zeroes using the optional Underrun output port. When the simulation throughput rate is higher than the hardware throughput rate, the To Audio Device block waits to write data to the queue.

To minimize the chance of dropouts, the block checks to make sure the queue duration is at least as large as the maximum of the buffer size and the frame size. If it is not, the queue duration is automatically set to this maximum value.

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 play audio, channel mapping allows you to specify which channel of the audio device directs input to a specific channel of audio data. You can specify channel mapping as a vector of output channel indices corresponding to each output channel of data being written. The default value in the Device Output Channels parameter is 1:MAXOUTPUTCHANNELS. If you do not select the default mapping, you must specify the Device Output Channels parameter in the dialog box.

Example: The selected output audio device contains 8 channels. The data being output has dimensions N×3 (3–channel data). You want the output to be redirected as follows:

First data channel to Audio Device channel 3
Second data channel to Audio Device channel 1
Third data channel to Audio Device channel 8

Thus, you would specify the Device Output Channels as [3 1 8].

Troubleshooting

Not Keeping Up in Real Time

When Simulink cannot keep up with an audio device that is operating in real time, the queue becomes empty and gaps occur in the audio data that the block sends to the device. Select the Output number of samples by which the queue was underrun check box to add an output port indicating when the queue was empty. 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 supply can lag the hardware's data demand.
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 device. If the buffer is too big, Simulink must wait for the device to empty the buffer before it can write 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 use frame-based processing 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/maci64 (csh/tcsh)` `export DYLD_LIBRARY_PATH $LD_LIBRARY_PATH: $MATLABROOT/bin/maci64 (Bash)`
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/maci64 (csh/tcsh)

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

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%

Channel-to-Speaker Mapping on Windows Operating Systems

The To Audio Device and From Audio Device blocks can support multiple channels. On Windows^® operating systems, the channel-to-speaker mapping is defined as listed below. This mapping only applies when your sound card is properly configured and capable of receiving the audio data you send. If the number of channels on the card does not match the number of channels on the block, or if you specify a data type for the Device data type parameter that is not supported by your device, the Windows mixer intervenes to translate from one format to another. If the Windows mixer does intervene, the channel-to-speaker mapping might differ from what is specified here.

Single channel input — Front center speaker
On systems with two speakers, the front center channel is split between the right and left speakers.
Multichannel input — Channels are assigned to speakers as follows:
- One channel — Front center
- Two channels — Front left, front right
- Four channels — Front left, front right, rear left, rear right
- Six channels — Front left, front right, front center, low frequency, rear left, rear right
- Eight channels — Front left, front right, front center, low frequency, rear left, rear right, front left center, front right center
- For all other channel combinations, the channel assignment is dictated by the audio card.

Audio Hardware API

The To Audio Device and From Audio Device blocks use the open-source PortAudio library in order to communicate with the audio hardware on a given computer. The PortAudio library supports a range of API’s 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^®: ALSA, OSS
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 which device to send the audio data to.
Inherit sample rate from input: Select this check box if you want the block to inherit the sample rate of the audio signal from the input to the block.
Sample rate (Hz): Specify the number of samples per second in the signal. This parameter is visible when the Inherit sample rate from input check box is cleared.
Device data type: Specify the data type of the audio data sent to the device.
Automatically determine buffer size: Select this check box to allow the block to calculate a conservative buffer size.
Buffer size (samples): Specify the size of the buffer. 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.
Use default mapping between Data and Device Output Channels: 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.
Device Output Channels: Specify the channel mapping. This parameter is visible when the Use default mapping between Device Input Channels and Data check box is disabled.
Output number of samples by which the queue was underrun: Select this check box to output the number of zero samples inserted into the audio stream due to queue underrun since the last transfer of a frame to 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.

Supported Data Types

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

Documentation