# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# dsp.AudioRecorder System object

Package: dsp

Record audio data using computer's audio device

 Note:   The `dsp.AudioRecorder` object will be removed in a future release. Existing instances of the object continue to run. For new code, use the `audioDeviceReader` object from Audio System Toolbox™ instead.

## Description

The `AudioRecorder` object records audio data using the computer's audio device.

To record audio data using the computer's audio device:

1. Define and set up your audio recorder object. See Construction.

2. Call `step` to record audio data according to the properties of `dsp.AudioRecorder`. The behavior of `step` is specific to each object in the toolbox.

This System object™ buffers the data from a frame of data using the process illustrated by the following figure.

 Note:   Starting in R2016b, instead of using the `step` method to perform the operation defined by the System object, you can call the object with arguments, as if it were a function. For example, ```y = step(obj,x)``` and `y = obj(x)` perform equivalent operations.

## Construction

`H = dsp.AudioRecorder` returns an audio recorder object, `H`, that records audio samples using an audio input device in real-time.

```H = dsp.AudioRecorder('PropertyName',PropertyValue, ...)``` returns an audio recorder object, `H`, with each property set to the specified value.

## Properties

 `DeviceName` Device from which to acquire audio data Specify the device from which to acquire audio data. The default is `Default`, which is the computer's standard input device. You can use tab completion to query valid `DeviceName` assignments for your computer by typing `H.DeviceName = '` and then pressing the tab key. The tab completion functionality shows all valid audio device names for your computer. `SampleRate` Number of samples per second read from audio device Specify the number of samples per second in the signal as an integer. The default is 44100. This property is tunable. `NumChannels` Number of audio channels Specify the number of audio channels as an integer. The default is 2. `DeviceDataType` Data type used by device Specify the data type used by the device to acquire audio data as `Determine from output data type` , `8-bit integer`, ```16-bit integer```, `24-bit integer`, or `32-bit float`. The default is `Determine from output data type`. `BufferSizeSource` Source of Buffer Size Specify how to determine the buffer size as `Auto` or `Property`. The default is `Auto`. `BufferSize` Buffer size Specify as an integer the size of the buffer that the audio recorder object uses to communicate with the audio device. This property applies when you set the `BufferSizeSource` property to `Property`. The default is `4096`. This property is tunable. Tuning this property involves a balance between device latency and the possibility of dropping data (buffer underrun). The instant you receive the buffer from a device, you have samples that are relatively new and samples that are at least as old as the size of the buffer. Therefore, the buffer size introduces latency, which is the time required for the device to fill the queue and the buffer. `BufferSize` is half the size of the sound card buffer. The size of the buffer processed in each interrupt from the audio device affects the performance of the system. A frame of data cannot pass through the queue until the buffer is filled by the device, thus introducing latency. `BufferSize` has to be smaller than the effective queue duration. To set the `BufferSize` to a value other than the default, first change the `BufferSizeSource` to 'Property'. You can select `BufferSize` from the list of properties. `QueueDuration` Size of queue in seconds Specify the length of the audio queue, in seconds. The default is `1.0`. This property is tunable. The purpose of the queue is to control the trade-off between latency and data dropout. Latency is calculated by the following equation: $latency=\frac{QueueDuration×SampleRate+2×BufferSize}{SampleRate}$. To minimize latency, lower the `QueueDuration` or set it to 0. However, be aware that data dropouts or loss of system robustness may result. The `QueueDuration` property specifies the duration of the signal, in seconds, that can be buffered during the simulation. This value is the maximum length of time that the System object's data supply can lag the device's data demand. If the MATLAB® data throughput rate is lower than the device throughput rate, a buffer overrun occurs. You can use `OutputNumOverrunSamples` to monitor overrun. To correct the overrun, make the queue duration larger than the buffer. If the MATLAB data throughput rate is higher than the device throughput rate, a buffer underrun occurs, causing the System object to wait for new samples to become available. To minimize the chance of dropouts, the System object checks to verify the queue duration is at least as large as the maximum of the buffer size and the frame size. If it is not, the queue duration is automatically set to this maximum value. At the start of the simulation, the queue is filled with silence. At each time step, the audio device sends a buffer of samples to the top of the queue. `SamplesPerFrame` Number of samples in the output signal Specify the number of samples in the audio recorder's output as an integer. The default is 1024. `OutputDataType` Data type of the output Select the output data type as `uint8`, `int16`, `int32` , `single` , or `double`. The default is `double`. `OutputNumOverrunSamples` Enable output of overrun count Set to `true` to output the number of samples dropped due to queue overrun since the last call to the `step` method. The default is `false`. `ChannelMappingSource` Source of device channel mapping Specify whether to determine the channel mapping as `'Auto'` or as `'Property'`. If you set the value of `ChannelMappingSource` to `'Auto'`, the `ChannelMapping` field is rendered inactive. If you set this property to `'Property'`, the vector specified in the ChannelMapping field is used to route the input. Additionally, the `NumChannels` field is rendered inactive, because the channel map contains information about the number of data channels that the user is attempting to read. `ChannelMapping` Device-to-data channel mapping Vector of valid channel indices to represent the mapping between device input channels and the data. The term Channel Mapping refers to a 1-to-1 mapping that associates channels on the selected audio device to channels of the data. When you record audio, channel mapping allows you to specify which channel of the audio data directs input to a specific channel of audio. By default, the `ChannelMapping` field is [1:MAXNUMINPUTCHANNELS], where MAXNUMINPUTCHANNELS depends upon the selected device.

## Methods

 clone Create audio recorder object with same property values getNumInputs Number of expected inputs to step method getNumOutputs Number of outputs of step method isLocked Locked status for input attributes and nontunable properties release Allow property value and input characteristics changes step Record audio from recording device

## Examples

expand all

Note: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent `step` syntax. For example, myObject(x) becomes step(myObject,x).

Record ten seconds of speech from a microphone, and send the output to a .wav file.

```AR = dsp.AudioRecorder('OutputNumOverrunSamples',true); AFW = dsp.AudioFileWriter('myspeech.wav','FileFormat', 'WAV'); disp('Speak into microphone now'); tic; while toc < 10 [audioIn,nOverrun] = AR(); AFW(audioIn); if nOverrun > 0 fprintf('Audio recorder queue was overrun by %d samples\n'... ,nOverrun); end end release(AR); release(AFW); disp('Recording complete'); ```
```Speak into microphone now Recording complete ```

## Troubleshooting

### Running an Executable Outside MATLAB

To run your generated standalone executable application in Shell, you need to set your environment to the following:

PlatformCommand
Mac```setenv DYLD_LIBRARY_PATH \$LD_LIBRARY_PATH: \$MATLABROOT/bin/maci64 (csh/tcsh)```

```export DYLD_LIBRARY_PATH \$LD_LIBRARY_PATH: \$MATLABROOT/bin/maci64 (Bash)```

Linux```setenv LD_LIBRARY_PATH \$LD_LIBRARY_PATH: \$MATLABROOT/bin/glnxa64 (csh/tcsh)```

```export LD_LIBRARY_PATH \$LD_LIBRARY_PATH: \$MATLABROOT/bin/glnxa64 (Bash)```

Windows

`set PATH = \$MATLABROOT\bin\win64;%PATH%`

## Algorithms

This object implements the algorithm, inputs, and outputs described on the From Audio Device block reference page. The object properties correspond to the block parameters.