# Titanium.Media.Sound
An object for playing basic audio resources.
# 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
Determines whether the audio should continue playing even when its activity is paused.
Default: false
# audioType
Changes the audio-stream-type.
Default: Titanium.Media.AudioPlayer.AUDIO_TYPE_MEDIA
# duration READONLY
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).
# paused
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.
# time
Current playback position of the audio.
Time is reported in milliseconds.
On iOS, prior to Release 3.0, playback time is reported in seconds.
# volume
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
# isLooping DEPRECATED
DEPRECATED SINCE 10.0.0
Use the looping property instead.
Returns the value of the looping property.
Returns
- Type
- Boolean
# isPaused DEPRECATED
DEPRECATED SINCE 10.0.0
Use the paused property instead.
Returns the value of the paused property.
Returns
- Type
- Boolean
# isPlaying DEPRECATED
DEPRECATED SINCE 10.0.0
Use the playing property instead.
Returns the value of the playing property.
Returns
- Type
- Boolean
# play
Starting playing the sound, or resume playing a paused sound.
Returns
- Type
- void
# release
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
# setLooping DEPRECATED
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 |
Returns
- Type
- void
# setPaused DEPRECATED
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 |
Returns
- Type
- void
# stop
Stops playing the audio and resets the playback position to the beginning of the clip.
Returns
- Type
- void
# Events
# change
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
Fired 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 |
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
Fired when an error occurs while playing the audio.
Properties
Name | Type | Description |
---|---|---|
success | Boolean | Indicates a successful operation. Returns |
error | String | Error message, if any returned. May be |
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 |
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
Fired when audio playback is interrupted by the device.
Typically called during an interruption due to an incoming phone call.
# resume
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
Used to identify the volume of audio streams for alarms.
# AUDIO_TYPE_MEDIA
Used to identify the volume of audio streams for media playback.
# AUDIO_TYPE_NOTIFICATION
Used to identify the volume of audio streams for notifications.
# AUDIO_TYPE_RING
Used to identify the volume of audio streams for the phone ring.
# AUDIO_TYPE_SIGNALLING
Used to identify the volume of audio streams for DTMF tones or beeps.
# AUDIO_TYPE_VOICE
Used to identify the volume of audio streams for voice calls.
# STATE_WAITING_FOR_DATA
Player is waiting for audio data from the network.
# STATE_WAITING_FOR_QUEUE
Player is waiting for audio data to fill the queue.