Description..

audiodevinfo

Obtain information on installed audio devices

Syntax

• d = audiodevinfo
  audiodevinfo(io)
  audiodevinfo(io,ID)
  audiodevinfo(io,ID,'DriverVersion')
  audiodevinfo(io,name)
  audiodevinfo(io,rate,bits,chans)
  audiodevinfo(io,ID,rate,bits,chans)
  

Description

Note This function is for use only with 32-bit, Windows-based machines.

d = audiodevinfo returns a structure, d with an input field and an output field. Each field is an array of structures that contains information about the system's audio input and output devices. Each array contains these fields: a string with the name of the device, a string with the version of the installed driver (DriverVersion), and the device's numeric ID.

audiodevinfo(io) returns the number of input (io=1) or output (io=0) audio devices on the system.

audiodevinfo(io,ID) returns the name of the audio device specified by its ID.

audiodevinfo(io,ID,'DriverVersion') returns a string containing the driver version of the specified audio device.

audiodevinfo(io,name) returns the device ID specified by name. You can enter a partial name, but the case must match. If no device with the specified name is found, -1 is returned.

audiodevinfo(io,rate,bits,chans) returns the device ID of the first audio device that supports the specified sample rate, number of bits, and number of channels, chans. If no matching device is found, -1 is returned.

audiodevinfo(io,ID,rate,bits,chans) returns 1 if the device, specified by its ID, supports the specified sample rate, number of bits, and number of channels, chans. If the device does not support the specified parameters, 0 is returned.

audioplayer

Create an audio player object

Syntax

• y = audioplayer(x,Fs)
  y = audioplayer(x,Fs,nbits)
  y = audioplayer(r)
  y = audioplayer(r,id)
  

Description

Note audioplayer is available only on Windows-based machines. On 32-bit, Windows-based machines with an installed 24-bit audio device, audioplayer supports 24-bit playback. To use all of the audioplayer features, your system needs a properly installed and configured sound card with 8- and 16-bit I/O, two channels, and support for sampling rates of up to 48 kHz.

y = audioplayer(x,Fs) returns a handle to an audio player object y using input audio signal x. The input signal x can be a vector or two-dimensional array containing single, double, int8, uint8, or int16 MATLAB data types. The input sample values for single and double data must be between -1 and 1. For int8, uint8, and int16 data, the ranges of sample values are -128 to 127, 0 to 255, and -32768 to 32767, respectively.

Fs is the sampling rate in Hz to use for playback. Valid values for Fs depend on the specific audio hardware installed. Typical values supported by most sound cards are 8000, 11025, 22050, and 44100 Hz.

y = audioplayer(x,Fs,nbits) returns a handle to an audio player object where nbits is the bit quantization to use for single or double data types. This is an optional parameter with a default value of 16. Valid values for nbits are 8 and 16 (and 24, if a 24-bit device is installed). You do not need to specify nbits for int8, uint8 or int16 data because the quantization is set automatically to 8 or 16, respectively.

y = audioplayer(r) returns a handle to an audio player object from an audiorecorder object r.

y = audioplayer(r,id) returns a handle to an audio player object from an audiorecorder object r, using the specified audio device id for output.

After you create an audio player object, you can use the methods listed below on that object. y represents the name of the returned audio player.

Method	Description
play(y) play(y,start) play(y,[start stop]) play(y,range)	Starts playback from the beginning and plays to the end, or from start sample to the end, or from start sample to stop sample. The values of start and stop can be specified in a two-element vector range.
playblocking(y) playblocking(y,start) playblocking(y,[start stop]) playblocking(y,range)	Same as play, but does not return control until playback completes.
stop(y)	Stops playback.
pause(y)	Pauses playback.
resume(y)	Restarts playback from where playback was paused.
isplaying(y)	Indicates whether playback is in progress. If 0, playback is not in progress. If 1, playback is in progress.
display(y) disp(y) get(y)	Displays all property information about audio player y.

Audio player objects have the properties listed below. To set a user-settable property use this syntax:

• set(y, 'property1', value,'property2',value,...)
  

To view a read-only property

