audioplayer - Object for playing audio - MATLAB (original) (raw)
Description
Use an audioplayer object to play audio data. Theaudioplayer object contains properties that enable additional flexibility during playback. For example, you can pause, resume, or define callbacks using theaudioplayer object functions.
Creation
Syntax
Description
`player` = audioplayer([Y](#mw%5F08ad7041-b03f-44c3-85e9-d5a350cbdb2a),[Fs](#mw%5F26b827a1-15a2-4c90-ad32-b25e8be37bba)) creates an audioplayer object for signal Y, using sample rate Fs. The function returns the audio player object,player.
`player` = audioplayer([Y](#mw%5F08ad7041-b03f-44c3-85e9-d5a350cbdb2a),[Fs](#mw%5F26b827a1-15a2-4c90-ad32-b25e8be37bba),[nBits](#mw%5F9ff795d8-52ec-43a6-ac74-3d3b6a6645c1)) uses nBits bits per sample for signalY.
`player` = audioplayer([Y](#mw%5F08ad7041-b03f-44c3-85e9-d5a350cbdb2a),[Fs](#mw%5F26b827a1-15a2-4c90-ad32-b25e8be37bba),[nBits](#mw%5F9ff795d8-52ec-43a6-ac74-3d3b6a6645c1),[ID](#f10-479315%5Fsep%5Fmw%5Fd37577a6-deb4-41dc-9dfe-3ae8751186bc)) uses the audio device identified by ID for output.
`player` = audioplayer([recorder](#f10-479315%5Fsep%5Fmw%5Fee586f8e-6f0f-4796-8c17-7c19c3d5bc54)) creates an audioplayer object using audio recorder objectrecorder.
`player` = audioplayer([recorder](#f10-479315%5Fsep%5Fmw%5Fee586f8e-6f0f-4796-8c17-7c19c3d5bc54),[ID](#f10-479315%5Fsep%5Fmw%5Fd37577a6-deb4-41dc-9dfe-3ae8751186bc)) 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 samples depends on the data type.
| Data Type | Sample Value Range |
|---|---|
| int8 | -128 to 127 |
| uint8 | 0 to 255 |
| int16 | -32,768 to 32,767 |
| single ordouble | -1 to 1 |
Data Types: single | double | int8 | int16 | uint8
Fs — Sample rate
positive scalar
Sample rate in hertz (Hz), specified as a positive scalar.
Valid values of the sample rate depend on the audio hardware of your system. Typical sample rates supported by most setups are 8000, 11,025, 22,050, 44,100, 48,000, 96,000, and 192,000 Hz.
This argument sets the SampleRate property.
Data Types: single | double
nBits — Bits per sample
16 (default) | 8 | 24
Bits per sample, specified as 16, 8, or24. Specify nBits only when the signal contains floating-point values.
Valid values of nBits depend on the audio hardware of your system.
This argument sets the BitsPerSample property.
ID — Audio device identifier
-1 (default) | integer
Audio device identifier, specified as an integer.
To obtain the ID of a device, use the audiodevinfo function.
This argument sets the DeviceID property.
recorder — Audio recorder object
audiorecorder object
Audio recorder object, specified as an audiorecorder object. Use theaudiorecorder function to create the object.
Properties
SampleRate — Sample rate
positive scalar
Sample rate in hertz (Hz), specified as a positive scalar.
To set the SampleRate property initially, use theFs input argument when creating the audioplayer object. After creating the object, you can modify its SampleRate property.
BitsPerSample — Bits per sample
8 | 16 | 24
This property is read-only.
Bits per sample, returned as 8, 16, or24.
To set the BitsPerSample property, use thenBits input argument when creating theaudioplayer object.
NumChannels — Number of audio channels
1 | 2
This property is read-only.
Number of audio channels, returned as 1 (mono) or2 (stereo).
DeviceID — Audio device identifier
integer
This property is read-only.
Audio device identifier, returned as an integer.
To set the DeviceID property, use the ID input argument when creating the audioplayer object.
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 method.
TotalSamples — Total length of audio data
nonnegative integer
This property is read-only.
Total length of the audio data in samples, returned as a nonnegative integer.
Running — Audio player status
'off' (default) | 'on'
This property is read-only.
Audio player status, returned as 'off' or'on'.
StartFcn — Function to execute at start
character vector | function handle
Function to execute at the start of playback, specified as a character vector containing the name of the function, or a function handle.
The first two inputs to your callback function must be theaudioplayer object and an event structure. For more information, see Timer Callback Functions.
StopFcn — Function to execute at end
character vector | function handle
Function to execute at the end of playback, specified as a character vector containing the name of the function, or a function handle.
The first two inputs to your callback function must be theaudioplayer object and an event structure. For more information, see Timer Callback Functions.
TimerFcn — Function to execute repeatedly
character vector | function handle
Function to execute repeatedly during playback, specified as a character vector 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 theaudioplayer object and an event structure. For more information, see Timer Callback Functions.
TimerPeriod — Timer period
0.05 (default) | positive scalar
Timer period, specified as a positive scalar.
TimerPeriod is the time in seconds between TimerFcn callbacks.
Tag — Label
string scalar | character vector
Label, specified as a string scalar or character vector.
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.
Type — Object class name
'audioplayer' (default)
This property is read-only.
Object class name, returned as 'audioplayer'.
Object Functions
| get | Query property values for audioplayer object |
|---|---|
| isplaying | Determine if playback is in progress |
| pause | Pause playback of audioplayer object or recording ofaudiorecorder object |
| play | Play audio from audioplayer object |
| playblocking | Play audio from audioplayer object; hold control until playback completes |
| resume | Resume playback of audioplayer object or recording ofaudiorecorder object from paused state |
| set | Set property values for audioplayer object |
| stop | Stop playback of audioplayer object or recording ofaudiorecorder object |
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.
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.
Record a 5-second sample of your voice with your microphone.
recDuration = 5; % record for 5 seconds recordblocking(recObj,recDuration); disp("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
audioplayerin MATLAB® Online™ or MATLAB Web App Server™:- You cannot create an
audioplayerobject from anaudiorecorderobject. - You cannot change the sample rate of an existing
audioplayerobject. audioplayerignoresnBits. Instead, it plays audio data using the default number of bits per sample of the output audio device.- Valid values of the sample rate
Fsmay not be the same as they are in MATLAB Desktop.
- You cannot create an
Tips
- The
audioplayerfunction supports sound devices on all Windows® and most UNIX® platforms. audioplayerin MATLAB Online and MATLAB Web App Server is supported in Google Chrome®.- Note
Security Considerations When Using MATLAB Online or MATLAB Web App Server: When usingaudioplayerin MATLAB Online or MATLAB Web App Server, 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 forGoogle Chrome to revoke access for specific sites after you have initially allowed access.
You can also access the MATLAB Online website or MATLAB Web App Server using the private browsing mode in Google Chrome. When you do this, Chrome® automatically asks you for permission every time it tries to access your microphone, regardless of your browser settings.
Version History
Introduced before R2006a