# Titanium.Media

The top-level Media module.

Availability
0.8
0.8
9.2.0

# Overview

The Media module is used to access the device's media-related functionality, such as using the device's camera and photo gallery, playing media files, or recording audio or video. For examples of using the Media APIs, refer to the Working with Media APIs guide (opens new window) in addition to the other media submodule API documentation. Note: Some third party Android camera apps may choose to ignore video recording quality settings. If you wish to specifically set the video quality, don't assume EXTRA_VIDEO_QUALITY intent will be respected by the camera app and use Titanium's built-in camera window which can be used to assign the overlay property when calling the showCamera() method.

# Properties

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


# appMusicPlayer READONLY

Availability
0.8
9.2.0
appMusicPlayer :Titanium.Media.MusicPlayer

An instance of Titanium.Media.MusicPlayer representing the app-specific music player.


# aspectRatio READONLY

Availability
12.2.0
aspectRatio :Number

Aspect ratio of the image.

This API can be assigned the following constants:

Default: Titanium.Media.ASPECT_RATIO_4_3


# audioPlaying READONLY

Availability
0.8
9.2.0
audioPlaying :Boolean

Returns true if the device is playing audio.


# audioSessionCategory

Availability
3.4.2
9.2.0
audioSessionCategory :String

A constant for the audio session category to be used.

Set to one of the AUDIO_SESSION_CATEGORY constants defined in Titanium.Media.

Must be set while the audio session is inactive (no sounds are playing, no listeners for audio properties on the Media module, but the iPod may be active).


# availableCameraMediaTypes

Availability
0.8
9.2.0
availableCameraMediaTypes :Array<String>

Array of media type constants supported for the camera.


# availableCameras READONLY

Availability
3.2.0
0.8
9.2.0
availableCameras :Array<Number>

Array indicating which cameras are available, CAMERA_FRONT, CAMERA_REAR or both.

This API can be assigned the following constants:

# availablePhotoGalleryMediaTypes

Availability
0.8
9.2.0
availablePhotoGalleryMediaTypes :Array<String>

Array of media type constants supported for saving to the device's camera roll or saved images album.


# availablePhotoMediaTypes

Availability
0.8
9.2.0
availablePhotoMediaTypes :Array<String>

Array of media type constants supported for the photo library.


# averageMicrophonePower

Availability
0.8
9.2.0
averageMicrophonePower :Number

Current average microphone level in dB or -1 if microphone monitoring is disabled.


# 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


# cameraAuthorization READONLY

Availability
5.2.0
9.2.0
cameraAuthorization :Number

Returns the authorization status for the camera.


# cameraFlashMode

Availability
3.3.0
1.4.0
9.2.0
cameraFlashMode :Number

Determines how the flash is fired when using the device's camera.

Default: Titanium.Media.CAMERA_FLASH_AUTO> on iOS, <Titanium.Media.CAMERA_FLASH_OFF> on Android


# cameraOutputSizes READONLY

Availability
12.2.0
cameraOutputSizes :Object

Returns an object of possible targetImageWidth and targetImageHeight values. The output contains a cameraType (front or back) and object of width/height values. You have to set targetImageWidth and targetImageHeight if you want to change the camera image output size. Note: depeneding on your phone and camera the values won't be used or can be different.


# canRecord READONLY

Availability
6.2.0
0.8
9.2.0
canRecord :Boolean

true if the device has a recording input device available.


# currentRoute READONLY

Availability
3.4.2
9.2.0
currentRoute :RouteDescription

Returns a description of the current route, consisting of zero or more input ports and zero or more output ports.


# isCameraSupported READONLY

Availability
0.8
0.8
9.2.0
isCameraSupported :Boolean

true if the device has camera support.


# lifecycleContainer

Availability
3.6.0

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.


# maxZoomLevel READONLY

Availability
12.2.0
maxZoomLevel :Number

Returns the max zoom level of the camera.


# minZoomLevel READONLY

