UniApp中的背景音频播放：深入理解uni.getBackgroundAudioManager()

前言

在移动应用开发中，背景音频播放是一个常见需求，比如音乐播放器、有声读物等应用场景。UniApp提供了强大的背景音频管理器API：uni.getBackgroundAudioManager()，本文将深入探讨如何使用这个API来实现完整的背景音频播放功能。

基础概念

背景音频管理器支持后台播放，即用户离开应用后仍然可以继续播放音频。这与前台音频播放（使用uni.createInnerAudioContext()）的主要区别在于：

• 支持后台持续播放
• 会在系统控制中心显示音乐播放控件
• 支持锁屏界面显示音乐信息
• 具有更完整的状态管理和事件系统

基础使用方法

1. 获取背景音频管理器实例

const backgroundAudioManager = uni.getBackgroundAudioManager();

2. 设置音频信息

// 设置音频标题，必填
backgroundAudioManager.title = '歌曲名称';
// 设置音频描述
backgroundAudioManager.description = '歌曲描述';
// 设置音频歌手
backgroundAudioManager.singer = '演唱者';
// 设置音频封面图URL
backgroundAudioManager.coverImgUrl = 'https://example.com/cover.jpg';
// 设置音频文件URL，必填
backgroundAudioManager.src = 'https://example.com/music.mp3';

完整示例

下面是一个完整的音乐播放器组件示例：

