Titanium.Media

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.

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.

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.

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.

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

See startMicrophoneMonitor, stopMicrophoneMonitor.

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.

See startMicrophoneMonitor, stopMicrophoneMonitor.

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

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.

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

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

Recorded files can usually be transferred over the cellular network.

Recorded files can usually be transferred using Wi-Fi. This is the default video quality setting.

Used in conjunction with the mediaControlStyle property of Titanium.Media.VideoPlayer.

Removed on iOS in SDK 7.0.0.

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.

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.

Used in conjunction with the mediaControlStyle property of Titanium.Media.VideoPlayer.

Removed on iOS in SDK 7.0.0.

Used in conjunction with the mediaControlStyle property of Titanium.Media.VideoPlayer.

Removed on iOS in SDK 7.0.0.

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.

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

This constant was removed on iOS in SDK 7.0.0

This constant was removed on iOS in SDK 7.0.0

This is a String on iOS, a Number on Android.

This is a String on iOS, a Number on Android.

This is a String on iOS, a Number on Android.

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

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

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

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

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

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.

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

In Android, this can only be called when using a custom overlay (see Titanium.Media.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 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).