Availability
12.2.0
minZoomLevel :Number

Returns the min zoom level of the camera.


# peakMicrophonePower READONLY

Availability
0.8
9.2.0
peakMicrophonePower :Number

Current microphone level peak power in dB or -1 if microphone monitoring is disabled.


# QUALITY_640x480 READONLY

Availability
7.5.0
0.9.0
9.2.0
QUALITY_640x480 :Number

Media type constant for medium-quality video recording.

If recording, specifies that you want to use VGA-quality video recording (pixel dimensions of 640x480).


# QUALITY_IFRAME_1280x720 READONLY

Availability
7.5.0
6.0.0
9.2.0
QUALITY_IFRAME_1280x720 :Number

Media type constant for medium-quality video recording.

If recording, specifies that you want to use 1280x720 iFrame format.


# QUALITY_IFRAME_960x540 READONLY

Availability
6.0.0
9.2.0
QUALITY_IFRAME_960x540 :Number

Media type constant for medium-quality video recording.

If recording, specifies that you want to use 960x540 iFrame format.


# scalingMode READONLY

Availability
12.2.0
scalingMode :Number

Scaling mode of the preview image.

Default: Titanium.Media.IMAGE_SCALING_ASPECT_FILL


# systemMusicPlayer READONLY

Availability
0.8
9.2.0
systemMusicPlayer :Titanium.Media.MusicPlayer

An instance of Titanium.Media.MusicPlayer representing the system-wide music player.


# torch

Availability
12.2.0
torch :Boolean

Enable or disable the camera torch.


# useCameraX READONLY

Availability
12.2.0
useCameraX :Boolean

To use the new CameraX classes for "camera with overlay" set useCameraX to true

Default: false


# verticalAlign READONLY

Availability
12.2.0
verticalAlign :Number

Vertical align of the preview image for aspect fit.

Default: Titanium.Media.VERTICAL_ALIGN_CENTER


# volume READONLY

Availability
0.8
9.2.0
volume :Number

Current volume of the playback device.

A value in the range 0.0 to 1.0, with 0.0 representing the minimum volume and 1.0 representing the maximum volume.


# zoomLevel

Availability
12.2.0
zoomLevel :Number

Sets the zoom level of the camera.

# 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

# beep

Availability
0.8
9.2.0
beep() → void

Plays a device beep notification.

Returns

Type
void

# createAudioPlayer

Availability
0.9
0.9
9.2.0
createAudioPlayer([parameters]) → Titanium.Media.AudioPlayer

Creates and returns an instance of Titanium.Media.AudioPlayer.

Parameters

Name Type Description
parameters Dictionary<Titanium.Media.AudioPlayer>

Properties to set on a new object, including any defined by Titanium.Media.AudioPlayer except those marked not-creation or read-only.

Returns


# createAudioRecorder

Availability
6.2.0
0.9
9.2.0
createAudioRecorder([parameters]) → Titanium.Media.AudioRecorder

Creates and returns an instance of Titanium.Media.AudioRecorder.

Parameters

Name Type Description
parameters Dictionary<Titanium.Media.AudioRecorder>

Properties to set on a new object, including any defined by Titanium.Media.AudioRecorder except those marked not-creation or read-only.

Returns


# createSound

Availability
0.8
0.8
9.2.0
createSound([parameters]) → Titanium.Media.Sound

Creates and returns an instance of Titanium.Media.Sound.

Parameters

Name Type Description
parameters Dictionary<Titanium.Media.Sound>

Properties to set on a new object, including any defined by Titanium.Media.Sound except those marked not-creation or read-only.

Returns


# createSystemAlert DEPRECATED

Availability
6.1.0
9.2.0
createSystemAlert([parameters]) → Titanium.Media.SystemAlert

DEPRECATED SINCE 8.0.0

This iOS-only API has been deprecated and moved to the Ti.SystemAlert module in 8.0.0.

Creates and returns an instance of Titanium.Media.SystemAlert.

Parameters

