# Titanium.Media.AudioPlayer > An audio player object used for streaming audio to the device, and low-level control of the audio playback. - Source: https://titaniumsdk.com/docs/sdk/12.6.0/Titanium.Media.AudioPlayer - Titanium SDK version: 12.6.0 - Kind: proxy - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.9 - Extends: Titanium.Proxy - Inheritance: Titanium.Proxy On Android, when you are done playing a given audio file, you must call the [release](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#audioSessionCategory). Since Titanium 7.5.0, this API uses the [AVPlayer API](https://developer.apple.com/documentation/avfoundation/avplayer) for a more modern and performant audio playback. Use the [Titanium.Media.createAudioPlayer](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#createAudioPlayer) method to create an audio player. ## Example: Audio Streaming The following example demonstrates using the `AudioPlayer` object to stream audio. ``` js 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 - Type: Boolean - Platforms: Android - Default: `false` Boolean to indicate if audio should continue playing even if the associated Android [Activity](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md) is paused. Setting `allowBackground` to `true` allows the audio to continue playing, for example, if the application is in the background. ### allowsExternalPlayback - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 - Default: `true` Indicates whether the player allows switching to "external playback" mode. ### AUDIO_TYPE_ALARM - Type: Number - Platforms: Android - Since: Titanium SDK 6.2.0 - Permission: read-only Used to identify the volume of audio streams for alarms. ### AUDIO_TYPE_MEDIA - Type: Number - Platforms: Android - Since: Titanium SDK 6.2.0 - Permission: read-only Used to identify the volume of audio streams for media playback. ### AUDIO_TYPE_NOTIFICATION - Type: Number - Platforms: Android - Since: Titanium SDK 6.2.0 - Permission: read-only Used to identify the volume of audio streams for notifications. ### AUDIO_TYPE_RING - Type: Number - Platforms: Android - Since: Titanium SDK 6.2.0 - Permission: read-only Used to identify the volume of audio streams for the phone ring. ### AUDIO_TYPE_SIGNALLING - Type: Number - Platforms: Android - Since: Titanium SDK 6.2.0 - Permission: read-only Used to identify the volume of audio streams for DTMF tones or beeps. ### AUDIO_TYPE_VOICE - Type: Number - Platforms: Android - Since: Titanium SDK 6.2.0 - Permission: read-only Used to identify the volume of audio streams for voice calls. ### audioFocus - Type: Boolean - Platforms: Android - Default: `false` 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. ### audioSessionId - Type: Number - Platforms: Android - Since: Titanium SDK 10.0.0 - Permission: read-only Returns the audio session id. ### audioType - Type: Number - Platforms: Android - Since: Titanium SDK 6.2.0 - Default: `` Changes the audio-stream-type. Accepts: `Titanium.Media.Sound.AUDIO_TYPE_ALARM`, `Titanium.Media.Sound.AUDIO_TYPE_MEDIA`, `Titanium.Media.Sound.AUDIO_TYPE_NOTIFICATION`, `Titanium.Media.Sound.AUDIO_TYPE_RING`, `Titanium.Media.Sound.AUDIO_TYPE_SIGNALLING`, `Titanium.Media.Sound.AUDIO_TYPE_VOICE` ### bitRate - Type: Number - Platforms: iPhone, iPad, macOS Bit rate of the current playback stream. ### bufferSize - Type: Number - Platforms: iPhone, iPad, macOS 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 - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.3.0 - Permission: read-only Estimated duration in milliseconds of the file being played. May return `0` when playing a live stream. ### externalPlaybackActive - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 - Permission: read-only Indicates whether the player is currently playing video in "external playback" mode. ### idle - Type: Boolean - Platforms: iPhone, iPad, macOS - Permission: read-only 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 - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 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 - Type: Boolean - Platforms: Android, iPhone, iPad, macOS Boolean indicating if audio playback is paused. ### playing - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Boolean indicating if audio is currently playing. Returns `false` if playback is stopped or paused. ### progress - Type: Number - Platforms: iPhone, iPad, macOS - Permission: read-only Current playback progress, in milliseconds. Returns zero if `bitRate` has not yet been detected. ### rate - Type: Number - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 - Default: `0` 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 [Titanium.Media.AUDIO_STATE_PAUSED](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#AUDIO_STATE_PAUSED). Setting the rate to a non-zero value causes the value of the `state` property to become either or [Titanium.Media.AUDIO_STATE_PLAYING](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#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. ### state - Type: Number - Platforms: iPhone, iPad, macOS - Permission: read-only Current state of playback, specified using one of the `STATE` constants defined on this object. Accepts: `Titanium.Media.AUDIO_STATE_BUFFERING`, `Titanium.Media.AUDIO_STATE_INITIALIZED`, `Titanium.Media.AUDIO_STATE_PAUSED`, `Titanium.Media.AUDIO_STATE_PLAYING`, `Titanium.Media.AUDIO_STATE_STARTING`, `Titanium.Media.AUDIO_STATE_STOPPED`, `Titanium.Media.AUDIO_STATE_STOPPING`, `Titanium.Media.AUDIO_STATE_WAITING_FOR_DATA` ### STATE_BUFFERING - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_BUFFERING](Titanium.Media.AUDIO_STATE_BUFFERING) instead. Audio data is being buffered from the network. ### STATE_INITIALIZED - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_INITIALIZED](Titanium.Media.AUDIO_STATE_INITIALIZED) instead. Audio playback is being initialized. ### STATE_PAUSED - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_PAUSED](Titanium.Media.AUDIO_STATE_PAUSED) instead. Playback is paused. ### STATE_PLAYING - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_PLAYING](Titanium.Media.AUDIO_STATE_PLAYING) instead. Audio playback is active. ### STATE_STARTING - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_STARTING](Titanium.Media.AUDIO_STATE_STARTING) instead. Audio playback is starting. ### STATE_STOPPED - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_STOPPED](Titanium.Media.AUDIO_STATE_STOPPED) instead. Audio playback is stopped. ### STATE_STOPPING - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_STOPPING](Titanium.Media.AUDIO_STATE_STOPPING) instead. Audio playback is stopping. ### STATE_WAITING_FOR_DATA - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_WAITING_FOR_DATA](Titanium.Media.AUDIO_STATE_WAITING_FOR_DATA) instead. Player is waiting for audio data from the network. ### STATE_WAITING_FOR_QUEUE - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only - DEPRECATED since 7.5.0. Use [Titanium.Media.AUDIO_STATE_WAITING_FOR_QUEUE](Titanium.Media.AUDIO_STATE_WAITING_FOR_QUEUE) instead. Player is waiting for audio data to fill the queue. ### time - Type: Number - Platforms: Android - Since: Titanium SDK 3.3.0 Current playback position of the audio. Time is reported in milliseconds. ### url - Type: String - Platforms: Android, iPhone, iPad, macOS URL for the audio stream. ### volume - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 2.1.0 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 [Titanium.Media.appMusicPlayer](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#appMusicPlayer) and set the [Titanium.Media.audioSessionCategory](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#audioSessionCategory) property to either [Titanium.Media.AUDIO_SESSION_CATEGORY_AMBIENT](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#AUDIO_SESSION_CATEGORY_AMBIENT), [Titanium.Media.AUDIO_SESSION_CATEGORY_SOLO_AMBIENT](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#AUDIO_SESSION_CATEGORY_SOLO_AMBIENT), or [Titanium.Media.AUDIO_SESSION_CATEGORY_PLAYBACK](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#AUDIO_SESSION_CATEGORY_PLAYBACK). ### waiting - Type: Boolean - Platforms: iPhone, iPad, macOS - Permission: read-only 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 - Platforms: Android - Since: Titanium SDK 5.4.0 - DEPRECATED since 10.0.0. Use the [audioSessionId](Titanium.Media.AudioPlayer.audioSessionId) property instead Returns the audio session id. Returns: Number ### getPaused - Platforms: iPhone, iPad, macOS - DEPRECATED since 7.5.0, removed in 10.0.0. Use the cross-platform API property instead. Returns the value of the [paused](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#paused) property. Returns: Boolean ### getPlaying - Platforms: iPhone, iPad, macOS - DEPRECATED since 7.5.0, removed in 10.0.0. Use the cross-platform API property instead. Returns the value of the [playing](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#playing) property. Returns: Boolean ### isPaused - Platforms: Android - DEPRECATED since 7.5.0, removed in 10.0.0. Use the cross-platform API property instead. Returns the value of the [paused](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#paused) property. Returns: Boolean ### isPlaying - Platforms: Android - DEPRECATED since 7.5.0, removed in 10.0.0. Use the cross-platform API property instead. Returns the value of the [playing](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#playing) property. Returns: Boolean ### pause - Platforms: Android, iPhone, iPad, macOS 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 [Titanium.Media.AudioPlayer.start](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#start) on a paused stream resumes play. ### play - Platforms: Android - DEPRECATED since 7.5.0. Use the cross-platform API [Titanium.Media.AudioPlayer.start](Titanium.Media.AudioPlayer.start) instead. Starts or resumes audio playback. This method is identical to . ### release - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 0.9, iPhone 7.5.0, iPad 7.5.0 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. ### restart - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 Restarts (stops and stars) audio playback. ### seekToTime - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 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: - `time` (Number): The time in milliseconds to seek to. ### setPaused - Platforms: iPhone, iPad, macOS - DEPRECATED since 7.5.0, removed in 10.0.0. Use the cross-platform API [Titanium.Media.AudioPlayer.pause](Titanium.Media.AudioPlayer.pause) instead. Sets the value of the [paused](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#paused) property. On iOS, this method can be used to pause and unpause playback. For portability, it is preferable to use the [Titanium.Media.AudioPlayer.pause](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#pause) and [Titanium.Media.AudioPlayer.start](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#start) methods instead. Parameters: - `paused` (Boolean): Pass `true` to pause the current playback temporarily, `false` to unpause it. ### start - Platforms: Android, iPhone, iPad, macOS Starts or resumes audio playback. ### stateDescription - Platforms: iPhone, iPad, macOS Converts a [state](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#state) value into a text description suitable for display. Parameters: - `state` (Number): State value to convert. Returns: String ### stop - Platforms: Android, iPhone, iPad, macOS Stops audio playback. ## Events ### change - Platforms: Android, iPhone, iPad, macOS 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. Event properties: - `state` (Number): Current state of playback. - `description` (Number): Text description of the state of playback. ### complete - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 0.9, iPhone 7.5.0, iPad 7.5.0 Fired when the audio has finished playing. Event properties: - `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. ### error - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 4.1.0 Fired when there's an error. Event properties: - `error` (String): Error message. - `code` (Number): Error code. Different between android and iOS. ### metadata - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 7.5.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](https://developer.apple.com/documentation/avfoundation/avplayeritem/1389602-timedmetadata?language=objc). Event properties: - `items` (Array): An array of metadata items containing relevant information about the current media item. ### progress - Platforms: Android, iPhone, iPad, macOS Fired once per second with the current progress during playback. Event properties: - `progress` (Number): Current progress, in milliseconds. ### seek - Platforms: iPhone, iPad, macOS Fired once the [seekToTime](https://titaniumsdk.com/docs/sdk/Titanium.Media.AudioPlayer.md#seek) method completes. Event properties: - `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`. ## Inherited members 7 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.