<template>
  <view class="audio-player">
    <view class="cover">
      <image :src="currentSong.coverImg" mode="aspectFill"></image>
    </view>
    
    <view class="info">
      <text class="title">{{currentSong.title}}</text>
      <text class="singer">{{currentSong.singer}}</text>
    </view>
    
    <view class="progress">
      <slider :value="progress" @change="onProgressChange" step="1" />
      <view class="time">
        <text>{{formatTime(currentTime)}}</text>
        <text>{{formatTime(duration)}}</text>
      </view>
    </view>
    
    <view class="controls">
      <button @tap="onPrev">上一首</button>
      <button @tap="onPlayPause">
        {{isPlaying ? '暂停' : '播放'}}
      </button>
      <button @tap="onNext">下一首</button>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      backgroundAudioManager: null,
      isPlaying: false,
      currentTime: 0,
      duration: 0,
      progress: 0,
      currentSong: {
        title: '示例歌曲',
        singer: '演唱者',
        coverImg: '/static/default-cover.png',
        src: ''
      },
      playlist: [
        // 播放列表数据
      ]
    }
  },
  
  onLoad() {
    this.initAudioManager();
  },
  
  methods: {
    initAudioManager() {
      // 获取背景音频管理器实例
      this.backgroundAudioManager = uni.getBackgroundAudioManager();
      
      // 监听播放状态
      this.backgroundAudioManager.onPlay(() => {
        this.isPlaying = true;
        console.log('音频播放');
      });
      
      this.backgroundAudioManager.onPause(() => {
        this.isPlaying = false;
        console.log('音频暂停');
      });
      
      // 监听播放进度
      this.backgroundAudioManager.onTimeUpdate(() => {
        this.currentTime = this.backgroundAudioManager.currentTime;
        this.duration = this.backgroundAudioManager.duration;
        this.progress = (this.currentTime / this.duration) * 100;
      });
      
      // 监听播放结束
      this.backgroundAudioManager.onEnded(() => {
        console.log('音频播放结束');
        this.onNext(); // 播放下一首
      });
      
      // 监听播放错误
      this.backgroundAudioManager.onError((res) => {
        console.error('播放错误：', res.errMsg);
        uni.showToast({
          title: '播放出错，请稍后重试',
          icon: 'none'
        });
      });
    },
    
    // 播放音频
    playSong(song) {
      const backgroundAudioManager = this.backgroundAudioManager;
      
      backgroundAudioManager.title = song.title;
      backgroundAudioManager.singer = song.singer;
      backgroundAudioManager.coverImgUrl = song.coverImg;
      backgroundAudioManager.src = song.src; // 设置了 src 之后会自动播放
      
      // 更新当前歌曲信息
      this.currentSong = song;
    },
    
    // 播放/暂停切换
    onPlayPause() {
      if (this.isPlaying) {
        this.backgroundAudioManager.pause();
      } else {
        this.backgroundAudioManager.play();
      }
    },
    
    // 播放上一首
    onPrev() {
      // 实现播放上一首的逻辑
    },
    
    // 播放下一首
    onNext() {
      // 实现播放下一首的逻辑
    },
    
    // 进度条改变
    onProgressChange(e) {
      const value = e.detail.value;
      const targetTime = (this.duration * value) / 100;
      this.backgroundAudioManager.seek(targetTime);
    },
    
    // 格式化时间
    formatTime(time) {
      const minutes = Math.floor(time / 60);
      const seconds = Math.floor(time % 60);
      return `${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
    }
  }
}
</script>

<style>
.audio-player {
  padding: 20px;
}

.cover {
  width: 200px;
  height: 200px;
  margin: 0 auto;
  border-radius: 8px;
  overflow: hidden;
}

.cover image {
  width: 100%;
  height: 100%;
}

.info {
  text-align: center;
  margin: 20px 0;
}

.title {
  font-size: 18px;
  font-weight: bold;
}

.singer {
  font-size: 14px;
  color: #666;
  margin-top: 5px;
}

.progress {
  margin: 20px 0;
}

.time {
  display: flex;
  justify-content: space-between;
  font-size: 12px;
  color: #999;
  margin-top: 5px;
}

.controls {
  display: flex;
  justify-content: space-around;
  margin-top: 30px;
}
</style>

高级功能实现

1. 播放列表管理

export default {
  data() {
    return {
      playlist: [],
      currentIndex: 0
    }
  },
  
  methods: {
    // 播放指定索引的歌曲
    playByIndex(index) {
      if (index < 0 || index >= this.playlist.length) return;
      
      this.currentIndex = index;
      this.playSong(this.playlist[index]);
    },
    
    // 上一首
    onPrev() {
      let index = this.currentIndex - 1;
      if (index < 0) index = this.playlist.length - 1;
      this.playByIndex(index);
    },
    
    // 下一首
    onNext() {
      let index = this.currentIndex + 1;
      if (index >= this.playlist.length) index = 0;
      this.playByIndex(index);
    }
  }
}

2. 播放模式管理

export default {
  data() {
    return {
      playMode: 'sequence', // sequence-顺序播放 random-随机播放 single-单曲循环
    }
  },
  
  methods: {
    // 切换播放模式
    togglePlayMode() {
      const modes = ['sequence', 'random', 'single'];
      const currentIndex = modes.indexOf(this.playMode);
      const nextIndex = (currentIndex + 1) % modes.length;
      this.playMode = modes[nextIndex];
      
      // 提示当前播放模式
      const modeText = {
        sequence: '顺序播放',
        random: '随机播放',
        single: '单曲循环'
      };
      
      uni.showToast({
        title: modeText[this.playMode],
        icon: 'none'
      });
    },
    
    // 获取下一首歌曲的索引
    getNextIndex() {
      switch (this.playMode) {
        case 'sequence':
          return (this.currentIndex + 1) % this.playlist.length;
        case 'random':
          return Math.floor(Math.random() * this.playlist.length);
        case 'single':
          return this.currentIndex;
        default:
          return 0;
      }
    }
  }
}

3. 播放状态持久化

export default {
  methods: {
    // 保存播放状态
    savePlayState() {
      const state = {
        currentIndex: this.currentIndex,
        playMode: this.playMode,
        currentTime: this.backgroundAudioManager.currentTime
      };
      
      uni.setStorageSync('audioPlayerState', state);
    },
    
    // 恢复播放状态
    restorePlayState() {
      const state = uni.getStorageSync('audioPlayerState');
      if (!state) return;
      
      this.currentIndex = state.currentIndex;
      this.playMode = state.playMode;
      
      // 恢复播放
      const song = this.playlist[this.currentIndex];
      if (song) {
        this.playSong(song);
        // 恢复播放进度
        setTimeout(() => {
          this.backgroundAudioManager.seek(state.currentTime);
        }, 1000); // 延迟seek以确保音频已加载
      }
    }
  },
  
  onShow() {
    this.restorePlayState();
  },
  
  onHide() {
    this.savePlayState();
  }
}

性能优化建议

1. 资源预加载

   // 预加载下一首歌曲的封面图
   preloadNextSong() {
     const nextIndex = this.getNextIndex();
     const nextSong = this.playlist[nextIndex];
     if (nextSong && nextSong.coverImg) {
       uni.getImageInfo({
         src: nextSong.coverImg,
         success: () => {
           console.log('下一首歌曲封面预加载成功');
         }
       });
     }
   }

2. 状态管理优化

   // 使用防抖处理进度更新
   onTimeUpdate() {
     if (this.progressUpdateTimer) clearTimeout(this.progressUpdateTimer);
     
     this.progressUpdateTimer = setTimeout(() => {
       this.currentTime = this.backgroundAudioManager.currentTime;
       this.duration = this.backgroundAudioManager.duration;
       this.progress = (this.currentTime / this.duration) * 100;
     }, 1000 / 60); // 约60fps的更新频率
   }

常见问题解决方案

1. 音频无法播放

// 播放前检查音频可用性
async checkAudioAvailable(src) {
  try {
    const result = await uni.request({
      url: src,
      method: 'HEAD'
    });
    return result.statusCode === 200;
  } catch (error) {
    console.error('音频文件检查失败：', error);
    return false;
  }
}

async playSong(song) {
  const isAvailable = await this.checkAudioAvailable(song.src);
  if (!isAvailable) {
    uni.showToast({
      title: '音频文件不可用',
      icon: 'none'
    });
    return;
  }
  
  // 继续正常的播放逻辑...
}

 2. 播放状态不同步

// 定期同步播放状态
initStateSync() {
  setInterval(() => {
    const systemPlayState = this.backgroundAudioManager.paused;
    if (this.isPlaying === systemPlayState) {
      this.isPlaying = !systemPlayState;
    }
  }, 1000);
}

平台差异说明

1. iOS平台

• 需要在manifest.json中配置background-audio权限
• 锁屏界面显示的封面图需要使用https链接

1. Android平台

• 后台播放可能受到系统限制
• 某些机型可能需要申请特殊权限

  // manifest.json
  {
    "app-plus": {
      "distribute": {
        "ios": {
          "capabilities": {
            "background-audio": true
          }
        }
      }
    }
  }

总结

通过本文，我们深入了解了uni.getBackgroundAudioManager()的使用方法和最佳实践。从基础播放控制到高级功能实现，再到性能优化和问题解决，相信这些内容能帮助你更好地开发音频相关功能。

关键要点回顾：

1. 背景音频管理器支持后台播放
2. 完整的事件系统支持精确控制
3. 播放状态管理和持久化很重要
4. 需要注意平台差异性
5. 性能优化对用户体验至关重要

 

参考资料

• UniApp官方文档 - 背景音频播放管理器
• HTML5 Audio API 参考
• iOS 音频会话编程指南
• Android 媒体播放指南

扩展阅读

1. 音频格式支持

不同平台支持的音频格式有所不同，建议使用通用格式：

• MP3 (.mp3)
• AAC (.m4a)
• WAV (.wav)

2. 音频缓存策略

// 实现音频文件缓存
export class AudioCache {
  constructor() {
    this.cacheDir = 'audio_cache/';
    this.cacheMap = new Map();
  }
  
  // 获取缓存音频
  async getAudio(url) {
    const cacheKey = this.getCacheKey(url);
    
    try {
      const cachePath = await this.getCachePath(cacheKey);
      if (cachePath) {
        console.log('使用缓存音频');
        return cachePath;
      }
      
      console.log('下载音频文件');
      return await this.downloadAudio(url, cacheKey);
    } catch (error) {
      console.error('获取音频失败：', error);
      return url; // 失败时返回原始URL
    }
  }
  
  // 生成缓存键
  getCacheKey(url) {
    return encodeURIComponent(url);
  }
  
  // 检查缓存是否存在
  async getCachePath(cacheKey) {
    try {
      const cacheInfo = await uni.getStorageSync(`${this.cacheDir}${cacheKey}`);
      if (cacheInfo) {
        const fileInfo = await uni.getFileInfo({
          filePath: cacheInfo.path
        });
        
        if (fileInfo.size > 0) {
          return cacheInfo.path;
        }
      }
      return null;
    } catch (error) {
      return null;
    }
  }
  
  // 下载音频文件
  async downloadAudio(url, cacheKey) {
    try {
      const downloadResult = await uni.downloadFile({
        url: url,
        timeout: 60000
      });
      
      if (downloadResult.statusCode === 200) {
        const savedFilePath = `${wx.env.USER_DATA_PATH}/${this.cacheDir}${cacheKey}`;
        
        await uni.saveFile({
          tempFilePath: downloadResult.tempFilePath,
          filePath: savedFilePath
        });
        
        await uni.setStorageSync(`${this.cacheDir}${cacheKey}`, {
          path: savedFilePath,
          timestamp: Date.now()
        });
        
        return savedFilePath;
      }
      
      return url;
    } catch (error) {
      console.error('下载音频失败：', error);
      return url;
    }
  }
  
  // 清理过期缓存
  async clearExpiredCache(maxAge = 7 * 24 * 60 * 60 * 1000) {
    try {
      const now = Date.now();
      const storage = await uni.getStorageInfo();
      
      for (const key of storage.keys) {
        if (key.startsWith(this.cacheDir)) {
          const cacheInfo = await uni.getStorageSync(key);
          if (now - cacheInfo.timestamp > maxAge) {
            await uni.removeSafeFile({
              filePath: cacheInfo.path
            });
            await uni.removeStorageSync(key);
          }
        }
      }
    } catch (error) {
      console.error('清理缓存失败：', error);
    }
  }
}

3. 音频可视化

如果需要实现音频波形图等可视化效果，可以结合canvas实现：

// 音频可视化组件
export default {
  data() {
    return {
      canvasContext: null,
      analyser: null,
      dataArray: null,
      rafId: null
    }
  },
  
  methods: {
    initVisualizer() {
      const audioContext = new (window.AudioContext || window.webkitAudioContext)();
      const analyser = audioContext.createAnalyser();
      
      analyser.fftSize = 256;
      const bufferLength = analyser.frequencyBinCount;
      const dataArray = new Uint8Array(bufferLength);
      
      this.analyser = analyser;
      this.dataArray = dataArray;
      
      // 获取canvas上下文
      const query = uni.createSelectorQuery().in(this);
      query.select('#visualizer')
        .fields({ node: true, size: true })
        .exec((res) => {
          const canvas = res[0].node;
          this.canvasContext = canvas.getContext('2d');
          this.drawVisualizer();
        });
    },
    
    drawVisualizer() {
      this.rafId = requestAnimationFrame(this.drawVisualizer);
      
      const { analyser, dataArray, canvasContext } = this;
      const canvas = canvasContext.canvas;
      const width = canvas.width;
      const height = canvas.height;
      
      analyser.getByteFrequencyData(dataArray);
      
      canvasContext.fillStyle = 'rgb(0, 0, 0)';
      canvasContext.fillRect(0, 0, width, height);
      
      const barWidth = (width / dataArray.length) * 2.5;
      let barHeight;
      let x = 0;
      
      for(let i = 0; i < dataArray.length; i++) {
        barHeight = dataArray[i] / 2;
        
        canvasContext.fillStyle = `rgb(${barHeight + 100},50,50)`;
        canvasContext.fillRect(x, height - barHeight, barWidth, barHeight);
        
        x += barWidth + 1;
      }
    },
    
    stopVisualizer() {
      if (this.rafId) {
        cancelAnimationFrame(this.rafId);
        this.rafId = null;
      }
    }
  },
  
  beforeDestroy() {
    this.stopVisualizer();
  }
}

实际应用场景

1. 音乐播放器
2. 有声读物
3. 播客应用
4. 语音学习应用
5. 冥想放松应用

每个场景可能需要不同的功能特性，但核心的音频控制逻辑是相通的。根据具体需求，你可以基于本文提供的代码进行扩展和定制。

结语

background-audio-manager是UniApp提供的强大功能，掌握好它的使用可以帮助我们开发出优秀的音频应用。希望本文的内容对你有所帮助！如果你有任何问题或建议，欢迎在评论区留言交流。

最后，建议在实际开发中注意以下几点：

1. 合理管理音频资源，避免内存泄漏
2. 注意用户体验，提供必要的加载提示
3. 做好错误处理，提供友好的错误提示
4. 考虑不同平台的兼容性问题
5. 注重性能优化，特别是在低端设备上的表现

祝你开发顺利！