Name Type Description
parameters Dictionary<Titanium.Media.SystemAlert>

Properties to set on a new object, including any defined by Titanium.Media.SystemAlert except those marked not-creation or read-only.

Returns


# createVideoPlayer

Availability
0.9
0.9
9.2.0
createVideoPlayer([parameters]) → Titanium.Media.VideoPlayer

Creates and returns an instance of Titanium.Media.VideoPlayer.

Parameters

Name Type Description
parameters Dictionary<Titanium.Media.VideoPlayer>

Properties to set on a new object, including any defined by Titanium.Media.VideoPlayer except those marked not-creation or read-only.

Returns


# 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

# hasAudioPermissions DEPRECATED

Availability
6.0.0
9.2.0
hasAudioPermissions() → Boolean

DEPRECATED SINCE 6.1.0

Use hasAudioRecorderPermissions instead.

Returns true if the app has audio permissions.

Recording audio requires explicit permission from the user. After the user grants or denies permission, the system remembers the choice for future use in the same app. If permission is not granted, or if the user has not yet responded to the permission prompt, any audio recording sessions record only silence.

In addition, Apple introduced the Info.plist key NSMicrophoneUsageDescription that is used to display an own description while authorizing microphone permissions. In iOS 10, this key is mandatory and the application will crash if your app does not include the key. Check the Apple docs for more information.

Returns

Type
Boolean

# hasAudioRecorderPermissions

Availability
6.2.0
6.1.0
9.2.0
hasAudioRecorderPermissions() → Boolean

Returns true if the app has audio permissions.

Recording audio requires explicit permission from the user. After the user grants or denies permission, the system remembers the choice for future use in the same app. If permission is not granted, or if the user has not yet responded to the permission prompt, any audio recording sessions record only silence.

In addition, Apple introduced the Info.plist key NSMicrophoneUsageDescription that is used to display an own description while authorizing microphone permissions. In iOS 10, this key is mandatory and the application will crash if your app does not include the key. Check the Apple docs for more information.

Returns

Type
Boolean

# hasCameraPermissions

Availability
5.1.0
5.1.0
9.2.0
hasCameraPermissions() → Boolean

Returns true if the app has camera access.

Returns

Type
Boolean

# hasMusicLibraryPermissions

Availability
6.0.0
9.2.0
hasMusicLibraryPermissions() → Boolean

Returns true if the app has music library access.

Music-library permissions are only needed in iOS 9.3 and later and will be ignored on older iOS versions. Because of that, the method will return true for devices that run iOS < 9.3.

Returns

Type
Boolean

# hasPhotoGalleryPermissions

Availability
9.3.0
6.0.0
9.2.0
hasPhotoGalleryPermissions() → Boolean

Returns true if the app has photo gallery permissions.

If you use Android 13+ you have to add the following permissions to your tiapp.xml:

<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>

You don't need to check this before using requestPhotoGalleryPermissions. If you already have the permission and use requestPhotoGalleryPermissions it will call the success event, no second permission request is displayed.

Returns

Type
Boolean

# hideCamera

Availability
3.2.0
0.8
9.2.0
hideCamera() → void

Hides the device camera UI.

Must be called after calling showCamera and only when autohide is set to false. This method causes the media capture UI to be hidden.

Returns

Type
void

# hideMusicLibrary

Availability
0.8
9.2.0
hideMusicLibrary() → void

Hides the music library.

Must be called after calling openMusicLibrary and only when autohide is set to false.

Returns

Type
void

# isMediaTypeSupported

Availability
0.8
9.2.0
isMediaTypeSupported(source, type) → Boolean

Returns true if the source supports the specified media type.

You can query whether a given media type is supported by the device's camera (source == 'camera') or photo library (source == 'photo').

An additional value, photogallery can be used to query the media supported by the device's camera roll or saved image album, which is a subset of the iOS photo library. However, when calling openPhotoGallery on iOS, the entire library is displayed, and there is currently no way to restrict the gallery to show only the camera roll/saved images album.

