Titanium.Media.AudioPlayer
An audio player object used for streaming audio to the device, and low-level control of the audio playback.
On Android, when you are done playing a given audio file, you must call the release method to stop buffering audio data and release associated system resources. Since 7.5.0, this method is available on iOS as well and will release all audio-player related resources. After this method has been called, the object should not be accessed anymore.
On iOS, you can control how the audio stream interacts with other system sounds by setting Titanium.Media.audioSessionCategory. Since Titanium 7.5.0, this API uses the AVPlayer API for a more modern and performant audio playback.
Use the Titanium.Media.createAudioPlayer method to create an audio player.
Extends: Titanium.Proxy · Since: 0.9 · Platforms: android, iphone, ipad, macos
Properties #
allowBackground#
Type: Boolean
Boolean to indicate if audio should continue playing even if the associated
Android Activity is paused.
Setting allowBackground to true allows the audio to continue playing, for
example, if the application is in the background.
allowsExternalPlayback#
Type: Boolean
Indicates whether the player allows switching to "external playback" mode.
apiName#
Type: String
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.
AUDIO_TYPE_SIGNALLING#
Type: Number
Used to identify the volume of audio streams for DTMF tones or beeps.
audioFocus#
Type: Boolean
Focuses on the current audio player and stops other audio playing.
If true then all other audio sources will be stopped
when Titanium.AudioPlayer is started or resumed.
bubbleParent#
Type: Boolean
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often
established by the add() method. For example, for a button added to a window, a
click event on the button would bubble up to the window. Other common parents are
table sections to their rows, table views to their sections, and scrollable views
to their views. Set this property to false to disable the bubbling to the proxy's parent.
bufferSize#
Type: Number
Size of the buffer used for streaming, in milliseconds.
Prior to Titanium 7.5.0, this property was set in bytes. Since the internal iOS
API moved to the more modern AVPlayer, this property now works with milliseconds instead.
duration#
Type: Number
Estimated duration in milliseconds of the file being played.
May return 0 when playing a live stream.
externalPlaybackActive#
Type: Boolean
Indicates whether the player is currently playing video in "external playback" mode.
idle#
Type: Boolean
Boolean indicating if the player is idle.
true if the player is in the initialized state: that is, not playing, paused,
or waiting for data.
lifecycleContainer#
Type: Titanium.UI.Window, Titanium.UI.TabGroup
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.
muted#
Type: Boolean
Indicates whether or not audio output of the player is muted.
Only affects audio muting for the player instance and not for the device.
playing#
Type: Boolean
Boolean indicating if audio is currently playing.
Returns false if playback is stopped or paused.
progress#
Type: Number
Current playback progress, in milliseconds.
Returns zero if bitRate has not yet been detected.
rate#
Type: Number
Indicates the desired rate of playback; 0.0 means "paused", 1.0 indicates a
desire to play at the natural rate of the current item. In addition, 2.0
would mean that the audio plays twice as fast.
Setting the value of rate to 0.0 pauses playback, causing the value of
the state property change to Titanium.Media.AUDIO_STATE_PAUSED.
Setting the rate to a non-zero value causes the value of the state property
to become either Titanium.Media.AUDIO_STATE_WAITING_FOR_QUEUE or
Titanium.Media.AUDIO_STATE_PLAYING, depending on whether sufficient
media data has been buffered for playback to occur and whether the player's
default behavior of waiting in order to minimize stalling is permitted.
state#
Type: Number
Current state of playback, specified using one of the STATE constants defined on this object.
STATE_WAITING_FOR_QUEUE (deprecated)#
Type: Number
Player is waiting for audio data to fill the queue.
volume#
Type: Number
Volume of the audio, from 0.0 (muted) to 1.0 (loudest).
This setting controls the volume of the sound relative to the overall
volume setting for the device.
On iOS, to adjust the volume of the device, set the volume property of
Titanium.Media.appMusicPlayer and set the Titanium.Media.audioSessionCategory property
to either Titanium.Media.AUDIO_SESSION_CATEGORY_AMBIENT,
Titanium.Media.AUDIO_SESSION_CATEGORY_SOLO_AMBIENT,
or Titanium.Media.AUDIO_SESSION_CATEGORY_PLAYBACK.
waiting#
Type: Boolean
Boolean indicating if the playback is waiting for audio data from the network.
This property is true if the player is in any of the waiting states, including
buffering, starting, waiting for data, and waiting for queue.
Methods #
addEventListener #
Adds the specified callback as an event listener for the named event.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. | No |
applyProperties #
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that
myproxy[key] = value.
| Name | Type | Summary | Optional |
|---|---|---|---|
props | Dictionary | A dictionary of properties to apply. | No |
fireEvent #
Fires a synthesized event to any registered listeners.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. | Yes |
pause #
Pauses audio playback.
On iOS, the pause call operates as a toggle. If the stream is already paused,
calling pause again resumes playing the stream.
On Android, the pause call does nothing if the stream is already paused.
On both platforms, calling Titanium.Media.AudioPlayer.start on a paused
stream resumes play.
release #
Stops buffering audio data and releases audio resources.
On Android, this method should be called when you are done streaming a given
audio object, to release underlying resources, including buffered data.
On iOS, this method can be called for parity to release the current player
instance and it's observers. Note: If you are listening to the progress event,
you should remove and re-add the event listener.
removeEventListener #
Removes the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function
in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to addEventListener. | No |
restart #
Restarts (stops and stars) audio playback.
seekToTime #
Moves the playback cursor and invokes the specified block when the seek
operation has either been completed or been interrupted.
Use this method to seek to a specified time for the current player item and
to be notified by the seek event when the seek operation is complete.
| Name | Type | Summary | Optional |
|---|---|---|---|
time | Number | The time in milliseconds to seek to. | No |
setPaused #
Sets the value of the paused property.
On iOS, this method can be used to pause and unpause playback. For portability,
it is preferable to use the Titanium.Media.AudioPlayer.pause and
Titanium.Media.AudioPlayer.start methods instead.
| Name | Type | Summary | Optional |
|---|---|---|---|
paused | Boolean | Pass true to pause the current playback temporarily, false to unpause it. | No |
start #
Starts or resumes audio playback.
stateDescription #
Converts a state value into a text description
suitable for display.
| Name | Type | Summary | Optional |
|---|---|---|---|
state | Number | State value to convert. | No |
Returns: String
stop #
Stops audio playback.
Events #
change #
Fired when the state of the playback changes.
This event can be generated by programmatic events, such as pausing or stopping the audio,
and also by external events, such as the current state of network buffering.
| Name | Type | Summary |
|---|---|---|
state | Number | Current state of playback. |
description | Number | Text description of the state of playback. |
complete #
Fired when the audio has finished playing.
| Name | Type | Summary |
|---|---|---|
success | Boolean | Indicates if the sound was played successfully. Returns true if request succeeded, false otherwise. |
error | String | Error message, if any returned. Will be undefined if success is true. |
code | Number | Error code. Error code will be 0 if success is true, nonzero otherwise. If the errorwas generated by the operating system, that system's error value is used. Otherwise, this value will be -1. |
error #
Fired when there's an error.
| Name | Type | Summary |
|---|---|---|
error | String | Error message. |
code | Number | Error code. Different between Android and iOS. |
metadata #
Fired when the timed metadata was encountered most recently within the media as it plays.
Use this event to receive meta information about real time streams and buffers, for example
the title of an active radio stream. Read more about timed metadata in the Apple docs.
| Name | Type | Summary |
|---|---|---|
items | Array<TiMetadataItemType> | An array of metadata items containing relevant information about the current media item. |
progress #
Fired once per second with the current progress during playback.
| Name | Type | Summary |
|---|---|---|
progress | Number | Current progress, in milliseconds. |
seek #
Fired once the seekToTime method completes.
| Name | Type | Summary |
|---|---|---|
finished | Boolean | The event for any prior seek request that is still in process will be invoked immediately with the finished parameter set to false.If the new request completes without being interrupted by another seek request or by any other operation this event will be invoked with the finished parameter set to true. |
Examples #
Audio Streaming
The following example demonstrates using the `AudioPlayer` object to stream audio.
var win = Ti.UI.createWindow({
title: 'Audio Test',
backgroundColor: '#fff',
layout: 'vertical'
});
var startStopButton = Ti.UI.createButton({
title: 'Start/Stop Streaming',
top: 10,
width: 200,
height: 40
});
var pauseResumeButton = Ti.UI.createButton({
title: 'Pause/Resume Streaming',
top: 10,
width: 200,
height: 40,
enabled: false
});
win.add(startStopButton);
win.add(pauseResumeButton);
// allowBackground: true on Android allows the
// player to keep playing when the app is in the
// background.
var audioPlayer = Ti.Media.createAudioPlayer({
url: 'www.example.com/podcast.mp3',
allowBackground: true
});
startStopButton.addEventListener('click', function() {
// When paused, playing returns false.
// If both are false, playback is stopped.
if (audioPlayer.playing || audioPlayer.paused) {
audioPlayer.stop();
pauseResumeButton.enabled = false;
audioPlayer.release();
} else {
audioPlayer.start();
pauseResumeButton.enabled = true;
}
});
pauseResumeButton.addEventListener('click', function() {
if (audioPlayer.paused) {
audioPlayer.start();
} else {
audioPlayer.pause();
}
});
audioPlayer.addEventListener('progress', function(e) {
Ti.API.info('Time Played: ' + Math.round(e.progress) + ' milliseconds');
});
audioPlayer.addEventListener('change', function(e) {
Ti.API.info('State: ' + e.description + ' (' + e.state + ')');
});
win.addEventListener('close', function() {
audioPlayer.stop();
audioPlayer.release();
});
win.open();