Learn more about MATLAB

audioplayer - Create audioplayer 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

Requirements   To use all of the features of the audioplayer object, ensure that your system has 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 audioplayer object for signal Y, using sample rate Fs. The function returns player, a handle to the audioplayer object. The audioplayer 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 audioplayer object and uses nBits bits per sample for floating-point signal Y. Valid values for nBits are 8, 16, and 24 on Windows operating systems, and 8 and 16 on UNIX^® operating systems. The default number of bits per sample for floating-point signals is 16.

player = audioplayer(Y, Fs, nBits, ID) creates an audioplayer object using audio device identifier ID for output. (You can obtain the ID of a device with the audiodevinfo function.) If ID equals -1, the default output device is used. This option is available only on Windows operating systems.

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

player = audioplayer(R, ID) creates an audioplayer object from audio recorder object R using audio device identifier ID for output. (You can obtain the ID of a device with the audiodevinfo function.) This option is available only on Windows operating systems.

Remarks

Value Range and Data Type

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

Object Scope

When using an audioplayer object inside a function, the scope of the object is limited to the duration of the function. When the function is completed, the object is cleared, so that you cannot access any of its data or callbacks after that point. For example, in this function, play does not block execution, so the function ends immediately after the playing starts, deleting all callbacks and data.

function makePlayer(waveData, Fs, timerCallback, timerPeriod)

% Create an audioplayer object
playObject = audioplayer(waveData, Fs);

% Set callback to be called every timerPeriod seconds
set(playObject, ...
    'TimerFcn', timerCallback, ...
    'TimerPeriod', timerPeriod);

% Start playing
play(playObject);

end

To work around this problem, you can try any of the following:

• Create the audioplayer object outside your function, before calling that function.

• Use playblocking instead of play. This synchronously blocks execution until the waveform is completed. Note, however, that the object exists only during execution of your function.

• Pass the audioplayer object back out of the function to the MATLAB workspace:

  function playObject = makeRecorder(waveData, Fs, ...
                              timerCallback, timerPeriod)

Examples

Load a sample audio file of Handel's Hallelujah Chorus, create an audioplayer object, and play back only the first 3 seconds. y contains the audio samples, and Fs is the sampling rate.

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 audioplayer object, you can use the following methods on that object. player represents a handle to the audioplayer 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 audioplayer 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. You can also specify the values of start and stop 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 audioplayer object player.

Properties

audioplayer objects have the following properties. To specify a user-settable property, use this syntax:

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

To view a read-only property, use this syntax:

get(player,'property')		% Displays 'property' setting.

Property	Description	Type
BitsPerSample	Number of bits per sample.	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
NumberOfChannels	Number of channels.	Read-only
Running	Status of the audio player ('on' or 'off').	Read-only
SampleRate	Sampling frequency in Hz.	User-settable
TotalSamples	Total length, in samples, of the audio data.	Read-only
Tag	User-specified object label string.	User-settable
Type	Name of the object's class.	Read-only
UserData	User data of any type.	User-settable
For information on using the following four properties, see Creating and Executing Callback Functions in the MATLAB documentation. Note that for audioplayer object callbacks, eventStruct(event) is currently empty ([]).
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
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

See Also

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

audiodevinfo

audiorecorder

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS