Titanium.Media.Sound 音频播放模块详解

Titanium.Media.Sound 音频播放模块详解

titanium-sdk 🚀 Native iOS and Android Apps with JavaScript 项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk

概述

Titanium.Media.Sound 是 Titanium SDK 中用于播放基础音频资源的对象模块。它提供了一套完整的 API 让开发者能够在移动应用中实现音频播放功能。与流媒体播放器不同，Sound 对象会将整个音频资源加载到内存中再进行播放，因此更适合播放本地或较小的音频文件。

核心特性

1. 支持多种音频格式：能够播放目标平台支持的所有音频格式
2. 基础播放控制：提供播放、暂停、停止等基本功能
3. 播放状态管理：可获取当前播放状态和进度
4. 音量控制：支持0.0（静音）到1.0（最大）的音量调节
5. 循环播放：支持设置音频循环播放

创建 Sound 对象

要使用 Sound 功能，首先需要创建一个 Sound 对象：

var sound = Ti.Media.createSound({
    url: 'audio.mp3',  // 音频文件路径
    volume: 0.8,      // 初始音量
    looping: false    // 是否循环播放
});

常用方法详解

播放控制

1. play() - 开始播放音频或恢复暂停的音频

   sound.play();
   

2. pause() - 暂停当前播放

   sound.pause();
   

3. stop() - 停止播放并重置播放位置到开头

   sound.stop();
   

4. reset() - 重置播放位置到开头但不停止播放

   sound.reset();
   

状态获取

1. playing 属性 - 获取当前是否正在播放

   if (sound.playing) {
       console.log('音频正在播放');
   }
   

2. paused 属性 - 获取当前是否处于暂停状态

   if (sound.paused) {
       console.log('音频已暂停');
   }
   

3. time 属性 - 获取或设置当前播放位置（毫秒）

   // 获取当前位置
   var currentPosition = sound.time;
   
   // 跳转到指定位置
   sound.time = 30000; // 跳转到30秒处
   

高级功能

循环播放

设置 looping 属性可以控制音频是否循环播放：

sound.looping = true; // 开启循环播放

音量控制

通过 volume 属性可以调整音量（0.0-1.0）：

sound.volume = 0.5; // 设置为50%音量

后台播放（Android）

在 Android 平台上，可以通过 allowBackground 属性设置音频是否在应用进入后台时继续播放：

var sound = Ti.Media.createSound({
    url: 'bgmusic.mp3',
    allowBackground: true // 允许后台播放
});

事件处理

Sound 对象提供了多种事件来响应播放状态变化：

1. complete - 音频播放完成时触发

   sound.addEventListener('complete', function(e) {
       if (e.success) {
           console.log('播放完成');
       } else {
           console.log('播放出错:', e.error);
       }
   });
   

2. error - 播放出错时触发

   sound.addEventListener('error', function(e) {
       console.error('播放错误:', e.error);
   });
   

3. interrupted (iOS/macOS) - 播放被中断时触发（如来电）

   sound.addEventListener('interrupted', function() {
       console.log('播放被中断');
   });
   

4. resume (iOS/macOS) - 中断后恢复播放时触发

   sound.addEventListener('resume', function(e) {
       console.log('播放恢复', e.interruption ? '来自中断' : '');
   });
   

最佳实践

1. 资源释放：对于大型音频文件，播放完成后调用 release() 方法释放资源

   sound.addEventListener('complete', function() {
       sound.release();
   });
   

2. 错误处理：始终添加错误事件监听器以处理可能的播放问题

3. 平台差异：

   • iOS 上 time 属性单位为秒（3.0之前）或毫秒（3.0之后）
   • Android 上 duration 属性只能在音频初始化后获取

4. 性能考虑：对于大文件或需要流式播放的场景，考虑使用 AudioPlayer 而非 Sound 对象

总结

Titanium.Media.Sound 提供了简单易用的音频播放功能，适合大多数基础音频播放需求。通过合理使用其API和事件系统，开发者可以轻松实现各种音频播放场景，从简单的音效播放到背景音乐控制。记住根据实际需求选择 Sound 或 AudioPlayer，并注意不同平台间的行为差异，可以构建出更加稳定高效的音频功能。

titanium-sdk 🚀 Native iOS and Android Apps with JavaScript 项目地址: https://gitcode.com/gh_mirrors/ti/titanium-sdk