audioPlayerRecorder - Simultaneously play and record using an audio device - MATLAB (original) (raw)

Simultaneously play and record using an audio device

Description

The audioPlayerRecorder System object™ reads and writes audio samples using your computer’s audio device. To useaudioPlayerRecorder, 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

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 therelease function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, seeSystem 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:

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 theinfo method to get the device name associated with youraudioPlayerRecorder 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 ortrue.

To minimize latency, set SupportVariableSize tofalse. If variable-size input is required by your audio system, setSupportVariableSize 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 theBufferSize 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 is1, 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

Description

[audioFromDevice](audioplayerrecorder-system-object.html#mw%5Fe8836f9e-5fd8-413d-9bd5-5190a1e294c5)= playRec([audioToDevice](audioplayerrecorder-system-object.html#mw%5F21082638-647c-49b4-bb30-346c6c941713)) writes one frame of audio samples, audioToDevice, to the selected audio device, and returns one frame of audio, audioFromDevice.

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 theaudioPlayerRecorder 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 asaudioToDevice.

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

Number of samples by which the player queue was underrun since the last call toplayRec. 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 toplayRec. 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:

expand all

clone Create duplicate System object
isLocked Determine if System object is in use
release Release resources and allow changes to System object property values and input characteristics
reset Reset internal states of System object
step Run System object algorithm
setup One-time set up tasks for System objects

Examples

collapse all

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)

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:

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

As a best practice, release your audio device once complete.

Extended Capabilities

expand all

Usage notes and limitations:

Version History

Introduced in R2017a

expand all

Specify a channel mapping in the audioPlayerRecorder object to play a mono signal on only one channel of a stereo device. Set thePlayerChannelMapping property to 1 (left) or 2 (right).

This change affects only DirectSound and CoreAudio drivers.

Previously, setting PlayerChannelMapping to 1 would play a mono signal in both left and right stereo channels. The default behavior for the object remains the same.