audioplayer

Create object for playing audio

Syntax

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

Description

player = audioplayer(Y,Fs) creates an audioplayer object for signal Y, using sample rate Fs. The function returns a handle to the audioplayer object, player.

player = audioplayer(Y,Fs,nBits) uses nBits bits per sample for signal Y.

player = audioplayer(Y,Fs,nBits,ID) uses the audio device identified by ID for output.

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

player = audioplayer(recorder,ID) creates an object from recorder that uses the audio device identified byID for output.

Input Arguments

Y

Audio signal represented by a vector or two-dimensional array containing single, double, int8, uint8, or int16 values.

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

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

Fs

Sampling rate in Hz. Valid values depend on both the sample rates permitted by MATLAB^® and the specific audio hardware on your system. MATLAB has a hard restriction of 1000 Hz <= Fs <= 384000 Hz, although further hardware-dependent restrictions apply. Typical values supported by most sound cards are 8000, 11025, 22050, 44100, 48000, and 96000 Hz.

nBits

Bits per sample. Specify only when signal Y is represented by floating-point values. Valid values depend on the audio hardware installed: 8, 16, or 24.

Default: 16

ID

Device identifier. To obtain the ID of a device, use the audiodevinfo function.

Default: -1 (default device)

recorder

Audio recorder object created by audiorecorder.

Methods

Note: When calling any method, include the audioplayer object name using function syntax, such as stop(player).

`get`	Query properties of `audioplayer` object.
`isplaying`	Query whether playback is in progress: returns `true` or `false`.
`pause`	Pause playback.
`play`	Play audio from beginning to end.
`playblocking`	Play, and do not return control until playback completes.
`resume`	Restart playback from paused position.
`set`	Set properties of `audioplayer` object.
`stop`	Stop playback.

See the reference pages for get, play, playblocking, and set for additional syntax options.

Properties

`BitsPerSample`	Number of bits per sample. (Read-only)
`CurrentSample`	Current sample that the audio output device is playing. If the device is not playing, `CurrentSample` is the next sample to play with `play` or `resume`. (Read-only)
`DeviceID`	Identifier for audio device. (Read-only)
`NumberOfChannels`	Number of audio channels. (Read-only)
`Running`	Status of the audio player: `'on'` or `'off'`. (Read-only)
`SampleRate`	Sampling frequency in Hz.
`TotalSamples`	Total length of the audio data in samples. (Read-only)
`Tag`	Label of the object.
`Type`	Name of the class: `'audioplayer'`. (Read-only)
`UserData`	Any type of additional data to store with the object.

The following four properties apply to callback functions. The first two inputs to your callback function must be the audioplayer object and an event structure.

`StartFcn`	Function to execute one time when playback starts.
`StopFcn`	Function to execute one time when playback stops.
`TimerFcn`	Function to execute repeatedly during playback. To specify time intervals for the repetitions, use the `TimerPeriod` property.
`TimerPeriod`	Time in seconds between `TimerFcn` callbacks. Default: `.05`

Examples

Load and play a sample audio file of Handel's "Hallelujah Chorus:"

load handel;
player = audioplayer(y, Fs);
play(player);

Documentation

audioplayer

Syntax

Description

Input Arguments

Methods

Properties

Examples

More About

See Also

Introduced before R2006a

MATLAB Documentation

Other Documentation

Support