dsp.AudioPlayer

(Removed) Play audio data using computer's audio device

Compatibility

The dsp.AudioPlayer object has been removed. Existing instances of the object error out. Replace with audioDeviceWriter object. For more information, see Compatibility Considerations.

Description

The AudioPlayer object plays audio data using the computer's audio device.

To play audio data using the computer’s audio device:

1. Define and set up your audio player object. See Construction.

2. Call step to play audio data according to the properties of dsp.AudioPlayer. The behavior of step is specific to each object in the toolbox.

This System object™ buffers the data from the audio device using the process illustrated by the following figure.

Note

Starting in R2016b, instead of using the step method to perform the operation defined by the System object, you can call the object with arguments, as if it were a function. For example, y = step(obj,x) and y = obj(x) perform equivalent operations.

Construction

H = dsp.AudioPlayer returns an audio player object, H, that plays audio samples using an audio output device in real-time.

H = dsp.AudioPlayer('PropertyName',PropertyValue, ...) returns an audio player object, H, with each property set to the specified value.

H = dsp.AudioPlayer(SAMPLERATE,'PropertyName',PropertyValue, ...) returns an audio player object, H, with the SampleRate property set to SAMPLERATE and other specified properties set to the specified values. This System object supports variable-size input. If you use variable-size signals with this System object, you may experience sound dropouts when the size of the input frame increases. To avoid this behavior, use a signal of maximum expected size when you first call step to start running through this System object.

Properties

DeviceName	Device to which to send audio data Specify the device to which to send the audio data. The default is Default, which is the computer's standard output device. You can use tab completion to query valid DeviceName assignments for your computer by typing H.DeviceName = ' and then pressing the tab key.
SampleRate	Number of samples per second sent to audio device Specify the number of samples per second in the signal as an integer. The default is 44100. This property is tunable.
DeviceDataType	Data type used by device Specify the data type used by the audio device to acquire audio data as Determine from input data type , 8-bit integer, 16-bit integer, 24-bit integer, or 32-bit float. The default is Determine from input data type.
BufferSizeSource	Source of Buffer Size Specify how to determine the buffer size as Auto or Property. The default is Auto. When this property is set to Auto, an appropriate buffer size based on the SampleRate gets computed.
BufferSize	Buffer size Specify the size of the buffer that the audio player object uses to communicate with the audio device as an integer. BufferSize is half the size of the sound card buffer. A frame of data cannot be passed to the queue until the device empties the buffer, which introduces latency. Latency is the time it takes the device to empty the queue and the buffer. BufferSize has to be smaller than the effective queue duration. This property is tunable. Tuning this property involves a balance between device latency and the possibility of dropping data (buffer underrun). This property applies when you set the BufferSizeSource property to Property. The default is 4096. To set the BufferSize to a value other than the default, first change the BufferSizeSource to 'Property'. You can select BufferSize in the list of properties.
QueueDuration	Size of queue in seconds Specify the length of the audio queue, in seconds. The default is 1.0. This property is tunable. The purpose of the queue is to control the trade-off between latency and data dropout. Latency is calculated by the following equation: $$latency=\frac{QueueDuration\times SampleRate+2\times BufferSize}{SampleRate}$$. To minimize latency, lower the QueueDuration or set it to 0. However, be aware that data dropouts or loss of system robustness may result. The QueueDuration property specifies the duration of the signal, in seconds, that can be buffered during the simulation. This value is the maximum length of time that the System object data supply can lag the device’s data demand. If the MATLAB® data throughput rate is lower than the device throughput rate, a buffer underrun occurs. You can use OutputNumUnderrunSamples to monitor underrun. To correct the underrun, make the queue duration larger than the buffer. If the MATLAB data throughput rate is higher than the device throughput rate, a buffer overrun occurs, causing the System object to wait before writing data to the queue. To minimize the chance of dropouts, the System object checks to verify 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. At the start of the simulation, the queue is filled with silence. At each time step, the System object sends a buffer of samples from the top of the queue to the audio device. If the queue does not contain enough data to completely fill the buffer, the System object fills the remaining portion of the buffer with zeros.
OutputNumUnderrunSamples	Enable output of underrun count Set to true to output the number of zero samples inserted due to queue underrun since the last call to the step method. The default is false.
ChannelMappingSource	Source of device channel mapping Specify whether to determine the channel mapping as 'Auto' or as 'Property'. If you set the value of ChannelMappingSource to 'Auto', the ChannelMapping field is rendered inactive. If you set this property to 'Property', the vector specified in the ChannelMapping field is used to route the output.
ChannelMapping	Data-to-device channel mapping Vector of valid channel indices to represent the mapping between data and device output channels. The term Channel Mapping refer 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 data to output a specific channel of audio data. By default, the ChannelMapping field is [1:MAXOUTPUTCHANNELS], where MAXOUTPUTCHANNELS depends upon the selected device.

Methods

step	Write audio to audio output device

Common to All System Objects
release	Allow System object property value changes

Troubleshooting

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	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%

Algorithms

This object implements the algorithm, inputs, and outputs described on the To Audio Device block reference page. The object properties correspond to the block parameters.

Compatibility Considerations

dsp.AudioPlayer System object has been removed

Errors starting in R2020a

dsp.AudioPlayer System object has been removed. Use audioDeviceWriter instead.

Update Code

This table shows typical usage of the System object and explains how to update existing code to use the equivalent function.

Discouraged Usage

Recommended Replacement

AFR = dsp.AudioFileReader; AP = dsp.AudioPlayer('SampleRate',22050); while ~isDone(AFR) audio = AFR(); AP(audio); end % Wait until audio is played to the end pause(AP.QueueDuration); % close the input file release(AFR); % close the audio output device release(AP); If you are using a release prior to R2016b, replace AP(audio) with step(AP,audio).

fileReader = dsp.AudioFileReader; devWriter = audioDeviceWriter('SampleRate',... fileReader.SampleRate); fileInfo = audioinfo(fileReader.Filename); % Initialize audio device setup(devWriter, zeros(fileReader.SamplesPerFrame, ... fileInfo.NumChannels)); while ~isDone(fileReader) audioSamples = fileReader(); play(devWriter, audioSamples); end % close the input file release(fileReader); % close the audio output device release(devWriter);