audioplayer (MATLAB Functions)

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.

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

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

See Also

audiorecorder, sound, wavplay, wavwrite, wavread, get, set, methods

audiodevinfo audiorecorder