audioDeviceReader - Record from sound card - MATLAB (original) (raw)
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:
- Create the
audioDeviceReaderobject 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?
Creation
Syntax
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 tosampleRateValue.
`deviceReader` = audioDeviceReader(`sampleRateValue`,`sampPerFrameValue`) sets the SamplesPerFrame property tosampPerFrameValue.
`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 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.
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
IfDriveris specified as'ASIO', useasiosettings to set the sound card buffer size to theSamplesPerFramevalue of youraudioDeviceReaderSystem 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. UsegetAudioDevices 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 youraudioDeviceReader 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 setNumChannelsto 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
Description
[audioFromDevice](audiodevicereader-system-object.html#mw%5F446d6ed2-ee2a-43ce-a44a-d2a9e77cddda)= `deviceReader`() returns one frame of audio samples from the selected audio input device.
[[audioFromDevice](audiodevicereader-system-object.html#mw%5F446d6ed2-ee2a-43ce-a44a-d2a9e77cddda),[numOverrun](audiodevicereader-system-object.html#mw%5F93876ffb-9c89-4493-83da-b9ef1c9da67a)] = `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 oneaudioDeviceReader at a time. To release the audio device, callrelease 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:
Specific to audioDeviceReader
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.')
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: 44100Use 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')
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')
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')
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)
Use info to determine the maximum number of input channels available with your specified Driver and Device configuration.
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: 44100Show 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)
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 (
.dllfiles) included with MATLAB. Use thepackNGofunction 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