Titanium SDK

# Titanium.Media.Sound

An object for playing basic audio resources.

Availability
0.8
0.8
9.2.0
Extends
Titanium.Proxy

# Overview

The Sound object loads the entire media resource in memory before playing. If you need to support streaming, use the Titanium.Media.AudioPlayer API.

You can control how the sound interacts with other system sounds by setting Titanium.Media.audioSessionCategory.

Use the Titanium.Media.createSound method to create a Sound object. You can play audio in any format supported by the target platform(s), as described in the following documents:

# Examples

# Simple Example

Simple example of playing a WAVE file from the Resources directory.

var player = Ti.Media.createSound({url:"sound.wav"});
player.play();

# Properties

# allowBackground CREATION ONLY

Availability
1.3.0
allowBackground :Boolean

Determines whether the audio should continue playing even when its activity is paused.

Default: false

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

# 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

# duration READONLY

Availability
0.8
0.8
9.2.0
duration :Number

Duration of the audio resource.

On iOS, playback time is reported in seconds.

On Android, time is reported in milliseconds.

Android note: Starting from Titanium 3.2.0, the remote audio plays asynchronously. The duration can only be fetched after the audio is initialized (refer to STATE_INITIALIZED).

# lifecycleContainer

Availability
3.6.0
lifecycleContainer :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.

# looping

Availability
0.8
0.8
9.2.0
looping :Boolean

Determines whether the audio should loop upon completion.

Default: false

# paused

Availability
0.8
0.8
9.2.0
paused :Boolean

Indicates if the audio is paused.

On iOS, this property is read-write, and you can pause and resume playback by setting this property to true or false.

On Android, this property is read-only. For portability, use pause to pause audio, and play to resume.

# playing READONLY

Availability
0.8
0.8
9.2.0
playing :Boolean

Indicates if the audio is playing.

# time

Availability
0.8
0.8
9.2.0
time :Number

Current playback position of the audio.

Time is reported in milliseconds.

On iOS, prior to Release 3.0, playback time is reported in seconds.

# url

Availability
0.8
0.8
9.2.0
url :String

URL identifying the audio resource.

# volume

Availability
0.8
0.8
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_SOLO_AMBIENT, AUDIO_SESSION_CATEGORY_PLAYBACK, or AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD.

# Methods

# addEventListener

Availability
0.8
0.8
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.8
0.8
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

# isLooping DEPRECATED

Availability
0.8
0.8
9.2.0
isLooping() → Boolean

DEPRECATED SINCE 10.0.0

Use the looping property instead.

Returns the value of the looping property.

Returns

Type
Boolean

# isPaused DEPRECATED

Availability
0.8
0.8
9.2.0
isPaused() → Boolean

DEPRECATED SINCE 10.0.0

Use the paused property instead.

Returns the value of the paused property.

Returns

Type
Boolean

# isPlaying DEPRECATED

Availability
0.8
0.8
9.2.0
isPlaying() → Boolean

DEPRECATED SINCE 10.0.0

Use the playing property instead.

Returns the value of the playing property.

Returns

Type
Boolean

# pause

Availability
0.8
0.8
9.2.0
pause() → void

Pauses the audio.

To restart the audio, call play.

Returns

Type
void

# play

Availability
0.8
0.8
9.2.0
play() → void

Starting playing the sound, or resume playing a paused sound.

Returns

Type
void

# release

Availability
0.8
0.8
9.2.0
release() → void

Releases all internal resources.

This is typically unnecessary but can be useful if you load a large audio file in app.js, and play it only once and you would like to release all resources after your final play to reduce memory.

Returns

Type
void

# removeEventListener

Availability
0.8
0.8
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

# reset

Availability
0.8
0.8
9.2.0
reset() → void

Resets the audio playback position to the beginning.

Returns

Type
void

# setLooping DEPRECATED

Availability
0.8
0.8
9.2.0
setLooping(looping) → void

DEPRECATED SINCE 10.0.0

Set the value of the looping property directly.

Sets the value of the looping property.

Parameters

Name Type Description
looping Boolean

New value for the looping property.

Returns

Type
void

# setPaused DEPRECATED

Availability
0.8
9.2.0
setPaused(paused) → void

DEPRECATED SINCE 10.0.0

It is preferable to use the pause and play methods 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 play methods instead.

Parameters

Name Type Description
paused Boolean

Pass true to pause the current playback temporarily, false to unpause it.

Returns

Type
void

# stop

Availability
0.8
0.8
9.2.0
stop() → void

Stops playing the audio and resets the playback position to the beginning of the clip.

Returns

Type
void

# Events

# change

Availability
3.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 String

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.8
0.8
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.

# error

Availability
0.8
0.8
9.2.0

Fired when an error occurs while playing the audio.

Properties

Name Type Description
success Boolean

Indicates a successful operation. Returns false.

error String

Error message, if any returned. May be undefined.

code Number

Error code. If the error was generated by the operating system, that system's error value is used. Otherwise, this value will be -1.

message String

Error message.

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.

# interrupted

Availability
0.8
9.2.0

Fired when audio playback is interrupted by the device.

Typically called during an interruption due to an incoming phone call.

# resume

Availability
0.8
9.2.0

Fired when audio playback is resumed after an interruption.

Properties

Name Type Description
interruption Boolean

Indicates if the resume was from an interruption.

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

Availability
3.2.0
STATE_BUFFERING :Number

Audio data is being buffered from the network.

# STATE_INITIALIZED

Availability
3.2.0
STATE_INITIALIZED :Number

Audio playback is being initialized.

# STATE_PAUSED

Availability
3.2.0
STATE_PAUSED :Number

Playback is paused.

# STATE_PLAYING

Availability
3.2.0
STATE_PLAYING :Number

Audio playback is active.

# STATE_STARTING

Availability
3.2.0
STATE_STARTING :Number

Audio playback is starting.

# STATE_STOPPED

Availability
3.2.0
STATE_STOPPED :Number

Audio playback is stopped.

# STATE_STOPPING

Availability
3.2.0
STATE_STOPPING :Number

Audio playback is stopping.

# STATE_WAITING_FOR_DATA

Availability
3.2.0
STATE_WAITING_FOR_DATA :Number

Player is waiting for audio data from the network.

# STATE_WAITING_FOR_QUEUE

Availability
3.2.0
STATE_WAITING_FOR_QUEUE :Number

Player is waiting for audio data to fill the queue.

Contents