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);