Titanium.Media
The top-level Media module.
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 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.
Extends: Titanium.Module · Since: 0.1
Properties #
apiName#
Type: 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, Button
returns Ti.UI.Button.
appMusicPlayer#
Type: Titanium.Media.MusicPlayer
An instance of Titanium.Media.MusicPlayer representing the app-specific music player.
AUDIO_SESSION_CATEGORY_AMBIENT#
Type: 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#
Type: 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 Titanium.Media.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 Titanium.Media.setOverrideAudioRoute.
AUDIO_SESSION_CATEGORY_PLAYBACK#
Type: 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#
Type: String
Session mode for recording audio; it silences playback audio.
AUDIO_SESSION_CATEGORY_SOLO_AMBIENT#
Type: 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#
Type: Number
Constant that specifies audio should output to the default audio route. See Titanium.Media.setOverrideAudioRoute for more information.
AUDIO_SESSION_OVERRIDE_ROUTE_SPEAKER#
Type: Number
Constant that specifies audio should output to the speaker. See Titanium.Media.setOverrideAudioRoute for more information.
AUDIO_SESSION_PORT_AIRPLAY#
Type: String
Constant for output on a remote Air Play device. This is an output port.
AUDIO_SESSION_PORT_BLUETOOTHA2DP#
Type: String
Constant for output on a Bluetooth A2DP device. This is an output port.
AUDIO_SESSION_PORT_BLUETOOTHHFP#
Type: 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#
Type: String
Constant for output on a Bluetooth Low Energy device. This is an output port. This is available on iOS 7 and later.
AUDIO_SESSION_PORT_BUILTINMIC#
Type: String
Constant for built-in microphone on an iOS device. This is an input port.
AUDIO_SESSION_PORT_BUILTINRECEIVER#
Type: String
Constant for the speaker you hold to your ear when on a phone call. This is an output port.
AUDIO_SESSION_PORT_BUILTINSPEAKER#
Type: String
Constant for built-in speaker on an iOS device. This is an output port.
AUDIO_SESSION_PORT_CARAUDIO#
Type: String
Constant for Input or output via Car Audio. This can be both an input and output port. This is available on iOS 7 and later.
AUDIO_SESSION_PORT_HDMI#
Type: String
Constant for output via High-Definition Multimedia Interface. This is an output port
AUDIO_SESSION_PORT_HEADPHONES#
Type: String
Constant for headphone or headset output. This is an output port.
AUDIO_SESSION_PORT_HEADSETMIC#
Type: String
Constant for microphone on a wired headset. This is an input port.
AUDIO_SESSION_PORT_LINEIN#
Type: String
Constant for line level input on a dock connector. This is an input port.
AUDIO_SESSION_PORT_LINEOUT#
Type: String
Constant for line level output on a dock connector. This is an output port.
AUDIO_SESSION_PORT_USBAUDIO#
Type: String
Constant for input or output on a Universal Serial Bus device. This can be both an input and output port.
audioSessionCategory#
Type: 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#
Type: Array<String>
Array of media type constants supported for the camera.
availableCameras#
Type: Array<Number>
Array indicating which cameras are available, CAMERA_FRONT, CAMERA_REAR or both.
availablePhotoGalleryMediaTypes#
Type: Array<String>
Array of media type constants supported for saving to the device's camera roll or saved images album.
availablePhotoMediaTypes#
Type: Array<String>
Array of media type constants supported for the photo library.
averageMicrophonePower#
Type: Number
Current average microphone level in dB or -1 if microphone monitoring is disabled.
bubbleParent#
Type: 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.
CAMERA_AUTHORIZATION_AUTHORIZED#
Type: Number
Constant specifying that app is authorized to use camera. This is available on iOS 7 and later.
CAMERA_AUTHORIZATION_DENIED#
Type: Number
Constant specifying that app is denied usage of camera. This is available on iOS 7 and later.
CAMERA_AUTHORIZATION_RESTRICTED#
Type: Number
Constant specifying that app is restricted from using camera. This is available on iOS 7 and later.
CAMERA_AUTHORIZATION_UNKNOWN#
Type: Number
Constant specifying that app is not yet authorized to use camera. This is available on iOS 7 and later.
CAMERA_FLASH_AUTO#
Type: Number
Constant specifying to have the device determine to use the flash or not.
cameraOutputSizes#
Type: 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: depending on your phone and camera the values won't be used or can be different.
currentRoute#
Type: RouteDescription
Returns a description of the current route, consisting of zero or more input ports and zero or more output ports.
IMAGE_SCALING_ASPECT_FILL#
Type: Number
Crops the image proportionally causing its content to be clipped either horizontally or vertically.
IMAGE_SCALING_ASPECT_FIT#
Type: Number
Letterbox or pillarbox scales the image proportionally to fit the container.
IMAGE_SCALING_AUTO#
Type: Number
Scales the image depending on how the view container is sized.
If a width and height are both configured on the
image view, then it will use IMAGE_SCALING_FILL
to stretch the image disproportionally to fill the view. Otherwise it will use
IMAGE_SCALING_ASPECT_FIT to letterbox/pillarbox the image.
IMAGE_SCALING_FILL#
Type: Number
Stretches the image disproportionally to completely fill the container's bounds.
lifecycleContainer#
Type: 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.
peakMicrophonePower#
Type: Number
Current microphone level peak power in dB or -1 if microphone monitoring is disabled.
QUALITY_640x480#
Type: 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_HIGH#
Type: Number
Media type constant for high-quality video recording.
Recorded files are suitable for on-device playback and for wired transfer to the
Desktop using Image Capture; they are likely to be too large for transfer using Wi-Fi.
QUALITY_IFRAME_1280x720#
Type: Number
Media type constant for medium-quality video recording.
If recording, specifies that you want to use 1280x720 iFrame format.
QUALITY_IFRAME_960x540#
Type: Number
Media type constant for medium-quality video recording.
If recording, specifies that you want to use 960x540 iFrame format.
QUALITY_LOW#
Type: Number
Media type constant for low-quality video recording.
Recorded files can usually be transferred over the cellular network.
QUALITY_MEDIUM#
Type: Number
Media type constant for medium-quality video recording.
Recorded files can usually be transferred using Wi-Fi. This is the default video
quality setting.
systemMusicPlayer#
Type: Titanium.Media.MusicPlayer
An instance of Titanium.Media.MusicPlayer representing the system-wide music player.
useCameraX#
Type: Boolean
To use the new CameraX classes for "camera with overlay" set useCameraX to true
VIDEO_CONTROL_DEFAULT (deprecated)#
Type: Number
Constant for default video controls.
Used in conjunction with the
mediaControlStyle property
of Titanium.Media.VideoPlayer.
Removed on iOS in SDK 7.0.0.
VIDEO_CONTROL_EMBEDDED (deprecated)#
Type: Number
Constant for video controls for an embedded view.
Used in conjunction with the
mediaControlStyle property
of Titanium.Media.VideoPlayer.
On Android, this constant has the same effect as VIDEO_CONTROL_DEFAULT. Video controls may
only be shown or hidden.
Removed on iOS in SDK 7.0.0.
VIDEO_CONTROL_FULLSCREEN (deprecated)#
Type: Number
Constant for fullscreen video controls.
Used in conjunction with the
mediaControlStyle property
of Titanium.Media.VideoPlayer.
On iOS, use VIDEO_CONTROL_FULLSCREEN when creating a video player that occupies the entire
screen, that is, the parent window should be a fullscreen window
(fullscreen set to true) and the video player should
occupy the entirety of the parent window.
If the user clicks the Done button in the fullscreen control bar, the video player
pauses playback and generates a complete event.
Note that if you create a video player that does not occupy the entire screen, and later
switch to fullscreen mode, the video controls are switched automatically. That is, if
mediaControlStyle is set to VIDEO_CONTROL_DEFAULT or VIDEO_CONTROL_EMBEDDED, it is
automatically switched to the fullscreen controls when the player enters fullscreen mode.
This is true whether the user initiates the mode switch by clicking the fullscreen button
in the embedded controls, or if you programmatically switch to full screen mode (by setting
the fullscreen property to true).
On Android, this constant has the same effect as VIDEO_CONTROL_DEFAULT. Video controls may
only be shown or hidden.
Removed on iOS in SDK 7.0.0.
VIDEO_CONTROL_HIDDEN (deprecated)#
Type: Number
Constant for video controls hidden.
Used in conjunction with the
mediaControlStyle property
of Titanium.Media.VideoPlayer.
Removed on iOS in SDK 7.0.0.
VIDEO_CONTROL_NONE (deprecated)#
Type: Number
Constant for no video controls.
Used in conjunction with the
mediaControlStyle property
of Titanium.Media.VideoPlayer.
Removed on iOS in SDK 7.0.0.
VIDEO_FINISH_REASON_USER_EXITED#
Type: Number
Video playback ended by user action (such as clicking the Done button).
VIDEO_LOAD_STATE_FAILED#
Type: Number
Indicates that the player can no longer play media items because of an error.
VIDEO_PLAYBACK_STATE_SEEKING_BACKWARD#
Type: Number
Video playback is rewinding.
This constant has been removed on iOS in SDK 7.0.0 by using the official Apple AVPlayer that does not expose this functionality so far.
VIDEO_PLAYBACK_STATE_SEEKING_FORWARD#
Type: Number
Video playback is seeking forward.
This constant has been removed on iOS in SDK 7.0.0 by using the official Apple AVPlayer that does not expose this functionality so far.
VIDEO_REPEAT_MODE_ONE#
Type: Number
Constant for repeating one video (e.g., the one video will repeat constantly) during playback.
VIDEO_SCALING_ASPECT_FILL (deprecated)#
Type: Number
Scale video to fill the screen, clipping edges if necessary.
Video is scaled until the video fills the entire screen. Content at the edges
of the larger of the two dimensions is clipped so that the other dimension fits the
screen exactly. The aspect ratio of the movie is preserved.
VIDEO_SCALING_ASPECT_FIT (deprecated)#
Type: Number
Scale video to fit the screen, letterboxing if necessary.
Video is scaled until the larger dimension fits on the screen exactly. In the
other dimension, the region between the edge of the movie and the edge of the screen
is filled with a black bar. The aspect ratio of the movie is preserved.
This constant was removed on iOS in SDK 7.0.0
VIDEO_SCALING_MODE_FILL (deprecated)#
Type: Number
Video is scaled until both dimensions fit the screen exactly, stretching if necessary.
This constant was removed on iOS in SDK 7.0.0
VIDEO_SCALING_NONE (deprecated)#
Type: Number
Video scaling is disabled.
This constant was removed on iOS in SDK 7.0.0
VIDEO_SCALING_RESIZE#
Type: String, Number
Specifies that the video should be stretched to fill the bounds of layer.
This is a String on iOS, a Number on Android.
VIDEO_SCALING_RESIZE_ASPECT#
Type: String, Number
Specifies that the player should preserve the aspect ratio of video and fit the video within the bounds of layer.
This is a String on iOS, a Number on Android.
VIDEO_SCALING_RESIZE_ASPECT_FILL#
Type: String, Number
Specifies that the player should preserve the aspect ratio of video and fill the bounds of layer.
This is a String on iOS, a Number on Android.
VIDEO_TIME_OPTION_NEXT_SYNC#
Type: Number
Use the sync (or key) frame located right after or at given the time.
VIDEO_TIME_OPTION_PREVIOUS_SYNC#
Type: Number
Use the sync (or key) frame located right before or at given the time.
volume#
Type: 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.
Methods #
addEventListener #
Adds the specified callback as an event listener for the named event.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. | No |
applyProperties #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
props | Dictionary | A dictionary of properties to apply. | No |
beep #
Plays a device beep notification.
fireEvent #
Fires a synthesized event to any registered listeners.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. | Yes |
hasAudioPermissions #
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: Boolean
hasAudioRecorderPermissions #
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: Boolean
hasMusicLibraryPermissions #
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: Boolean
hasPhotoGalleryPermissions #
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 Titanium.Media.requestPhotoGalleryPermissions. If you already have the permission and use
Titanium.Media.requestPhotoGalleryPermissions it will call the success event, no second permission request is displayed.
Returns: Boolean
hideCamera #
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.
hideMusicLibrary #
Hides the music library.
Must be called after calling openMusicLibrary
and only when autohide is set to false.
isMediaTypeSupported #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
source | String | Media source specified as a string: camera for Camera or photo for Photo Library. | No |
type | String | Media type to check. | No |
Returns: Boolean
openMusicLibrary #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
options | MusicLibraryOptionsType | A dictionary of options as described in <MusicLibraryOptionsType>. | No |
openPhotoGallery #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
options | PhotoGalleryOptionsType | Photo gallery options as described in <PhotoGalleryOptionsType>. | No |
pauseVideoCapture #
Pauses video capturing.
previewImage #
Displays the given image.
| Name | Type | Summary | Optional |
|---|---|---|---|
options | Dictionary<PreviewImageOptions> | Dictionary containing the image and callback functions. | No |
queryMusicLibrary #
Searches the music library for items matching the specified search predicates.
Use Titanium.Media.hasMusicLibraryPermissions to check the granted permissions and
Titanium.Media.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 Titanium.Media.requestMusicLibraryPermissions.
| Name | Type | Summary | Optional |
|---|---|---|---|
query | MediaQueryType | The query object to extract information from. | No |
Returns: Array<Titanium.Media.Item>
removeEventListener #
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);
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to addEventListener. | No |
requestAudioRecorderPermissions #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
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. | Yes |
Returns: Promise<MediaAuthorizationResponse> — On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
requestCameraPermissions #
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 Titanium.Android.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.
| Name | Type | Summary | Optional |
|---|---|---|---|
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. | Yes |
Returns: Promise<RequestCameraAccessResult> — On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
requestMusicLibraryPermissions #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
callback | Callback<RequestMusicLibraryAccessResult> | Function to call indicating if permission was granted or denied. | No |
requestPhotoGalleryPermissions #
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 Titanium.Media.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 [Titanium.Android.requestPermissions](/api/titanium/android/#request-permissions) and request android.permission.READ_MEDIA_IMAGES.
| Name | Type | Summary | Optional |
|---|---|---|---|
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. | Yes |
Returns: Promise<RequestPhotoGalleryAccessResult> — On SDK 10+, this method will return a `Promise` whose resolved value is equivalent to that passed to the optional callback argument.
resumeVideoCapture #
Resumes video capturing.
saveToPhotoGallery #
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 Titanium.Media.hasPhotoGalleryPermissions
and request the permissions with Titanium.Media.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.
| Name | Type | Summary | Optional |
|---|---|---|---|
media | Titanium.Blob, Titanium.Filesystem.File | Media to save to the camera roll or media gallery. | No |
callbacks | Object | Pass a dictionary with the following supported keys: success a function thatwill be called when the save succeeds, and error a function that will becalled upon receiving an error. | No |
setOverrideAudioRoute #
Overrides the default audio route when using the Titanium.Media.AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD session mode.
By default, when using the Titanium.Media.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.
| Name | Type | Summary | Optional |
|---|---|---|---|
route | Number | The specified audio route. | No |
showCamera #
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
autohidetofalseand then set the
overlayproperty 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
saveToPhotoGallerytofalseis 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 Titanium.Media.hasCameraPermissions and Titanium.Media.requestCameraPermissions
to ask for camera permissions. This is especially important when running on iOS 10 and later, since
the application may crash otherwise.
| Name | Type | Summary | Optional |
|---|---|---|---|
options | CameraOptionsType | A dictionary of camera options as described in <CameraOptionsType>. | No |
startMicrophoneMonitor #
Starts monitoring the microphone sound level.
startVideoCapture #
Starts video capture using the camera specified.
stopMicrophoneMonitor #
Stops monitoring the microphone sound level.
stopVideoCapture #
Stops video capture using the camera specified.
switchCamera #
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 Titanium.Media.showCamera).
| Name | Type | Summary | Optional |
|---|---|---|---|
camera | Number | Constant indicating to which camera you want to switch. | No |
takePicture #
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.
takeScreenshot #
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
Blob object.
| Name | Type | Summary | Optional |
|---|---|---|---|
callback | Callback<ScreenshotResult> | Function to call upon capture. | No |
vibrate #
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).
| Name | Type | Summary | Optional |
|---|---|---|---|
pattern | Array<Number> | Array of values identifying a vibrate pattern (only used on Android). | Yes |
Events #
cameraready #
Fires when the camera overlay is ready to take pictures.
routechange #
Fired when an audio line type change is detected.
| Name | Type | Summary |
|---|---|---|
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. |
volume #
Fired when the volume output changes.
| Name | Type | Summary |
|---|---|---|
volume | Number | New volume level in dB. |