audioplayer

Object for playing audio

Description

Use an audioplayer object to play audio data. The object contains properties that enable additional flexibility during playback. For example, you can pause, resume, or define callbacks using the audioplayer object functions.

Creation

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 the audio player 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 by ID for output.

Input Arguments

Y — Audio signal

vector | array

Audio signal, specified as a vector or two-dimensional array of numeric data.

The value range of the input sample depends on the data type.

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

Data Types: single | double | int8 | int16 | uint8

Fs — Sampling frequency

numeric scalar

Sampling frequency in hertz (Hz), specified as a numeric scalar.

Valid values of the sampling rate 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 hertz.

Data Types: single | double

nBits — Bits per sample

16 (default) | 8 | 24

Bits per sample, specified as 8, 16, or 24.

Specify nBits only when the signal Y contains floating-point values. Valid values of nBits depend on the audio hardware. For example, depending on your audio hardware, nBits can be one of these values: 8, 16, or 24.

ID — Device identifier

-1 (default) | integer

Device identifier, specified as an integer.

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

recorder — Audio recorder object

audiorecorder object

Audio recorder object, specified as an audiorecorder object. Use the audiorecorder function to create the object.

Properties

BitsPerSample — Bits per sample

positive integer

This property is read-only.

Bits per sample, returned as a positive integer.

CurrentSample — Sample currently playing

positive integer

This property is read-only.

Sample currently playing on the audio output device, returned as a positive integer.

If the device is not playing, then CurrentSample is the next sample to play using the play or resume methods.

DeviceID — Audio device identifier

integer

This property is read-only.

Audio device identifier, returned as an integer.

NumChannels — Number of audio channels

1 | 2

This property is read-only.

Number of audio channels, returned as 1 or 2.

Running — Audio player status

on | off

This property is read-only.

Audio player status, returned as on or off.

SampleRate — Sampling frequency

numeric scalar

Sampling frequency in hertz (Hz), returned as a numeric scalar.

To set the SampleRate, use the Fs input argument when constructing the audioplayer object.

TotalSamples — Total length of audio data

integer

This property is read-only.

Total length of the audio data in samples, returned as an integer.

Tag — Label

character vector

Label, specified as a character vector.

Type — Object class name

'audioplayer'

This property is read-only.

Object class name, returned as 'audioplayer'.

UserData — User-defined data

[] (default) | any data type

User-defined data, specified as a value of any data type. Use this property to store any additional data with the object.

StartFcn — Function to execute at start

character vector | string scalar | function handle

Function to execute at start of playback, specified as a character vector or string scalar containing the name of the function, or a function handle.

The first two inputs to your callback function must be the audioplayer object and an event structure. For more information, see callback functions.

StopFcn — Function to execute at end

character vector | string scalar | function handle

Function to execute at the end of playback, specified as a character vector or string scalar containing the name of the function, or a function handle.

The first two inputs to your callback function must be the audioplayer object and an event structure. For more information, see callback functions.

TimerFcn — Function to execute repeatedly

character vector | string scalar | function handle

Function to execute repeatedly during playback, specified as a character vector or string scalar containing the name of the function, or a function handle. To specify time intervals for the repetitions, use the TimerPeriod property.

The first two inputs to your callback function must be the audioplayer object and an event structure. For more information, see callback functions.

TimerPeriod — Timer period

0.05 (default) | numeric scalar

Timer period, specified as numeric scalar.

Timer period is the time in seconds between TimerFcn callbacks.

Object Functions

get	Query property values for audioplayer object
isplaying	Determine if playback is in progress
pause	Pause playback or recording
play	Play audio from audioplayer object
playblocking	Play audio from audioplayer object, hold control until playback completes
resume	Resume playback or recording from paused state
set	Set property values for audioplayer object
stop	Stop playback or recording

Examples

Play Audio File

Load and play a sample audio file.

Load handel.mat into the workspace. The file contains a sample audio data array y and the sampling rate Fs.

load('handel.mat')
whos y Fs

  Name          Size             Bytes  Class     Attributes

  Fs            1x1                  8  double              
  y         73113x1             584904  double              

Create an audioplayer object to play the file.

player = audioplayer(y,Fs);

Play the audio object on the default audio device.

play(player);

Record and Play Audio Sample

Record audio data from a microphone and then play the recorded audio.

Create an audiorecorder object with default property values.

recObj = audiorecorder;

Record a five second sample of your speech with your microphone.

disp('Start speaking.')

Start speaking.

recordblocking(recObj,5);
disp('End of Recording.');

End of Recording.

Create an audio player object from the recording and then play the recorded sample.

playerObj = audioplayer(recObj);
play(playerObj);

Limitations

• These limitations apply when using audioplayer in MATLAB Online™:

  • You cannot create an audioplayer object from a recorder object.

  • You cannot change the sample rate of an existing audioplayer object.

  • audioplayer ignores nBits. Instead, it plays audio data using the default number of bits per sample of the output audio device.

More About

Security Considerations When Using MATLAB Online

When using audioplayer in MATLAB Online, certain features and settings help you keep control of your privacy.

To reduce the likelihood of unwanted applications using your microphone, turn off automatic access to your audio device. You can change these settings at any time. After granting permission to a website once, your browser may be able to access your microphone automatically for that site on future visits. Use the browser settings for Google Chrome to revoke access for specific sites after you have initially allowed access.

You can also access the MATLAB Online website using the private browsing mode in Google Chrome. When you do this, Chrome™ automatically asks you for permission to access your microphone every time you open the MATLAB Online site and run audioplayer, regardless of your browser settings.

Tips

• Audio playback in MATLAB Online is supported in Google Chrome™.