Main Content

audioPlayerRecorder

Simultaneously play and record using an audio device

expand all in page

Description

The audioPlayerRecorder 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:

  1. Create the audioPlayerRecorder object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

playRec = audioPlayerRecorder
playRec = audioPlayerRecorder(sampleRateValue)
playRec = audioPlayerRecorder(___,Name,Value)

Description

playRec = audioPlayerRecorder returns a System object, playRec, that plays audio samples to an audio device and records samples from the same audio device, in real time.

playRec = audioPlayerRecorder(sampleRateValue) sets the SampleRate property to sampleRateValue.

playRec = audioPlayerRecorder(___,Name,Value) sets each property Name to the specified Value. Unspecified properties have default values.

Example: 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.

Properties

expand all

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

Note

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 mode, 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 audioPlayerRecorder object.

Data Types: char | string

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 hardware.

Data Types: single | double

Data type used by device, specified as a character vector or string.

Data Types: char | string

Option to support variable frame size, specified as false or true.

  • false –– If the audioPlayerRecorder object 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 audioPlayerRecorder object 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 SupportVariableSize to false. If variable-size input is required by your audio system, set SupportVariableSize to true.

Data Types: logical

Buffer size of audio device, specified as a positive integer.

Note

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 audioPlayerRecorder System object.

Dependencies

To enable this property, set SupportVariableSize to true.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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 is used.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Usage

Syntax

audioFromDevice = playRec(audioToDevice)
[audioFromDevice,numUnderrun] = playRec(audioToDevice)
[audioFromDevice,numUnderrun,numOverrun] = playRec(audioToDevice)

Description

audioFromDevice = playRec(audioToDevice) writes one frame of audio samples, audioToDevice, to the selected audio device, and returns one frame of audio, audioFromDevice.

example

[audioFromDevice,numUnderrun] = playRec(audioToDevice) returns the number of samples overrun since the last call to playRec.

example

[audioFromDevice,numUnderrun,numOverrun] = playRec(audioToDevice) returns the number of samples underrun since the last call to playRec.

example

Note:  When you call the audioPlayerRecorder System object, the audio device specified by the Device property is locked. An audio device can be locked by only one audioPlayerRecorder at a time. To release the audio device, call release on the audioPlayerRecorder System object.

Input Arguments

expand all

Audio signal to write to device, specified as a matrix. The columns of the matrix are treated as independent audio channels.

Data Types: single | double | int8 | int16 | int32 | uint8

Output Arguments

expand all

Audio signal read from device, returned as a matrix the same size and data type as audioToDevice.

Data Types: single | double | int16 | int32 | uint8

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.

Data Types: uint32

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.

Data Types: uint32

Object Functions

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 obj, use this syntax:

release(obj)

expand all

getAudioDevicesList available audio devices
infoGet audio device information
cloneCreate duplicate System object
isLockedDetermine if System object is in use
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
stepRun System object algorithm
setupOne-time set up tasks for System objects

Examples

collapse all

Open Live Script

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:

  1. Read an audio signal from your file.

  2. Play the audio signal to your device and simultaneously record audio from your device. Use the optional nUnderruns and nOverruns output arguments to track any loss of synchronization.

  3. 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)
Open Script

The 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

Create an audioPlayerRecorder object with default settings. The audioPlayerRecorder is automatically configured to a compatible device and driver.

aPR = audioPlayerRecorder;

The 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 audioToDevice to output channels of your device

  • Maps input channels of your device to columns of audioFromDevice

By default, 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 info method.

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.

Call the 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 audioToDevice matrix.

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.

Run the 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.

release(aPR)

Extended Capabilities

Version History

Introduced in R2017a

expand all

See Also

Functions

Blocks

Topics