Titanium SDK # Titanium.Media.AudioPlayer
An audio player object used for streaming audio to the device, and low-level control of the audio playback.
0.9
0.9
9.2.0# Overview
On Android, when you are done playing a given audio file, you must call the Titanium.Media.AudioPlayer.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 (opens new window) for a more modern and performant audio playback.
Use the Titanium.Media.createAudioPlayer method to create an audio player.
# 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();
# Properties
# allowBackground CREATION ONLY
0.9Boolean to indicate if audio should continue playing even if the associated Android Titanium.Android.Activity is paused.
Setting allowBackground to true allows the audio to continue playing, for
example, if the application is in the background.
Default: false
# allowsExternalPlayback
7.5.0 9.2.0Indicates whether the player allows switching to "external playback" mode.
Default: true
# apiName READONLY
3.2.0 3.2.0 9.2.0The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button
returns Ti.UI.Button.
# audioFocus CREATION ONLY
0.9Focuses 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.
Default: false
# audioType
6.2.0Changes the audio-stream-type.
Default: Titanium.Media.AudioPlayer.AUDIO_TYPE_MEDIA
# bubbleParent
3.0.0 3.0.0 9.2.0Indicates 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.
Default: true
# bufferSize
0.9 9.2.0Size 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 READONLY
3.3.0 3.3.0 9.2.0Estimated duration in milliseconds of the file being played.
May return 0 when playing a live stream.
# externalPlaybackActive READONLY
7.5.0 9.2.0Indicates whether the player is currently playing video in "external playback" mode.
# idle READONLY
0.9 9.2.0Boolean 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
3.6.0The 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
7.5.0 7.5.0 9.2.0Indicates whether or not audio output of the player is muted.
Only affects audio muting for the player instance and not for the device.
# playing READONLY
0.9 0.9 9.2.0Boolean indicating if audio is currently playing.
Returns false if playback is stopped or paused.
# progress READONLY
0.9 9.2.0Current playback progress, in milliseconds.
Returns zero if bitRate has not yet been detected.
# rate
7.5.0 9.2.0Indicates 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 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
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.
Default: 0
# state READONLY
0.9 9.2.0Current state of playback, specified using one of the STATE constants defined on this object.
# volume
2.1.0 2.1.0 9.2.0Volume 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
appMusicPlayer and set the audioSessionCategory property
to either AUDIO_SESSION_CATEGORY_AMBIENT,
AUDIO_SESSION_CATEGORY_SOLO_AMBIENT,
or AUDIO_SESSION_CATEGORY_PLAYBACK.
# waiting READONLY
0.9 9.2.0Boolean 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
0.9 0.9 9.2.0Adds the specified callback as an event listener for the named event.
Parameters
| Name | Type | Description |
|---|---|---|
name | String | Name of the event. |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. |
Returns
- Type
- void
# applyProperties
3.0.0 3.0.0 9.2.0Applies 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.
Parameters
| Name | Type | Description |
|---|---|---|
props | Dictionary | A dictionary of properties to apply. |
Returns
- Type
- void
# fireEvent
0.9 0.9 9.2.0Fires a synthesized event to any registered listeners.
Parameters
| Name | Type | Description |
|---|---|---|
name | String | Name of the event. |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. |
Returns
- Type
- void
# getAudioSessionId DEPRECATED
5.4.0DEPRECATED SINCE 10.0.0
Use the audioSessionId property instead
Returns the audio session id.
Returns
- Type
- Number
# getPaused DEPRECATED
0.9 9.2.0DEPRECATED SINCE 7.5.0
Use the cross-platform API paused property instead.
Returns the value of the paused property.
Returns
- Type
- Boolean
# getPlaying DEPRECATED
0.9 9.2.0DEPRECATED SINCE 7.5.0
Use the cross-platform API playing property instead.
Returns the value of the playing property.
Returns
- Type
- Boolean
# isPaused DEPRECATED
0.9DEPRECATED SINCE 7.5.0
Use the cross-platform API paused property instead.
Returns the value of the paused property.
Returns
- Type
- Boolean
# isPlaying DEPRECATED
0.9DEPRECATED SINCE 7.5.0
Use the cross-platform API playing property instead.
Returns the value of the playing property.
Returns
- Type
- Boolean
# pause
0.9 0.9 9.2.0Pauses 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 start on a paused stream resumes play.
Returns
- Type
- void
# play DEPRECATED
0.9DEPRECATED SINCE 7.5.0
Use the cross-platform API start instead.
Starts or resumes audio playback.
This method is identical to .
Returns
- Type
- void
# release
0.9 7.5.0 9.2.0Stops 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.
Returns
- Type
- void
# removeEventListener
0.9 0.9 9.2.0Removes 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);
Parameters
| Name | Type | Description |
|---|---|---|
name | String | Name of the event. |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to |
Returns
- Type
- void
# restart
7.5.0 7.5.0 9.2.0Restarts (stops and stars) audio playback.
Returns
- Type
- void
# seekToTime
7.5.0 9.2.0Moves 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.
Parameters
| Name | Type | Description |
|---|---|---|
time | Number | The time in milliseconds to seek to. |
Returns
- Type
- void
# setPaused DEPRECATED
0.9 9.2.0DEPRECATED SINCE 7.5.0
Use the cross-platform API pause instead.
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 pause and start methods instead.
Parameters
| Name | Type | Description |
|---|---|---|
paused | Boolean | Pass |
Returns
- Type
- void
# Events
# change
0.9 0.9 9.2.0Fired 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.
Properties
| Name | Type | Description |
|---|---|---|
| state | Number | Current state of playback. |
| description | Number | Text description of the state of playback. |
| source | Object | Source object that fired the event. |
| type | String | Name of the event fired. |
| bubbles | Boolean | True if the event will try to bubble up if possible. |
| cancelBubble | Boolean | Set to true to stop the event from bubbling. |
# complete
0.9 7.5.0 9.2.0Fired when the audio has finished playing.
Properties
| Name | Type | Description |
|---|---|---|
| success | Boolean | Indicates if the sound was played successfully.
Returns |
| error | String | Error message, if any returned. Will be undefined if |
| code | Number | Error code.
Error code will be 0 if |
| source | Object | Source object that fired the event. |
| type | String | Name of the event fired. |
| bubbles | Boolean | True if the event will try to bubble up if possible. |
| cancelBubble | Boolean | Set to true to stop the event from bubbling. |
# metadata
7.5.0 9.2.0Fired 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.
Properties
| Name | Type | Description |
|---|---|---|
| items | Array<TiMetadataItemType> | An array of metadata items containing relevant information about the current media item. |
| source | Object | Source object that fired the event. |
| type | String | Name of the event fired. |
| bubbles | Boolean | True if the event will try to bubble up if possible. |
| cancelBubble | Boolean | Set to true to stop the event from bubbling. |
# error
4.1.0 4.1.0 9.2.0Fired when there's an error.
Properties
| Name | Type | Description |
|---|---|---|
| error | String | Error message. |
| code | Number | Error code. Different between android and iOS. |
| source | Object | Source object that fired the event. |
| type | String | Name of the event fired. |
| bubbles | Boolean | True if the event will try to bubble up if possible. |
| cancelBubble | Boolean | Set to true to stop the event from bubbling. |
# progress
0.9 0.9 9.2.0Fired once per second with the current progress during playback.
Properties
| Name | Type | Description |
|---|---|---|
| progress | Number | Current progress, in milliseconds. |
| source | Object | Source object that fired the event. |
| type | String | Name of the event fired. |
| bubbles | Boolean | True if the event will try to bubble up if possible. |
| cancelBubble | Boolean | Set to true to stop the event from bubbling. |
# seek
0.9 9.2.0Fired once the seek method completes.
Properties
| Name | Type | Description |
|---|---|---|
| finished | Boolean | The event for any prior seek request that is still in process will be invoked
immediately with the |
| source | Object | Source object that fired the event. |
| type | String | Name of the event fired. |
| bubbles | Boolean | True if the event will try to bubble up if possible. |
| cancelBubble | Boolean | Set to true to stop the event from bubbling. |
# Constants
# AUDIO_TYPE_ALARM
6.2.0Used to identify the volume of audio streams for alarms.
# AUDIO_TYPE_MEDIA
6.2.0Used to identify the volume of audio streams for media playback.
# AUDIO_TYPE_NOTIFICATION
6.2.0Used to identify the volume of audio streams for notifications.
# AUDIO_TYPE_RING
6.2.0Used to identify the volume of audio streams for the phone ring.
# AUDIO_TYPE_SIGNALLING
6.2.0Used to identify the volume of audio streams for DTMF tones or beeps.
# AUDIO_TYPE_VOICE
6.2.0Used to identify the volume of audio streams for voice calls.
# STATE_BUFFERING DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_BUFFERING instead.
Audio data is being buffered from the network.
# STATE_INITIALIZED DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_INITIALIZED instead.
Audio playback is being initialized.
# STATE_PAUSED DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_PAUSED instead.
Playback is paused.
# STATE_PLAYING DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_PLAYING instead.
Audio playback is active.
# STATE_STARTING DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_STARTING instead.
Audio playback is starting.
# STATE_STOPPED DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_STOPPED instead.
Audio playback is stopped.
# STATE_STOPPING DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_STOPPING instead.
Audio playback is stopping.
# STATE_WAITING_FOR_DATA DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use AUDIO_STATE_WAITING_FOR_DATA instead.
Player is waiting for audio data from the network.
# STATE_WAITING_FOR_QUEUE DEPRECATED
0.9 0.9 9.2.0DEPRECATED SINCE 7.5.0
Use Titanium.Media.AUDIO_STATE_WAITING_FOR_QUEUE instead.
Player is waiting for audio data to fill the queue.