• get(y,'property')            % Displays `property' setting.
  

Property	Description	Type
Type	Name of the object's class	read-only
SampleRate	Sampling frequency in Hz	user-settable
BitsPerSample	Number of bits per sample	read-only
NumberOfChannels	Number of channels	read-only
TotalSamples	Total length, in samples, of the audio data	read-only
Running	Status of the audio player ('on' or 'off')	read-only
CurrentSample	Current sample being played by the audio output device (If it is not playing, currentsample is the next sample to be played with play or resume.)	read-only
UserData	User data of any type	user-settable
Tag	User-specified object label string	user-settable
For information on using the following four properties, see Creating Timer Callback Functions in the MATLAB documentation. Note that for audio object callbacks, eventStruct (event) is currently empty ([]).
TimerFcn	Name of, or handle to, user-specified function to be called during playback	user-settable
TimerPeriod	Time, in seconds, between TimerFcn callbacks	user-settable
StartFcn	Name of, or handle to, the function to be called once when playback starts	user-settable
StopFcn	Name of or handle to the function to be called once when playback stops	user-settable

Example

Load a sample audio file, create an audio player object, and play the audio at a higher sampling rate. x contains the audio samples and Fs is the sampling rate. You can use any of the audioplayer functions listed above on the player.

• load handel;
  player=audioplayer(y,Fs);
  play(player,[1 (get(player,'SampleRate')*3)]);
  

To stop the playback, use this command:

• stop(player);                     % Equivalent to player.stop

audiorecorder

Create an audio recorder object

Syntax

• y = audiorecorder
  y = audiorecorder(Fs,nbits,channels)
  y = audiorecorder(Fs,nbits,channels,id)
  

Description

Note To use all of the audio recorder object features, your system must have a properly installed and configured sound card with 8- and 16-bit I/O and support for sampling rates of up to 48 kHz. On 32-bit, Windows-based machines with an installed 24-bit audio device, audiorecorder supports 24-bit recording.

y = audiorecorder returns a handle to an 8-kHz, 8-bit, mono audio recorder object.

y = audiorecorder(Fs,nbits,channels) returns a handle to an audio recorder object using the sampling rate, Fs ( in Hz), the sample size of nbits, and the number of channels. Fs can be any sampling rate supported by the audio hardware. Common sampling rates are 8000, 11025, 22050, and 44000. The value of nbits must be 8 or 16 (or 24, if a 24-bit device is installed). For mono or stereo, channels must be 1 or 2, respectively.

y = audiorecorder(Fs,nbits,channels,id) returns a handle to an audio recorder object using the audio device specified by its id for input.

After you create an audio recorder object, you can use the methods listed below on that object. y represents the name of the returned audio recorder.

Method	Description
record(y) record(y,length)	Starts recording. Records for length number of seconds.
recordblocking(y,length)	Same as record, but does not return control until recording completes.
stop(y)	Stops recording.
pause(y)	Pauses recording.
resume(y)	Restarts recording from where recording was paused.
isrecording(y)	Indicates the status of recording. If 0, recording is not in progress. If 1, recording is in progress.
play(y)	Creates an audioplayer, plays the recorded audio data, and returns a handle to the created audioplayer.
getplayer(y)	Creates an audioplayer and returns a handle to the created audioplayer.
getaudiodata(y) getaudiodata(y,'type')	Returns the recorded audio data to the MATLAB workspace. type is a string containing the desired data type. Supported data types are double, single, int16, int8, or uint8. If type is omitted, it defaults to 'double'. For double and single, the array contains values between -1 and 1. For int8, values are between -128 to 127. For uint8, values are from 0 to 255. For int16, values are from -32768 to 32767. If the recording is in mono, the returned array has one column. If it is in stereo, the array has two columns--one for each channel.
display(y) disp(y) get(y)	Displays all property information about audio recorder y.

Audio recorder objects have the properties listed below. To set a user-settable property use this syntax:

• set(y, 'property1', value,'property2',value,...)
  

To view a read-only property

• get(y,'property')            %displays `property' setting.
  

Property	Description	Type
Type	Name of the object's class	read-only
SampleRate	Sampling frequency in Hz	read-only
BitsPerSample	Number of bits per recorded sample	read-only
NumberOfChannels	Number of channels of recorded audio	read-only
TotalSamples	Total length, in samples, of the recording	read-only
Running	Status of the audio recorder ('on' or 'off')	read-only
CurrentSample	Current sample being recorded by the audio output device (If it is not recording, currentsample is the next sample to be recorded with record or resume.)	read-only
UserData	User data of any type	user-settable
For information on using the following four properties, see Creating Timer Callback Functions in the MATLAB documentation. Note that for audio object callbacks, eventStruct (event) is currently empty ([]).
TimerFcn	Name of or handle to user-specified function to be called during recording	user-settable
TimerPeriod	Time, in seconds, between TimerFcn callbacks	user-settable
StartFcn	Name of or handle to the function to be called a single time when recording starts	user-settable
StopFcn	Name of or handle to the function to be called a single time when recording stops	user-settable
NumberOfBuffers	Number of buffers used for recording (You should adjust this only if you have skips, dropouts, etc. in your recording.)	user-settable
BufferLength	Length in seconds of buffer (You should adjust this only if you have skips, dropouts, etc. in your recording.)	user-settable
Tag	User-specified object label string	user-settable

Examples

Example 1

Using a microphone, record 3.5 seconds of 44.1-kHz, 16-bit, stereo data, and then return the data to the MATLAB workspace as a double array.

• recorder = audiorecorder(44100,16,2);
  recordblocking(recorder,3.5);
  audioarray = getaudiodata(recorder);
  

Example 2

Using a microphone, record 8-bit, 22-kHz mono data, play it back, record again and return the data to the MATLAB workspace as a uint8 array.

• micrecorder = audiorecorder(22050,8,1);
  record(micrecorder);
  % Now, speak into microphone
  
  stop(micrecorder);
  speechplayer = play(micrecorder);
  % Now, listen to the recording
  
  stop(speechplayer);
  speechdata = getaudiodata(micrecorder, 'uint8');
  

Remarks

The current implementation of AudioRecorder is not intended for long, high sample rate recording because it uses system memory for storage and does not use disk buffering. When large recordings are attempted, MATLAB performance may degrade.