# 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
4.1.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


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


# autoplay

Availability
4.1.0
autoplay :Boolean

Indicates if the audio should automatically start playback.


# bitRate

Availability
0.9
9.2.0
bitRate :Number

Bit rate of the current playback stream.


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


# 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
4.1.0
paused :Boolean

Boolean indicating if audio playback is paused.


# playing READONLY

Availability
0.9
0.9
9.2.0
4.1.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
4.1.0
time :Number

Current playback position of the audio.

Time is reported in milliseconds.


# url

Availability
0.9
0.9
9.2.0
4.1.0
url :String

URL for the audio stream.


# volume

Availability
2.1.0
2.1.0
9.2.0
4.1.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
4.1.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

# 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
4.1.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
4.1.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
4.1.0
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
4.1.0
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
4.1.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
4.1.0
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

# 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
4.1.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
4.1.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
4.1.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.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


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

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


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

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


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

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


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

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


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

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

# 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
4.1.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
4.1.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
4.1.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
4.1.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
4.1.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
4.1.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
4.1.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
4.1.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
4.1.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.