Parameters

Name Type Description
source String

Media source specified as a string: camera for Camera or photo for Photo Library.

type String

Media type to check.

Returns

Type
Boolean

# openMusicLibrary

Availability
0.8
9.2.0
openMusicLibrary(options) → void

Shows the music library and allows the user to select one or more tracks.

If autohide is set to false, you must hide the library explicitly using hideMusicLibrary.

Parameters

Name Type Description
options MusicLibraryOptionsType

A dictionary of options as described in MusicLibraryOptionsType.

Returns

Type
void

# openPhotoGallery

Availability
0.8
0.8
9.2.0
openPhotoGallery(options) → void

Opens the photo gallery image picker.

In iOS 6, Apple introduced the Info.plist key NSPhotoLibraryUsageDescription that is used to display an own description while authorizing gallery permissions. In iOS 10, this key is mandatory and the application will crash if your app does not include the key. Check the Apple docs for more information.

Parameters

Name Type Description
options PhotoGalleryOptionsType

Photo gallery options as described in PhotoGalleryOptionsType.

Returns

Type
void

# pauseVideoCapture

Availability
12.2.0
pauseVideoCapture() → void

Pauses video capturing.

Returns

Type
void

# previewImage

Availability
0.8
previewImage(options) → void

Displays the given image.

Parameters

Name Type Description
options Dictionary<PreviewImageOptions>

Dictionary containing the image and callback functions.

Returns

Type
void

# queryMusicLibrary

Availability
0.8
9.2.0
queryMusicLibrary(query) → Array<Titanium.Media.Item>

Searches the music library for items matching the specified search predicates.

Use hasMusicLibraryPermissions to check the granted permissions and requestMusicLibraryPermissions to request the permissions. This is especially important when running on an iOS 10 device, because the music-library access will crash without having the privacy-key NSAppleMusicUsageDescription that is specified in requestMusicLibraryPermissions.

Parameters

Name Type Description
query MediaQueryType

The query object to extract information from.

Returns

Type
Array<Titanium.Media.Item>

# 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

# requestAudioRecorderPermissions

Availability
6.2.0
6.1.0
9.2.0
requestAudioRecorderPermissions([callback]) → Promise<MediaAuthorizationResponse>

Request the user's permission for audio recording.

Recording audio requires explicit permission from the user. After the user grants or denies permission, the system remembers the choice for future use in the same app. If permission is not granted, or if the user has not yet responded to the permission prompt, any audio recording sessions record only silence.

In addition, Apple introduced the Info.plist key NSMicrophoneUsageDescription that is used to display an own description while authorizing microphone permissions. In iOS 10, this key is mandatory and the application will crash if your app does not include the key. Check the Apple docs for more information.

Parameters

Name Type Description
callback Callback<MediaAuthorizationResponse>

Callback function to execute when the users responds to the authorization alert. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<MediaAuthorizationResponse>

# requestCameraPermissions

Availability
5.1.0
5.1.0
9.2.0
requestCameraPermissions([callback]) → Promise<RequestCameraAccessResult>

Requests for camera access.

On Android, the request view will show if the permission is not accepted by the user, and the user did not check the box "Never ask again" when denying the request. If the user checks the box "Never ask again," the user has to manually enable the permission in device settings.

This method requests Manifest.permission.CAMERA, Manifest.permission.READ_EXTERNAL_STORAGE and Manifest.permission.WRITE_EXTERNAL_STORAGE on Android. If you require other permissions, you can also use requestPermissions.

In iOS 6, Apple introduced the Info.plist key NSCameraUsageDescription that is used to display an own description while authorizing camera permissions. In iOS 10, this key is mandatory when taking a photo and the application will crash if your app does not include the key. Check the Apple docs for more information. When using the camera to take a video, you also need the NSMicrophoneUsageDescription key. In addition, the authorization dialog will only show if user has not made a decision, yet. If the user has, the callback will return the earlier decision. To change the permission the user needs to change it in the device settings.

