Titanium SDK 媒体模块深度解析与应用指南

Titanium SDK 媒体模块深度解析与应用指南

概述

Titanium.Media 模块是 Titanium SDK 中处理设备多媒体功能的核心模块，它为开发者提供了访问设备相机、相册、音频录制与播放等多媒体功能的统一接口。本文将深入解析该模块的各项功能，并提供实用的开发指南。

核心功能详解

1. 音频相关功能

beep() - 播放系统提示音

• 简单调用即可播放设备默认提示音
• 适用于操作反馈或提醒场景

音频路由控制

• setOverrideAudioRoute() 方法可控制音频输出路径
• 特别适用于需要切换扬声器/听筒的场景
• 支持常量：AUDIO_SESSION_OVERRIDE_ROUTE_SPEAKER 和 AUDIO_SESSION_OVERRIDE_ROUTE_NONE

麦克风监控

• startMicrophoneMonitor() 和 stopMicrophoneMonitor() 方法
• 可用于实现声音电平检测或语音激活功能

2. 相机功能

showCamera() - 调用系统相机

• 支持自定义覆盖视图(overlay)
• 可控制是否自动隐藏相机界面
• 平台差异：
  • Android：需通过设置 autohide=false 来禁用默认控件
  • iOS：需设置 showControls=false 和 autohide=false

相机控制方法

• takePicture()：拍照
• switchCamera()：切换前后摄像头
• hideCamera()：隐藏相机界面

视频录制控制

• startVideoCapture() 和 stopVideoCapture()：视频录制启停
• pauseVideoCapture() 和 resumeVideoCapture()：视频录制暂停与恢复(仅Android)

3. 媒体库访问

相册访问

• openPhotoGallery()：打开相册选择图片
• saveToPhotoGallery()：保存媒体到相册
  • 支持 Blob 或 File 对象
  • 注意文件扩展名必须正确

音乐库访问

• openMusicLibrary()：打开音乐库
• queryMusicLibrary()：查询音乐库内容
• hideMusicLibrary()：隐藏音乐库界面

权限管理最佳实践

1. 相机权限

if (!Titanium.Media.hasCameraPermissions()) {
    Titanium.Media.requestCameraPermissions(function(e) {
        if (e.success) {
            // 权限已授予
        } else {
            // 处理权限被拒绝的情况
        }
    });
}

• iOS 需要 NSCameraUsageDescription 和 NSMicrophoneUsageDescription(录制视频时)
• Android 需要 CAMERA、READ_EXTERNAL_STORAGE 和 WRITE_EXTERNAL_STORAGE 权限

2. 相册权限

if (!Titanium.Media.hasPhotoGalleryPermissions()) {
    Titanium.Media.requestPhotoGalleryPermissions(function(e) {
        // 处理权限结果
    });
}

• iOS 需要 NSPhotoLibraryUsageDescription
• Android 13+ 需要 READ_MEDIA_IMAGES 和 READ_MEDIA_VIDEO

3. 音乐库权限

if (!Titanium.Media.hasMusicLibraryPermissions()) {
    Titanium.Media.requestMusicLibraryPermissions(function(e) {
        // 处理权限结果
    });
}

• iOS 9.3+ 需要 NSAppleMusicUsageDescription

实用技巧与注意事项

1. 媒体类型检查：使用 isMediaTypeSupported() 方法检查设备是否支持特定媒体类型

2. Android 视频保存：

   • 6.1.0 之前版本不支持直接保存视频到相册
   • 可考虑先将视频保存为 .mov 格式

3. iOS 地理信息限制：

   • 相机拍摄的照片不会包含准确的地理位置信息
   • 需要额外获取位置信息并手动添加到图片元数据

4. 自定义相机界面：

   • 通过 overlay 属性添加自定义控件
   • 需要配合 autohide=false 使用

5. 媒体保存回调：

   • saveToPhotoGallery() 是异步操作
   • 务必实现 success 和 error 回调处理结果

结语

Titanium.Media 模块提供了强大的多媒体功能支持，通过合理使用这些API，开发者可以轻松实现丰富的媒体相关功能。在实际开发中，务必注意各平台的差异和权限要求，特别是在较新的iOS和Android版本上，正确的权限配置是功能正常工作的前提。