audioDeviceReader

Record from sound card

Description

The audioDeviceReader System object™ reads audio samples using your computer’s audio input device.

See Audio I/O: Buffering, Latency, and Throughput for a detailed explanation of the audio device reader data flow.

The audio device reader specifies the driver, the device and its attributes, and the data type and size output from your System object.

To stream data from an audio device:

1. Create the audioDeviceReader 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

deviceReader = audioDeviceReader

deviceReader = audioDeviceReader(sampleRateValue)

deviceReader = audioDeviceReader(sampleRateValue,sampPerFrameValue)

deviceReader = audioDeviceReader(___,Name,Value)

Description

deviceReader = audioDeviceReader returns a System object, deviceReader, that reads audio samples using an audio input device in real time.

deviceReader = audioDeviceReader(sampleRateValue) sets the SampleRate property to sampleRateValue.

deviceReader = audioDeviceReader(sampleRateValue,sampPerFrameValue) sets the SamplesPerFrame property to sampPerFrameValue.

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

Example: deviceReader = audioDeviceReader(16000,'BitDepth','8-bit integer') creates a System object, deviceReader, that operates at a 16 kHz sample rate and an 8-bit integer bit depth.

Properties

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.

Driver — Driver used to access audio device (Windows only)

'DirectSound' (default) | 'ASIO' | 'WASAPI'

Driver used to access your audio device, specified as 'DirectSound', 'ASIO', or 'WASAPI'.

• ASIO™ drivers do not come pre-installed on Windows^® machines. To use the 'ASIO' driver option, install an ASIO driver outside of MATLAB^®.

  Note

  If Driver is specified as 'ASIO', use asiosettings to set the sound card buffer size to the SamplesPerFrame value of your audioDeviceReader System object.

• WASAPI drivers are supported for exclusive-mode only.

ASIO and WASAPI drivers do not provide sample rate conversion. For ASIO and WASAPI drivers, set SampleRate to a sample rate supported by your audio device.

This property applies only on Windows machines. Linux^® machines always use the ALSA driver. Mac machines always use the CoreAudio driver.

Data Types: char | string

Device — Device used to acquire audio samples

default audio device (default) | character vector | string

Device used to acquire audio samples, specified as a character vector or string. Use getAudioDevices to list available devices for the selected driver.

Data Types: char | string

NumChannels — Number of input channels acquired by audio device

1 (default) | integer

Number of input channels acquired by audio device, specified as an integer. The range of NumChannels depends on your audio hardware.

Dependencies

To enable this property, set ChannelMappingSource to 'Auto'.

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

SamplesPerFrame — Frame size read from audio device

1024 (default) | integer

Frame size read from audio device, specified as a positive integer. SamplesPerFrame is also the size of your device buffer and the number of columns of the output matrix returned by your audioDeviceReader object.

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

SampleRate — Sample rate used by device to acquire audio data (Hz)

44100 (default) | positive integer

Sample rate used by device to acquire audio data, in Hz, specified as a positive integer. The range of SampleRate depends on your audio hardware.

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

BitDepth — Data type used by device to acquire audio data

'16-bit integer' (default) | '8-bit integer' | '32-bit float' | '24-bit integer'

Data type used by device to acquire audio data, specified as a character vector or string.

Data Types: char | string

ChannelMappingSource — Source of mapping between device channels and output matrix

'Auto' (default) | 'Property'

Source of mapping between the channels of your audio input device and columns of the output matrix, specified as 'Auto' or 'Property'.

• 'Auto' –– The default settings determine the mapping between device channels and output matrix. For example, suppose that your audio device has six channels available, and you set NumChannels to 6. The output from a call to your audio device reader is a six-column matrix. Column 1 corresponds to channel 1, column 2 corresponds to channel 2, and so on.

• 'Property' –– The ChannelMapping property determines the mapping between channels of your audio device and columns of the output matrix.

Data Types: char | string

ChannelMapping — Nondefault mapping between device channels and output matrix

[1:MaximumInputChannels] (default) | scalar | vector

Nondefault mapping between channels of your audio input device and columns of the output matrix, specified as a vector of valid channel indices. See Specify Channel Mapping for audioDeviceReader for more information.

Dependencies

To enable this property, set ChannelMappingSource to 'Property'.

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

OutputDataType — Data type of the output

'double' (default) | 'single' | 'int32' | 'int16' | 'uint8'

