# 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

9.2.0

Extends

Titanium.Proxy

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

# audioType

Availability

6.2.0

audioType :Number

Changes the audio-stream-type.

This API can be assigned the following constants:

Default: Titanium.Media.AudioPlayer.AUDIO_TYPE_MEDIA

# 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

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

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

9.2.0

paused :Boolean

Boolean indicating if audio playback is paused.

# playing READONLY

Availability

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

# state READONLY

Availability

0.9

9.2.0

state :Number

Current state of playback, specified using one of the STATE constants defined on this object.

This API can be assigned the following constants:

# time

Availability

3.3.0

time :Number

Current playback position of the audio.

Time is reported in milliseconds.

# url

Availability

0.9

9.2.0

url :String

URL for the audio stream.

# volume

Availability

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

# 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

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

# restart

Availability

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

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

9.2.0

stop() → void

Stops audio playback.

Returns

Type: void

# Events

# change

Availability

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

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

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

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

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

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

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

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

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

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

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

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.