# Titanium.Media.AudioPlayer

An audio player object used for streaming audio to the device, and low-level control of the audio playback.

Availability
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

Availability
0.9
allowBackground :Boolean

Boolean 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

Availability
7.5.0
9.2.0
allowsExternalPlayback :Boolean

Indicates whether the player allows switching to "external playback" mode.

Default: true


# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :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, Titanium.UI.Button returns Ti.UI.Button.


# audioFocus CREATION ONLY

Availability
0.9
audioFocus :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.

Default: false


# audioSessionId READONLY

Availability
10.0.0
audioSessionId :Number

Returns the audio session id.


# bitRate

Availability
0.9
9.2.0
bitRate :Number

Bit rate of the current playback stream.


# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :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.

Default: true


# bufferSize

Availability
0.9
9.2.0
bufferSize :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 READONLY

Availability
3.3.0
3.3.0
9.2.0
duration :Number

Estimated duration in milliseconds of the file being played.

May return 0 when playing a live stream.


# externalPlaybackActive READONLY

Availability
7.5.0
9.2.0
externalPlaybackActive :Boolean

Indicates whether the player is currently playing video in "external playback" mode.


# idle READONLY

Availability
0.9
9.2.0
idle :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

Availability
3.6.0

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

Availability
7.5.0
7.5.0
9.2.0
muted :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.


# paused

Availability
0.9
0.9
9.2.0
paused :Boolean

Boolean indicating if audio playback is paused.


# playing READONLY

Availability
0.9
0.9
9.2.0
playing :Boolean

Boolean indicating if audio is currently playing.

Returns false if playback is stopped or paused.


# progress READONLY

Availability
0.9
9.2.0
progress :Number

Current playback progress, in milliseconds.

Returns zero if bitRate has not yet been detected.


# rate

Availability
7.5.0
9.2.0
rate :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 AUDIO_STATE_PAUSED. Setting the rate to a non-zero value causes the value of the state property to become either 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


# time

Availability
3.3.0
time :Number

Current playback position of the audio.

Time is reported in milliseconds.


# url

Availability
0.9
0.9
9.2.0
url :String

URL for the audio stream.


# volume

Availability
2.1.0
2.1.0
9.2.0
volume :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 appMusicPlayer and set the audioSessionCategory property to either AUDIO_SESSION_CATEGORY_AMBIENT, AUDIO_SESSION_CATEGORY_SOLO_AMBIENT, or AUDIO_SESSION_CATEGORY_PLAYBACK.


# waiting READONLY

Availability
0.9
9.2.0
waiting :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

Availability
0.9
0.9
9.2.0
addEventListener(name, callback) void

Adds 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

Availability
3.0.0
3.0.0
9.2.0
applyProperties(props) void

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.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# fireEvent

Availability
0.9
0.9
9.2.0
fireEvent(name[, event]) void

Fires 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

Availability
5.4.0
getAudioSessionId() Number

DEPRECATED SINCE 10.0.0

Use the audioSessionId property instead

Returns the audio session id.

Returns

Type
Number

# getPaused DEPRECATED

Availability
0.9
9.2.0
getPaused() Boolean

DEPRECATED SINCE 7.5.0

Use the cross-platform API paused property instead.

Returns the value of the paused property.

Returns

Type
Boolean

# getPlaying DEPRECATED

Availability
0.9
9.2.0
getPlaying() Boolean

DEPRECATED SINCE 7.5.0

Use the cross-platform API playing property instead.

Returns the value of the playing property.

Returns

Type
Boolean

# isPaused DEPRECATED

Availability
0.9
isPaused() Boolean

DEPRECATED SINCE 7.5.0

Use the cross-platform API paused property instead.

Returns the value of the paused property.

Returns

Type
Boolean

# isPlaying DEPRECATED

Availability
0.9
isPlaying() Boolean

DEPRECATED SINCE 7.5.0

Use the cross-platform API playing property instead.

Returns the value of the playing property.

Returns

Type
Boolean

# pause

Availability
0.9
0.9
9.2.0
pause() void

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 start on a paused stream resumes play.