Parameters

Name Type Description
callback Callback<RequestCameraAccessResult>

Function to call indicating if permission was granted or denied. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<RequestCameraAccessResult>

# requestMusicLibraryPermissions

Availability
6.0.0
9.2.0
requestMusicLibraryPermissions(callback) → void

Request permissions for the native music-library.

Music-library permissions are only needed in iOS 9.3 and later and will be ignored on older iOS versions. Because of that, the callback will ignore the permission-check and always return {success: true} for devices that run iOS < 9.3.

Important: On iOS 10, Apple introduced the Info.plist key NSAppleMusicUsageDescription that is used to display an own description while authorizing the music library. This key is mandatory and the application will crash if your app does not include the key. Check the Apple docs for more information.

Parameters

Name Type Description
callback Callback<RequestMusicLibraryAccessResult>

Function to call indicating if permission was granted or denied.

Returns

Type
void

# requestPhotoGalleryPermissions

Availability
9.3.0
6.0.0
9.2.0
requestPhotoGalleryPermissions([callback]) → Promise<RequestPhotoGalleryAccessResult>

Requests for photo gallery permissions.

In iOS 6, Apple introduced the Info.plist key NSPhotoLibraryUsageDescription that is used to display an own description while authorizing photo gallery permissions. In iOS 10, this key is mandatory when accessing the photo gallery and the application will crash if your app does not include the key. Check the Apple docs for more information. If the user has, the callback will return the earlier decision. To change the permission the user needs to change it in the device settings.

iOS Apps that do not include this method, will present the system-dialog while the dialog is opened with openPhotoGallery.

If you use Android 13+ you have to add the following permissions to your tiapp.xml:

<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>

