@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-howtos/references/media-apis.md

@@ -1,268 +1,148 @@
-# Media APIs
+# Media
 
-## 1. Audio APIs
+Based on the [current official guide](https://titaniumsdk.com/docs/build/media.md). Examples target released SDK 13.4.1; verify the selected SDK before adopting version-specific behavior.
 
-### Playing basic sounds (Ti.Media.Sound)
-- Use for short effects, beeps, ambient audio
-- The entire file loads into memory. Use `preload=true` to reduce delay.
-- Methods: `play()`, `pause()`, `stop()`, `setVolume()`
-- `allowBackground=true` keeps playback going when the app closes
+Camera, library access and recording need their matching permissions. Playing an app-owned audio or video file does not itself require camera, microphone or music-library permission.
 
-```javascript
-const sound = Ti.Media.createSound({
-  url: 'beep.mp3',
-  preload: true
-});
-sound.play();
-```
-
-### Streaming audio (Ti.Media.AudioPlayer)
-- Use for streaming web URLs (MP3, HLS)
-- Supports pseudo-streaming and HLS
-- Handle interruptions (phone calls) with app-level events:
-  - `pause`: call `setPaused(true)` or `pause()`
-  - `resume`: call `setPaused(false)` or `start()`
-
-```javascript
-const streamer = Ti.Media.createAudioPlayer({ url: 'https://example.com/stream.mp3' });
-streamer.start();
-
-Ti.App.addEventListener('pause', () => { streamer.setPaused(true); });
-Ti.App.addEventListener('resume', () => { streamer.setPaused(false); });
-```
-
-### Recording audio (Ti.Media.AudioRecorder)
-- Requires microphone permission
-- Properties:
-  - `compression`: `Ti.Media.AUDIO_FORMAT_ULAW` (low-fi) or `AUDIO_FORMAT_LINEAR_PCM` (hi-fi)
-  - `format`: `Ti.Media.AUDIO_FILEFORMAT_WAVE`
-- Methods: `start()`, `pause()`/`resume()`, `stop()`
-
-## 2. Video APIs (Ti.Media.VideoPlayer)
+## Ask first
 
-### Cross-platform considerations
-- Android: must be fullscreen (Intent-based, not a view proxy)
-- iOS: can be embedded or fullscreen; set `height` and `width` for embedded
+Each capability has a matching pair of methods.
 
-### Basic usage
-- `url`: local file path or remote URL
-- `autoplay=true`: auto-start when rendered
-- `movieControlStyle`: `Ti.Media.VIDEO_CONTROL_EMBEDDED` for embedded controls
-- `scalingMode`: control fill/fit behavior
-
-```javascript
-const videoPlayer = Ti.Media.createVideoPlayer({
-  url: 'movie.mp4',
-  scalingMode: Ti.Media.VIDEO_SCALING_ASPECT_FIT // or ASPECT_FILL, MODE_FILL, NONE
-});
-```
-
-```javascript
-const player = Ti.Media.createVideoPlayer({
-  url: 'movie.mp4',
-  movieControlStyle: Ti.Media.VIDEO_CONTROL_EMBEDDED,
-  autoplay: true
-});
-
-// iOS only: add to window
-if (Ti.Platform.osname === 'iphone' || Ti.Platform.osname === 'ipad') {
-  win.add(player);
-}
+| Capability | Check | Ask |
+| ---------- | ----- | --- |
+| Camera | `Ti.Media.hasCameraPermissions()` | `requestCameraPermissions()` |
+| Photo library | `hasPhotoGalleryPermissions()` | `requestPhotoGalleryPermissions()` |
+| Microphone | `hasAudioRecorderPermissions()` | `requestAudioRecorderPermissions()` |
+| Music library (iOS) | `hasMusicLibraryPermissions()` | `requestMusicLibraryPermissions()` |
 
-// Stop when window closes
-win.addEventListener('close', () => { player.stop(); });
-```
-
-### Key events
-- `complete`: playback ended (check `e.reason` vs `Ti.Media.VIDEO_FINISH_REASON_PLAYBACK_ENDED`)
-- `load`: movie finished loading
-- `fullscreen`: entered/exited fullscreen (check `e.entering`)
-
-## 3. Camera and photo gallery APIs
-
-### Camera availability and permissions
-Always check device support and permissions before opening the camera:
-
-```javascript
-if (!Ti.Media.isCameraSupported) {
-  Ti.API.warn('No camera available on this device');
-  return;
-}
-
-if (Ti.Media.hasCameraPermissions()) {
-  openCamera();
-} else {
+```js
+function withCamera(done) {
+  if (Ti.Media.hasCameraPermissions()) {
+    done();
+    return;
+  }
   Ti.Media.requestCameraPermissions((e) => {
     if (e.success) {
-      openCamera();
+      done();
     } else {
-      Ti.API.error('Camera permission denied');
+      Ti.API.warn('camera denied');
     }
   });
 }
 ```
 
-Required `tiapp.xml` keys (iOS):
+iOS also needs a usage string in `tiapp.xml`, and a missing required usage description can terminate the app when the protected API is accessed:
 
 ```xml
-<key>NSCameraUsageDescription</key>
-<string>We need camera access to take photos</string>
-<key>NSPhotoLibraryUsageDescription</key>
-<string>We need photo library access to save photos</string>
+<ios>
+  <plist>
+    <dict>
+      <key>NSCameraUsageDescription</key>
+      <string>Attach a photo to a note.</string>
+      <key>NSPhotoLibraryUsageDescription</key>
+      <string>Choose a photo to attach to a note.</string>
+      <key>NSMicrophoneUsageDescription</key>
+      <string>Record a voice note.</string>
+    </dict>
+  </plist>
+</ios>
 ```
 
-### Camera (Ti.Media.showCamera)
-- Requires camera permission and usage descriptions
-- Success callback provides `event.media` (Blob)
-- Use `saveToPhotoGallery: true` to auto-save
-- Handle `cancel` and `error` callbacks
+Write the real reason. "Required by the app" is the string reviewers reject.
 
-### Front and rear camera
-```javascript
-const cameras = Ti.Media.availableCameras;
+## The camera
 
-// Check if front camera exists
-if (cameras.indexOf(Ti.Media.CAMERA_FRONT) !== -1) {
-  Ti.Media.showCamera({
-    whichCamera: Ti.Media.CAMERA_FRONT,
-    // ... other options
-  });
-}
-
-// Switch camera programmatically
-Ti.Media.switchCamera(Ti.Media.CAMERA_REAR);
+```js
+Ti.Media.showCamera({
+  mediaTypes: [Ti.Media.MEDIA_TYPE_PHOTO],
+  saveToPhotoGallery: false,
+  success(e) {
+    const image = Ti.UI.createImageView({ image: e.media, width: 200, height: 200 });
+    win.add(image);
+  },
+  cancel() {},
+  error(e) {
+    Ti.API.error(e.error);
+  }
+});
 ```
 
-### Advanced camera options (iOS)
-| Property               | Description                                     |
-| ---------------------- | ----------------------------------------------- |
-| `autohide`             | Auto-hide camera after capture (default: true)  |
-| `animated`             | Animate camera appearance                       |
-| `allowEditing`         | Allow user to crop/edit after capture           |
-| `mediaTypes`           | Array: `MEDIA_TYPE_PHOTO`, `MEDIA_TYPE_VIDEO`   |
-| `videoMaximumDuration` | Max video duration in milliseconds              |
-| `videoQuality`         | `QUALITY_HIGH`, `QUALITY_MEDIUM`, `QUALITY_LOW` |
-| `overlay`              | Custom `Ti.UI.View` overlay on camera           |
-| `showControls`         | Show/hide default camera controls               |
+`e.media` is a `Blob`. Assign it straight to an `ImageView`, or write it to a
+file with `Ti.Filesystem`.
 
-When using a custom overlay, call `Ti.Media.takePicture()` to capture and `Ti.Media.hideCamera()` to dismiss.
+`saveToPhotoGallery` defaults to false, so a photo your app took exists only in
+that blob until you save it somewhere. Write it to
+`applicationDataDirectory` if it needs to outlive the screen.
 
-### Gallery (Ti.Media.openPhotoGallery)
-- Success callback provides `event.media` (Blob)
-- Note: `event.media` may only contain file info. Use `Ti.Filesystem.getFile(event.media.nativePath)` to access the actual file.
+Close the camera with `Ti.Media.hideCamera()` when you dismiss it yourself.
 
-### iPad-specific gallery options
-On iPad, the photo gallery opens as a popover. Configure its position:
+## The photo library
 
-```javascript
+```js
 Ti.Media.openPhotoGallery({
-  popoverView: myButton, // Anchor popover to this view
-  arrowDirection: Ti.UI.iPad.POPOVER_ARROW_DIRECTION_UP,
-  success: (e) => { /* ... */ }
-});
-```
-
-### Memory management
-Use `imageAsResized()` on blobs to avoid memory exhaustion. Resize to target dimensions before assigning to an ImageView.
-
-```javascript
-Ti.Media.showCamera({
-  success: (event) => {
-    const blob = event.media.imageAsResized(800, 600);
-    imageView.image = blob;
+  mediaTypes: [Ti.Media.MEDIA_TYPE_PHOTO],
+  allowMultiple: false,
+  success(e) {
+    // Single selection returns a media Blob, whose length is bytes, not item count.
+    Ti.API.info('Picked one item');
   },
-  cancel: () => { Ti.API.info('Camera canceled'); },
-  error: (e) => { Ti.API.error(`Camera error: ${e.error}`); }
+  cancel() {}
 });
 ```
 
-## 4. Images and ImageView APIs
+With `allowMultiple: true` the success event carries an `images` array instead
+of a single `media`, which is the shape change to handle rather than assume.
 
-### Background images
-- Scaled to fit component dimensions by default
-- iOS: use `backgroundLeftCap` and `backgroundTopCap` to control stretch regions
-- Android: supports remote URLs as background images; iOS does not
+## Audio
 
-### Image stretching (background images)
-When using small images as backgrounds, iOS and Android stretch differently:
-- `backgroundLeftCap` (iOS): pixels from the left that are not stretched. The middle section stretches.
-- `backgroundTopCap` (iOS): pixels from the top that are not stretched.
-- Android: supports remote URLs for background images; iOS does not.
+Three objects, for three jobs.
 
-### ImageView component
-- `image` accepts: URL, local path, or `Ti.Filesystem.File`
-- Scaling behavior:
-  - Both `height` and `width` specified: unproportional scale (aspect ratio not maintained)
-  - Only one dimension specified: proportional scale (aspect ratio maintained)
-- `defaultImage`: local image to show while remote image loads
+| Object | For |
+| ------ | --- |
+| `Ti.Media.Sound` | Short effects, held in memory |
+| `Ti.Media.AudioPlayer` | Long files and streams |
+| `Ti.Media.AudioRecorder` | Recording |
 
-### Density-specific images
-
-Android: place in resolution-specific directories:
-- `res-ldpi`, `res-mdpi`, `res-hdpi`, `res-xhdpi`, `res-xxhdpi`, `res-xxxhdpi`
+```js
+const sound = Ti.Media.createSound({ url: '/audio/tap.wav' });
+sound.play();
 
-iOS: use naming convention:
-- `foo.png` - non-retina
-- `foo@2x.png` - retina
-- `foo@3x.png` - iPhone 6 Plus
-- `foo~iphone.png` - iPhone-specific
-- `foo~ipad.png` - iPad-specific
+const player = Ti.Media.createAudioPlayer({ url: 'https://example.com/talk.mp3' });
+player.addEventListener('change', (e) => Ti.API.info(e.description));
+player.start();
+```
 
-For remote density-specific images on iOS:
+`Sound` loads the whole file, so it is for something short. `AudioPlayer`
+buffers, which is what you want for anything longer than a notification chime.
 
-```javascript
-const density = Ti.Platform.displayCaps.logicalDensityFactor;
-const url = `https://example.com/image@${density}x.png`;
-const imageView = Ti.UI.createImageView({
-  image: url,
-  hires: true // Indicates high-resolution remote image
-});
-```
+For audio that continues when the app is backgrounded, set
+`Ti.Media.audioSessionCategory` and declare background audio in `tiapp.xml`.
+On iOS configure both for background audio; these settings do not keep playback alive after process termination.
 
-### Flipbook animations
-- Assign an array of images to `images`
-- `duration`: milliseconds between frames
-- `repeatCount`: 0 = infinite, >1 = specific count
+## Video
 
-```javascript
-const frames = [];
-for (let i = 1; i < 18; i++) {
-  frames.push(`frame${i}.png`);
-}
-const animationView = Ti.UI.createImageView({
-  images: frames,
-  duration: 100,
-  repeatCount: 0
+```js
+const video = Ti.Media.createVideoPlayer({
+  url: 'https://example.com/clip.mp4',
+  width: Ti.UI.FILL,
+  height: 240,
+  autoplay: true
+});
+win.add(video);
+win.addEventListener('close', () => {
+  video.stop();
+  video.release();
 });
-// animationView.stop() / animationView.start() to control
 ```
 
-## Permissions checklist
+A `VideoPlayer` is a view, so it lays out like any other and defaults to
+filling its parent. Release it when the window closes: it holds a decoder, and
+leaving it alive costs memory that the platform will eventually take back by
+killing the app.
 
-### iOS (tiapp.xml)
-```xml
-<ios>
-  <plist>
-    <dict>
-      <key>NSCameraUsageDescription</key>
-      <string>Need camera to take photos</string>
-      <key>NSPhotoLibraryUsageDescription</key>
-      <string>Need photo library access</string>
-      <key>NSMicrophoneUsageDescription</key>
-      <string>Need microphone for audio recording</string>
-    </dict>
-  </plist>
-</ios>
-```
+## Next
 
-### Android (tiapp.xml)
-```xml
-<android>
-  <manifest>
-    <uses-permission android:name="android.permission.CAMERA"/>
-    <uses-permission android:name="android.permission.RECORD_AUDIO"/>
-    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
-    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
-  </manifest>
-</android>
-```
+[Location and maps](https://titaniumsdk.com/docs/build/location.md) covers the other capability that
+needs asking first.
+
+Contract corrections: [released Media API](https://github.com/tidev/titanium-sdk/blob/13_4_1_GA/apidoc/Titanium/Media/Media.yml), [VideoPlayer](https://github.com/tidev/titanium-sdk/blob/13_4_1_GA/apidoc/Titanium/Media/VideoPlayer.yml).