Data type of the output, specified as a character vector or string.

Note

If OutputDataType is specified as 'double' or 'single', the audio device reader outputs data in the range [–1, 1]. For other data types, the range is [min, max] of the specified data type.

Data Types: char | string

Usage

Syntax

audioFromDevice = deviceReader()

[audioFromDevice,numOverrun] = deviceReader()

Description

audioFromDevice = deviceReader() returns one frame of audio samples from the selected audio input device.

[audioFromDevice,numOverrun] = deviceReader() returns the number of samples by which the audio reader's queue was overrun since the last call to deviceReader.

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

Output Arguments

audioFromDevice — Audio from device

matrix

Audio signal read from device, returned as a matrix. The specified number of channels and the SamplesPerFrame property determine the matrix size. The data type of the matrix depends on the OutputDataType property.

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

numOverrun — Number of samples overrun

scalar

Number of samples by which the audio reader's queue was overrun since the last call to deviceReader.

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)

Specific to audioDeviceReader

getAudioDevices	List available audio devices
info	Get audio device information

Common to All System Objects

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

Read from Microphone and Write to Audio File

Record 10 seconds of speech with a microphone and send the output to a WAV file.

Create an audioDeviceReader object with default settings. Call setup to reduce the computational load of initialization in an audio stream loop.

deviceReader = audioDeviceReader;
setup(deviceReader)

Create a dsp.AudioFileWriter System object. Specify the file name and type to write.

fileWriter = dsp.AudioFileWriter('mySpeech.wav','FileFormat','WAV');

Record 10 seconds of speech. In an audio stream loop, read an audio signal frame from the device, and write the audio signal frame to a specified file. The file saves to your current folder.

disp('Speak into microphone now.')

Speak into microphone now.

tic
while toc < 10
    acquiredAudio = deviceReader();
    fileWriter(acquiredAudio);
end
disp('Recording complete.')

Recording complete.

Release the audio device and close the output file.

release(deviceReader)
release(fileWriter)

Reduce Latency Due to Input Device Buffer

Latency due to the input device buffer is the time delay of acquiring one frame of data. In this example, you modify default properties of your audioDeviceReader object to reduce latency.

Create an audioDeviceReader object with default settings.

deviceReader = audioDeviceReader

deviceReader = 
  audioDeviceReader with properties:

             Device: 'Default'
        NumChannels: 1
    SamplesPerFrame: 1024
         SampleRate: 44100

  Use get to show all properties

Calculate the latency due to your device buffer.

fprintf('Latency due to device buffer: %f seconds.\n',deviceReader.SamplesPerFrame/deviceReader.SampleRate)

Latency due to device buffer: 0.023220 seconds.

Set the SamplesPerFrame property of your audioDeviceReader object to 64. Calculate the latency.

deviceReader.SamplesPerFrame = 64;
fprintf('Latency due to device buffer: %f seconds.\n',deviceReader.SamplesPerFrame/deviceReader.SampleRate)

Latency due to device buffer: 0.001451 seconds.

Set the SampleRate property of your audioDeviceReader System object to 96000. Calculate the latency.

deviceReader.SampleRate = 96000;
fprintf('Latency due to device buffer: %f seconds.\n',deviceReader.SamplesPerFrame/deviceReader.SampleRate)

Latency due to device buffer: 0.000667 seconds.

Determine and Decrease Overrun

Overrun refers to input signal drops, which occur when the audio stream loop does not keep pace with the device. Determine overrun of an audio stream loop, add an artificial computational load to the audio stream loop, and then modify properties of your audioDeviceReader object to decrease overrun. Your results depend on your computer.

Create an audioDeviceReader System object with SamplesPerFrame set to 256 and SampleRate set to 44100. Call setup to reduce the computational load of initialization in an audio stream loop.

deviceReader = audioDeviceReader( ...
    'SamplesPerFrame',256, ...
    'SampleRate',44100);
setup(deviceReader)

Create a dsp.AudioFileWriter object. Specify the file name and data type to write.

fileWriter = dsp.AudioFileWriter('mySpeech.wav','FileFormat','WAV');

Record 5 seconds of speech. In an audio stream loop, read an audio signal frame from your device, and write the audio signal frame to a specified file.

totalOverrun = 0;
disp('Speak into microphone now.')

Speak into microphone now.

tic
while toc < 5
    [input,numOverrun] = deviceReader();
    totalOverrun = totalOverrun + numOverrun;
    fileWriter(input);