Returns

Type
void

# play DEPRECATED

Availability
0.9
play() void

DEPRECATED 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

Availability
0.9
7.5.0
9.2.0
release() void

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.

Returns

Type
void

# removeEventListener

Availability
0.9
0.9
9.2.0
removeEventListener(name, callback) void

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);

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 addEventListener.

Returns

Type
void

# restart

Availability
7.5.0
7.5.0
9.2.0
restart() void

Restarts (stops and stars) audio playback.

Returns

Type
void

# seekToTime

Availability
7.5.0
9.2.0
seekToTime(time) void

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.

Parameters

Name Type Description
time Number

The time in milliseconds to seek to.

Returns

Type
void

# setPaused DEPRECATED

Availability
0.9
9.2.0
setPaused(paused) void

DEPRECATED 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 true to pause the current playback temporarily, false to unpause it.

Returns

Type
void

# start

Availability
0.9
0.9
9.2.0
start() void

Starts or resumes audio playback.

Returns

Type
void

# stateDescription

Availability
0.9
9.2.0
stateDescription(state) String

Converts a state value into a text description suitable for display.

Parameters

Name Type Description
state Number

State value to convert.

Returns

Type
String

# stop

Availability
0.9
0.9
9.2.0
stop() void

Stops audio playback.

Returns

Type
void

# Events

# change

Availability
0.9
0.9
9.2.0

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.

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

Availability
0.9
7.5.0
9.2.0

Fired when the audio has finished playing.

Properties

Name Type Description
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 error was generated by the operating system, that system's error value is used. Otherwise, this value will be -1.

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

Availability
7.5.0
9.2.0

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.

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

Availability
4.1.0
4.1.0
9.2.0

Fired 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

Availability
0.9
0.9
9.2.0

Fired 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

Availability
0.9
9.2.0

Fired 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 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.

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

Availability
6.2.0
AUDIO_TYPE_ALARM :Number

Used to identify the volume of audio streams for alarms.


# AUDIO_TYPE_MEDIA

Availability
6.2.0
AUDIO_TYPE_MEDIA :Number

Used to identify the volume of audio streams for media playback.


# AUDIO_TYPE_NOTIFICATION

Availability
6.2.0
AUDIO_TYPE_NOTIFICATION :Number

Used to identify the volume of audio streams for notifications.


# AUDIO_TYPE_RING

Availability
6.2.0
AUDIO_TYPE_RING :Number

Used to identify the volume of audio streams for the phone ring.


# AUDIO_TYPE_SIGNALLING

Availability
6.2.0
AUDIO_TYPE_SIGNALLING :Number

Used to identify the volume of audio streams for DTMF tones or beeps.


# AUDIO_TYPE_VOICE

Availability
6.2.0
AUDIO_TYPE_VOICE :Number

Used to identify the volume of audio streams for voice calls.


# STATE_BUFFERING DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_BUFFERING :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_BUFFERING instead.

Audio data is being buffered from the network.


# STATE_INITIALIZED DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_INITIALIZED :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_INITIALIZED instead.

Audio playback is being initialized.


# STATE_PAUSED DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_PAUSED :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_PAUSED instead.

Playback is paused.


# STATE_PLAYING DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_PLAYING :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_PLAYING instead.

Audio playback is active.


# STATE_STARTING DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_STARTING :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_STARTING instead.

Audio playback is starting.


# STATE_STOPPED DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_STOPPED :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_STOPPED instead.

Audio playback is stopped.


# STATE_STOPPING DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_STOPPING :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_STOPPING instead.

Audio playback is stopping.


# STATE_WAITING_FOR_DATA DEPRECATED

Availability
0.9
0.9
9.2.0
STATE_WAITING_FOR_DATA :Number

DEPRECATED 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

Availability
0.9
0.9
9.2.0
STATE_WAITING_FOR_QUEUE :Number

DEPRECATED SINCE 7.5.0

Use AUDIO_STATE_WAITING_FOR_QUEUE instead.

Player is waiting for audio data to fill the queue.