When you only want to use it for images you can use [requestPermissions](/api/titanium/android.html#requestpermissions) and request android.permission.READ_MEDIA_IMAGES.

Parameters

Name Type Description
callback Callback<RequestPhotoGalleryAccessResult>

Function to call indicating if permission was granted or denied. Optional on SDK 10, as this method will return a Promise, which may be used to handle the result.

Returns

On SDK 10+, this method will return a Promise whose resolved value is equivalent to that passed to the optional callback argument.

Type
Promise<RequestPhotoGalleryAccessResult>

# resumeVideoCapture

Availability
12.2.0
resumeVideoCapture() → void

Resumes video capturing.

Returns

Type
void

# saveToPhotoGallery

Availability
3.3.0
0.8
9.2.0
saveToPhotoGallery(media, callbacks) → void

Saves media to the device's photo gallery / camera roll.

This operation is asynchronous. The caller can supply callbacks to be triggered when the save operation completes.

Media can be passed as either a Blob object or a File object. If the media argument is not one of these types, an error is generated.

Note that when passing a file (or a blob created from a file), the file name must have the appropriate extension for the data--for example, image.jpg or video1.mov work, but video1.tmp does not. Currently, the .mp4 extension is not supported, but MP4 files may be imported by saving them with the .mov extension.

Make sure to check for gallery access permissions with hasPhotoGalleryPermissions and request the permissions with requestPhotoGalleryPermissions if not granted. On iOS, the NSPhotoLibraryAddUsageDescription plist key is required in the tiapp.xml in order to use this API.

On Android, this method does not support saving videos to the gallery prior to Titanium SDK 6.1.0.

Parameters

Name Type Description
media Titanium.Blob | Titanium.Filesystem.File

Media to save to the camera roll or media gallery.

callbacks Object

Pass a dictionary with the following supported keys: success a function that will be called when the save succeeds, and error a function that will be called upon receiving an error.

Returns

Type
void

# setOverrideAudioRoute

Availability
0.8
9.2.0
setOverrideAudioRoute(route) → void

Overrides the default audio route when using the AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD session mode.

By default, when using the AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD session mode, the audio output is routed to the speaker in the receiver. This method lets you specify that audio should be routed to the built-in speaker.

If you override the audio route while audio is playing the changes won't not take effect until the audio is restarted.

Parameters

Name Type Description
route Number

The specified audio route.

Returns

Type
void

# showCamera

Availability
0.8
0.8
9.2.0
showCamera(options) → void

Shows the camera.

By default, the native camera controls are displayed. To add your own camera controls, you can add an overlay view by setting the overlay property on the options argument.

# Android Platform Notes

  • To suppress the default controls, set autohide to false and then set the overlay property to a view that contains a control (such as a button) to take the photo. You must then control the camera explicitly, using the takePicture and hideCamera methods.
  • Setting saveToPhotoGallery to false is not guaranteed to work with all camera apps. If this setting is desired, then you should use Titanium's internal camera overlay instead.
  • You can only use one or the other (video or photo) types in the array.

# iOS Platform Notes

To suppress the default controls, set showControls and autohide to false.

If the showControls option is false, you must control the camera explicitly, using the takePicture and hideCamera methods.

Images taken with the camera will not have accurate geolocation data embedded in the images; the latitude and longitude will be set to '0'. This is not an error, but a limitation which Apple has put on the camera API.

Important: Use hasCameraPermissions and requestCameraPermissions to ask for camera permissions. This is especially important when running on iOS 10 and later, since the application may crash otherwise.

Parameters

Name Type Description
options CameraOptionsType

A dictionary of camera options as described in CameraOptionsType.

Returns

Type
void

# startMicrophoneMonitor

Availability
0.8
9.2.0
startMicrophoneMonitor() → void

Starts monitoring the microphone sound level.

Returns

Type
void

# startVideoCapture

Availability
5.4.0
5.4.0
9.2.0
startVideoCapture() → void

Starts video capture using the camera specified.

Returns

Type
void

# stopMicrophoneMonitor

Availability
0.8
9.2.0
stopMicrophoneMonitor() → void

Stops monitoring the microphone sound level.

Returns

Type
void

# stopVideoCapture

Availability
5.4.0
5.4.0
9.2.0
stopVideoCapture() → void

Stops video capture using the camera specified.

Returns

Type
void

# switchCamera

Availability
3.2.0
1.8.1
9.2.0
switchCamera(camera) → void

Switches between front and rear-facing cameras. Make sure to set one of the below constants to determine the camera you want to switch to.

In Android, this can only be called when using a custom overlay (see showCamera).

Parameters

Name Type Description
camera Number

Constant indicating to which camera you want to switch.

Returns

Type
void

# takePicture

Availability
0.8
0.8
9.2.0
takePicture() → void

Uses the device camera to capture a photo.

Must be called after calling showCamera and only when autohide is set to false.

This method causes the media capture device to capture a photo and call the success callback.

Returns

Type
void

# takeScreenshot

Availability
0.8
0.8
9.2.0
takeScreenshot(callback) → void

Takes a screen shot of the visible UI on the device.

This method is asynchronous. The screenshot is returned in the callback argument. The callback argument's media property contains the screenshot image as a Titanium.Blob object.

Parameters

Name Type Description
callback Callback<ScreenshotResult>

Function to call upon capture.

Returns

Type
void

# vibrate

Availability
0.8
0.8
9.2.0
vibrate([pattern]) → void

Makes the device vibrate.

On Android, a pattern argument can be provided to specify a vibration pattern.

The pattern is an array of Number values. Each number in the array is interpreted as a duration in milliseconds. The first number is the delay before the pattern starts, and the remaining numbers are interpreted as alternating periods of on and off times. For example, the following pattern:

[ 0, 500, 100, 500, 100, 500 ]

Would cause the vibration to start immediately (delay = 0), and perform three long vibrations (500 ms) separated by short pauses (100ms).

Parameters

Name Type Description
pattern Array<Number>

Array of values identifying a vibrate pattern (only used on Android).

Returns

Type
void

# Events

# cameraready

Availability
6.0.0

Fires when the camera overlay is ready to take pictures.


# routechange

Availability
3.4.2
9.2.0

Fired when an audio line type change is detected.

Properties

Name Type Description
reason String

The reason for route change.

oldRoute RouteDescription

Returns a description of the old route, consisting of zero or more input ports and zero or more output ports.

currentRoute RouteDescription

Returns a description of the current route, consisting of zero or more input ports and zero or more output ports.

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.


# volume

Availability
0.8
9.2.0

Fired when the volume output changes.

Properties

Name Type Description
volume Number

New volume level in dB.

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

# ASPECT_RATIO_16_9

Availability
12.2.0
ASPECT_RATIO_16_9 :Number

Aspect ratio 16:9


# ASPECT_RATIO_4_3

Availability
12.2.0
ASPECT_RATIO_4_3 :Number

Aspect ratio 4:3


# AUDIO_FILEFORMAT_3GP2

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_3GP2 :Number

Audio file format 3GPP2.


# AUDIO_FILEFORMAT_3GPP

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_3GPP :Number

Audio file format 3GPP.


# AUDIO_FILEFORMAT_AIFF

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_AIFF :Number

Audio file format Audio Interchange File Format (AIFF).


# AUDIO_FILEFORMAT_AMR

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_AMR :Number

Audio file format Adaptive Multi-Rate (AMR).


# AUDIO_FILEFORMAT_CAF

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_CAF :Number

Audio file format Apple Compressed Audio Format (CAF).


# AUDIO_FILEFORMAT_MP3

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_MP3 :Number

Audio file format MP3.


# AUDIO_FILEFORMAT_MP4

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_MP4 :Number

Audio file format MP4.


# AUDIO_FILEFORMAT_MP4A

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_MP4A :Number

Audio file format MP4A.


# AUDIO_FILEFORMAT_WAVE

Availability
0.8
9.2.0
AUDIO_FILEFORMAT_WAVE :Number

Audio file format WAVE.


# AUDIO_FORMAT_AAC

Availability
0.8
9.2.0
AUDIO_FORMAT_AAC :Number

Audio format MPEG4 AAC encoding.


# AUDIO_FORMAT_ALAW

Availability
0.8
9.2.0
AUDIO_FORMAT_ALAW :Number

Audio format 8-bit aLaw encoding.


# AUDIO_FORMAT_APPLE_LOSSLESS

Availability
0.8
9.2.0
AUDIO_FORMAT_APPLE_LOSSLESS :Number

Audio format Apple lossless encoding.


# AUDIO_FORMAT_ILBC

Availability
0.8
9.2.0
AUDIO_FORMAT_ILBC :Number

Audio format iLBC encoding.


# AUDIO_FORMAT_IMA4

Availability
0.8
9.2.0
AUDIO_FORMAT_IMA4 :Number

Audio format Apple IMA4 encoding.


# AUDIO_FORMAT_LINEAR_PCM

Availability
0.8
9.2.0
AUDIO_FORMAT_LINEAR_PCM :Number

Audio format 16-bit, linear PCM encoding.


# AUDIO_FORMAT_ULAW

Availability
0.8
9.2.0
AUDIO_FORMAT_ULAW :Number

Audio format 8-bit muLaw encoding.


# AUDIO_SESSION_CATEGORY_AMBIENT

Availability
3.4.2
9.2.0
AUDIO_SESSION_CATEGORY_AMBIENT :String

For long-duration sounds such as rain, car engine noise, and so on.

Also used for for 'play along' style applications, such a virtual piano that a user plays over iPod audio.

See also: AUDIO_SESSION_CATEGORY_SOLO_AMBIENT.


# AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD

Availability
3.4.2
9.2.0
AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD :String

Session mode for recording (input) and playback (output) of audio, such as for a VOIP (voice over IP) application.

This category is appropriate for simultaneous recording and playback, and also for applications that record and play back but not simultaneously. If you want to ensure that sounds such as Messages alerts do not play while your application is recording, use AUDIO_SESSION_CATEGORY_RECORD instead. This category normally disallows mixing iPod audio with application audio.

In this mode, by default audio playback is routed to the speaker in the iPhone receiver. To have audio playback through the iPhone speaker, use setOverrideAudioRoute.


# AUDIO_SESSION_CATEGORY_PLAYBACK

Availability
3.4.2
9.2.0
AUDIO_SESSION_CATEGORY_PLAYBACK :String

Session mode for playing recorded music or other sounds that are central to the successful use of your application.

When using this mode, your application audio continues with the Ring/Silent switch set to silent or when the screen locks. This property normally disallows mixing iPod audio with application audio.


# AUDIO_SESSION_CATEGORY_RECORD

Availability
3.4.2
9.2.0
AUDIO_SESSION_CATEGORY_RECORD :String

Session mode for recording audio; it silences playback audio.


# AUDIO_SESSION_CATEGORY_SOLO_AMBIENT

Availability
3.4.2
9.2.0
AUDIO_SESSION_CATEGORY_SOLO_AMBIENT :String

Session mode for long-duration sounds such as rain, car engine noise, and so on.

When you use this category, audio from built-in applications, such as the iPod, is silenced. Your audio is silenced when the Ring/Silent switch is set to silent or when the screen locks.

To use long-duration sounds without silencing built-in applications, see AUDIO_SESSION_CATEGORY_AMBIENT.


# AUDIO_SESSION_OVERRIDE_ROUTE_NONE

Availability
0.8
9.2.0
AUDIO_SESSION_OVERRIDE_ROUTE_NONE :Number

Constant that specifies audio should output to the default audio route. See setOverrideAudioRoute for more information.


# AUDIO_SESSION_OVERRIDE_ROUTE_SPEAKER

Availability
0.8
9.2.0
AUDIO_SESSION_OVERRIDE_ROUTE_SPEAKER :Number

Constant that specifies audio should output to the speaker. See setOverrideAudioRoute for more information.


# AUDIO_SESSION_PORT_AIRPLAY

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_AIRPLAY :String

Constant for output on a remote Air Play device. This is an output port.


# AUDIO_SESSION_PORT_BLUETOOTHA2DP

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_BLUETOOTHA2DP :String

Constant for output on a Bluetooth A2DP device. This is an output port.


# AUDIO_SESSION_PORT_BLUETOOTHHFP

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_BLUETOOTHHFP :String

Constant for input or output on a Bluetooth Hands-Free Profile device. This can be both an input and output port.


# AUDIO_SESSION_PORT_BLUETOOTHLE

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_BLUETOOTHLE :String

Constant for output on a Bluetooth Low Energy device. This is an output port. This is available on iOS7 and later.


# AUDIO_SESSION_PORT_BUILTINMIC

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_BUILTINMIC :String

Constant for built-in microphone on an iOS device. This is an input port.


# AUDIO_SESSION_PORT_BUILTINRECEIVER

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_BUILTINRECEIVER :String

Constant for the speaker you hold to your ear when on a phone call. This is an output port.


# AUDIO_SESSION_PORT_BUILTINSPEAKER

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_BUILTINSPEAKER :String

Constant for built-in speaker on an iOS device. This is an output port.


# AUDIO_SESSION_PORT_CARAUDIO

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_CARAUDIO :String

Constant for Input or output via Car Audio. This can be both an input and output port. This is available on iOS7 and later.


# AUDIO_SESSION_PORT_HDMI

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_HDMI :String

Constant for output via High-Definition Multimedia Interface. This is an output port


# AUDIO_SESSION_PORT_HEADPHONES

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_HEADPHONES :String

Constant for headphone or headset output. This is an output port.


# AUDIO_SESSION_PORT_HEADSETMIC

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_HEADSETMIC :String

Constant for microphone on a wired headset. This is an input port.


# AUDIO_SESSION_PORT_LINEIN

Availability
3.4.2
9.2.0
AUDIO_SESSION_PORT_LINEIN :String