end
fprintf('Recording complete.\n')

Recording complete.

fprintf('Total number of samples overrun: %d.\n',totalOverrun)

Total number of samples overrun: 0.

fprintf('Total seconds overrun: %d.\n',double(totalOverrun)/double(deviceReader.SampleRate))

Total seconds overrun: 0.

Release your audioDeviceReader and dsp.AudioDeviceWriter objects and zero your counter variable.

release(fileWriter)
release(deviceReader)
totalOverrun = 0;

Use pause to add an artificial computational load to your audio stream loop. The computational load causes the audio stream loop to go slower than the device, which causes acquired samples to be dropped.

disp('Speak into microphone now.')

Speak into microphone now.

tic
while toc < 5
    [input,numOverrun] = deviceReader();
    totalOverrun = totalOverrun + numOverrun;
    fileWriter(input);
    pause(0.01)
end
fprintf('Recording complete.\n')

Recording complete.

fprintf('Total number of samples overrun: %d.\n',totalOverrun)

Total number of samples overrun: 97536.

fprintf('Total seconds overrun: %d.\n',double(totalOverrun)/double(deviceReader.SampleRate))

Total seconds overrun: 2.211701e+00.

Release your audioDeviceReader and dsp.AudioFileWriter objects, and set the SamplePerFrame property to 512. The device buffer size increases so that the device now takes longer to acquire a frame of data. Set your counter variable to zero.

release(fileWriter)
release(deviceReader)
deviceReader.SamplesPerFrame = 512;
totalOverrun = 0;

Calculate the total overrun of the audio stream loop using your modified SamplesPerFrame property.

disp('Speak into microphone now.')

Speak into microphone now.

tic
while toc < 5
    [input,numOverrun] = deviceReader();
    totalOverrun = totalOverrun + numOverrun;
    fileWriter(input);
    pause(0.01)
end
fprintf('Recording complete.\n')

Recording complete.

fprintf('Total number of samples overrun: %d.\n',totalOverrun)

Total number of samples overrun: 0.

fprintf('Total seconds overrun: %f.\n',totalOverrun/deviceReader.SampleRate)

Total seconds overrun: 0.000000.

Specify Channel Mapping for audioDeviceReader

Specify nondefault channel mapping for an audioDeviceReader object. This example is hardware specific. It assumes that your computer has a default audio input device with two available channels.

Create an audioDeviceReader object with default settings.

deviceReader = audioDeviceReader;

The default number of channels is 1. Call your audioDeviceReader object like a function with no arguments to read one frame of data from your audio device. Verify that the output data matrix has one column.

x = deviceReader();
[frameLength,numChannels] = size(x)

frameLength = 1024

numChannels = 1

Use info to determine the maximum number of input channels available with your specified Driver and Device configuration.

info(deviceReader)

ans = struct with fields:
                  Driver: 'DirectSound'
              DeviceName: 'Primary Sound Capture Driver'
    MaximumInputChannels: 2

Set ChannelMappingSource to 'Property'. The audioDeviceReader object must be unlocked to change this property.

release(deviceReader)
deviceReader.ChannelMappingSource = 'Property'

deviceReader = 
  audioDeviceReader with properties:

             Driver: 'DirectSound'
             Device: 'Default'
    SamplesPerFrame: 1024
         SampleRate: 44100

  Show all properties

By default, if ChannelMappingSource is set to 'Property', all available channels are mapped to the output. Call your audioDeviceReader object to read one frame of data from your audio device. Verify that the output data matrix has two columns.

x = deviceReader();
[frameLength,numChannels] = size(x)

frameLength = 1024

numChannels = 2

Use the ChannelMapping property to specify an alternative mapping between channels of your device and columns of the output matrix. Indicate the input channel number at an index corresponding to the output column. To change this property, first unlock the audioDeviceReader object.

release(deviceReader)
deviceReader.ChannelMapping = [2,1];

Now when you call your audioDeviceReader:

• Input channel 1 of your device maps to the second column of your output matrix.

• Input channel 2 of your device maps to the first column of your output matrix.

Acquire a specific channel from your input device.

deviceReader.ChannelMapping = 2;

If you call your audioDeviceReader, input channel 2 of your device maps to an output vector.

Extended Capabilities

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 (.dll files) included with MATLAB. Use the packNGo function 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.

Version History

Introduced in R2016a