Simultaneously play and record using an audio device
System object™ reads and writes audio samples using your computer’s audio device. To use
audioPlayerRecorder, you must have an audio device and driver capable of
simultaneous playback and record.
See Audio I/O: Buffering, Latency, and Throughput for a detailed explanation of the data flow.
To simultaneously play and record:
audioPlayerRecorderobject and set its properties.
Call the object with arguments, as if it were a function.
To learn more about how System objects work, see What Are System Objects?
playRec = audioPlayerRecorder
playRec, that plays audio samples to an audio device
and records samples from the same audio device, in real time.
sets the SampleRate
playRec = audioPlayerRecorder(
sets each property
playRec = audioPlayerRecorder(___,
Name to the specified
Unspecified properties have default values.
playRec = audioPlayerRecorder(48000,'BitDepth','8-bit
integer') creates a System object,
playRec, that operates at a 48 kHz sample rate and an
8-bit integer bit depth.
Unless otherwise indicated, properties are nontunable, which means you cannot change their
values after calling the object. Objects lock when you call them, and the
release function unlocks them.
If a property is tunable, you can change its value at any time.
For more information on changing property values, see System Design in MATLAB Using System Objects.
Device — Device used to play and record audio data
default audio device (default) | character vector | string
Device used to play and record audio data, specified as a character vector or
string. The object supports only devices enabled for simultaneous playback and recording
(full-duplex mode). Use
getAudioDevices to list available devices.
Supported drivers for
audioPlayerRecorder are platform-specific:
Windows® –– ASIO™
Mac –– CoreAudio
Linux® –– ALSA
The default audio device is the default device of your machine only if it supports
full-duplex mode. If your machine’s default audio device does not support full-duplex
audioPlayerRecorder specifies as the default device the first
available device it detects that is capable of full-duplex mode. Use the
info method to get the device name associated with your
SampleRate — Sample rate used by device to record and play audio data (Hz)
44100 (default) | positive integer
Sample rate used by device to record and play audio data, in Hz, specified as a
positive integer. The range of
SampleRate depends on your audio
BitDepth — Data type used by device
'16-bit integer' (default) |
'8-bit integer' |
'32-bit float' |
Data type used by device, specified as a character vector or string.
SupportVariableSize — Support variable frame size
false (default) |
Option to support variable frame size, specified as
false–– If the
audioPlayerRecorderobject is locked, the input must have the same frame size at each call. The buffer size of your audio device is the same as the input frame size. If you are using the object on Windows, open the ASIO UI to set the sound card buffer to the frame size value.
true–– If the
audioPlayerRecorderobject is locked, the input frame size can change at each call. The buffer size of your audio device is specified through the BufferSize property.
To minimize latency, set
false. If variable-size input is required by your audio system, set
BufferSize — Buffer size of audio device
1024 (default) | positive integer
Buffer size of audio device, specified as a positive integer.
If you are using the object on a Windows machine, use
asiosettings to set the sound card buffer size to the
BufferSize value of your
To enable this property, set SupportVariableSize to
PlayerChannelMapping — Mapping between columns of played data and channels of device
 (default) | scalar | vector
Mapping between columns of played data and channels of output
device, specified as a scalar or as a vector of valid channel indices. The default value
of this property is
, which means that the default channel mapping
To ensure mono output on only one channel of a stereo device, use the default
PlayerChannelMapping setting and provide a stereo signal where
one channel is all zeros.
outputLeftOnly = [x(:,1) zeros(size(x,1),1)];
outputRightOnly = [zeros(size(x,1),1) x(:,1)];
RecorderChannelMapping — Mapping between channels of device and columns of recorded data
1 (default) | scalar | vector
Mapping between channels of your audio device and columns of recorded data,
specified as a scalar or as a vector of valid channel indices. The default value is
1, which means that the first recording channel on the device is
used to acquire data and is mapped to a single-column matrix.
writes one frame of audio samples,
audioToDevice, to the selected
audio device, and returns one frame of audio,
returns the number of samples overrun since the last call to
returns the number of samples underrun since the last call to
Note: When you call the
System object, the audio device specified by the
Device property is
locked. An audio device can be locked by only one
a time. To release the audio device, call
release on the
audioToDevice — Audio to device
Audio signal to write to device, specified as a matrix. The columns of the matrix are treated as independent audio channels.
audioFromDevice — Audio from device
Audio signal read from device, returned as a matrix the same size and data type as
numUnderrun — Number of samples underrun
Number of samples by which the player queue was underrun since the last call to
playRec. Underrun refers to output signal
silence. Output signal silence occurs if the device buffer is empty when it is time
for digital-to-analog conversion. This results when the processing loop in MATLAB does
not supply samples at the rate the sound card demands.
numOverrun — Number of samples overrun
Number of samples by which the recorder queue was overrun since the last call to
playRec. Overrun refers to input signal
drops. Input signal drops occur when the processing stage does not keep pace with the
acquisition of samples.
To use an object function, specify the
System object as the first input argument. For
example, to release system resources of a System object named
Specific to audioPlayerRecorder
Common to All System Objects
Synchronize Playback and Recording
Synchronize playback and recording using a single audio device. If synchronization is lost, print information about samples dropped.
Create objects to read from and write to an audio file. Create an
audioPlayerRecorder object to play an audio signal to your device and simultaneously record audio from your device.
fileReader = dsp.AudioFileReader('Counting-16-44p1-mono-15secs.wav', ... 'SamplesPerFrame',512); fs = fileReader.SampleRate; fileWriter = dsp.AudioFileWriter('Counting-PlaybackRecorded.wav', ... 'SampleRate',fs); aPR = audioPlayerRecorder('SampleRate',fs);
In a frame-based loop:
Read an audio signal from your file.
Play the audio signal to your device and simultaneously record audio from your device. Use the optional
nOverrunsoutput arguments to track any loss of synchronization.
Write your recorded audio to a file.
Once the loop is completed, release the objects to free devices and resources.
while ~isDone(fileReader) audioToPlay = fileReader(); [audioRecorded,nUnderruns,nOverruns] = aPR(audioToPlay); fileWriter(audioRecorded) if nUnderruns > 0 fprintf('Audio player queue was underrun by %d samples.\n',nUnderruns); end if nOverruns > 0 fprintf('Audio recorder queue was overrun by %d samples.\n',nOverruns); end end
Audio player queue was underrun by 512 samples.
release(fileReader) release(fileWriter) release(aPR)
Specify Nondefault Channel Mapping
audioPlayerRecorder System object™ enables you to specify a nondefault mapping between the channels of your audio device and the data sent to and received from your audio device. To run this example, your audio device must have at least two channels and be capable of full-duplex mode.
Using Default Settings
audioPlayerRecorder object with default settings. The
audioPlayerRecorder is automatically configured to a compatible device and driver.
aPR = audioPlayerRecorder;
audioPlayerRecorder combines reading from your device and writing to your device in a single call:
audioFromDevice = aPR(audioToDevice). Calling the
audioPlayerRecorder with default settings:
Maps columns of
audioToDeviceto output channels of your device
Maps input channels of your device to columns of
audioFromDevice is a one-column matrix corresponding to channel 1 of your audio device. To view the maximum number of input and output channels of your device, use the
aPRInfo = info(aPR);
aPRInfo is returned as a structure with fields containing information about your selected driver, audio device, and the maximum number of input and output channels in your configuration.
audioPlayerRecorder with a two-column matrix. By default, column 1 is mapped to output channel 1, and column 2 is mapped to output channel 2. The
audioPlayerRecorder returns a one-column matrix with the same number of rows as the
highToneGenerator = audioOscillator('Frequency',600,'SamplesPerFrame',256); lowToneGenerator = audioOscillator('Frequency',200,'SamplesPerFrame',256); for i = 1:250 C = highToneGenerator(); D = lowToneGenerator(); audioToDevice = [C,D]; audioFromDevice = aPR(audioToDevice); end
Nondefault Channel Mapping for Audio Output
Specify a nondefault channel mapping for your audio output. Specify that column 1 of
audioToDevice maps to channel 2, and that column 2 of
audioToDevice maps to channel 1. To modify the channel mapping, the
audioPlayerRecorder object must be unlocked.
audioPlayerRecorder object. If you are using headphones or stereo speakers, notice that the high frequency and low frequency tones have switched speakers.
release(aPR) aPR.PlayerChannelMapping = [2,1]; for i = 1:250 C = highToneGenerator(); D = lowToneGenerator(); audioToDevice = [C,D]; audioFromDevice = aPR(audioToDevice); end
Nondefault Channel Mapping for Audio Input
Specify a nondefault channel mapping for your audio input. Record data from only channel two of your device. In this case, channel 2 is mapped to a one-column matrix. Use
size to verify that
audioFromDevice is a 256-by-1 matrix.
release(aPR) aPR.RecorderChannelMapping = 2; audioFromDevice = aPR(audioToDevice); [rows,col] = size(audioFromDevice)
rows = 256 col = 1
As a best practice, release your audio device once complete.
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
System Objects in MATLAB Code Generation (MATLAB Coder)
The executable generated from this System object relies on prebuilt dynamic library files (
.dllfiles) included with MATLAB®. Use the
packNGofunction to package the code generated from this object and all the relevant files in a compressed zip file. Using this zip file, you can relocate, unpack, and rebuild your project in another development environment where MATLAB is not installed. For more details, see Run Audio I/O Features Outside MATLAB and Simulink.
Introduced in R2017a