# Titanium.Media

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

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.

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.

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.

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.

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

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

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.

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

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.

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.

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);

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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