audioplayer

Create audio player object

Syntax

player = audioplayer(Y, Fs) player = audioplayer(Y, Fs, nBits) player = audioplayer(Y, Fs, nBits, ID) player = audioplayer(R) player = audioplayer(R, ID)

Description

Note To use all of the features of the audio player object, 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.

player = audioplayer(Y, Fs) creates an audio player object for signal Y, using sample rate Fs. The function returns player, a handle to the audio player object. The audio player object supports methods and properties that you can use to control how the audio data is played.

The input signal Y can be a vector or two-dimensional array containing single, double, int8, uint8, or int16 MATLAB data types. 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.

player = audioplayer(Y, Fs, nBits) creates an audio player object and uses nBits bits per sample for floating point signal Y. Valid values for nBits are 8, 16, and 24 on Windows, 8 and 16 on UNIX. The default number of bits per sample for floating point signals is 16.

player = audioplayer(Y, Fs, nBits, ID) creates an audio player object using audio device identifier ID for output. If ID equals -1, the default output device will be used. This option is only available on Windows.

player = audioplayer(R) creates an audio player object using audio recorder object R.

player = audioplayer(R, ID) creates an audio player object from audio recorder object R using audio device identifier ID for output. This option is only available on Windows.

Remarks

The value range of the input sample depends on the MATLAB data type. The following table lists these ranges.

Data Type	Input Sample Value Range
`int8`	-128 to 127
`uint8`	0 to 255
`int16`	-32768 to 32767
`single`	-1 to 1
`double`	-1 to 1

Example

Load a sample audio file of Handel's Hallelujah Chorus, create an audio player object, and play back only the first three seconds. y 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

Methods

After you create an audio player object, you can use the methods listed below on that object. player represents a handle to the audio player object.

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

Properties

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

set(player, 'property1', value,'property2',value,...)

To view a read-only property,

get(player,'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 player object callbacks, `eventStruct (event)` is currently empty (`[]`).
`TimerFcn`	Handle to a user-specified callback function that is executed repeatedly (at `TimerPeriod` intervals) during playback.	User-settable
`TimerPeriod`	Time, in seconds, between `TimerFcn` callbacks.	User-settable
`StartFcn`	Handle to a user-specified callback function that is executed once when playback starts.	User-settable
`StopFcn`	Handle to a user-specified callback function that is executed once when playback stops.	User-settable