音乐播放控制API

本文编辑: MINA搬运工 MINA搬运工浏览 10144 版权所有,严禁转载



文档采取先基础后示例的方式书写,并将音乐播放相关的API按照功能性划分为以下三个部分。

音乐播放状态API

接口 说明
wx.getBackgroundAudioPlayerState(OBJECT) 获取音乐播放状态:总时长、当前位置、音乐地址、播放状态、下载进度等

音乐播放控制API

接口 说明
wx.playBackgroundAudio(OBJECT) 播放音乐,同时只能有一首音乐正在播放。
wx.pauseBackgroundAudio() 暂停音乐播放
wx.stopBackgroundAudio(OBJECT) 停止音乐播放
wx.seekBackgroundAudio(OBJECT) 控制音乐播放进度

监听播放状态的事件

接口 说明
wx.onBackgroundAudioPlay(CALLBACK) 监听音乐播放
wx.onBackgroundAudioPause(CALLBACK) 监听音乐暂停
wx.onBackgroundAudioStop(CALLBACK) 监听音乐停止

API 的说明部分来自官方文档,笔者补充的内容,会以 tips 形式给出。比如:

tips : 音乐播放控制API的使用,几个小场景:(1)定制一个自己的音乐播放小程序(流量问题,可以使用缓存来解决);(2)内容资讯类小程序的补充背景音乐;(3)睡前辅助小程序,天然白嘈音(首日上线即获70w+用户的小睡眠小程序)


仅对示例Demo感兴趣的,请直接拉到最后。

音乐播放状态

wx.getBackgroundAudioPlayerState(OBJECT)

获取音乐播放状态。

OBJECT参数说明:

参数 类型 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 说明
duration 选定音频的长度(单位:s),只有在当前有音乐播放时返回
currentPosition 选定音频的播放位置(单位:s),只有在当前有音乐播放时返回
status 播放状态(2:没有音乐在播放,1:播放中,0:暂停中)
downloadPercent 音频的下载进度(整数,80 代表 80%),只有在当前有音乐播放时返回
dataUrl 歌曲数据链接,只有在当前有音乐播放时返回

示例代码:

wx.getBackgroundAudioPlayerState({
    success: function(res) {
        var status = res.status
        var dataUrl = res.dataUrl
        var currentPosition = res.currentPosition
        var duration = res.duration
        var downloadPercent = res.downloadPercent
    }
})

音乐播放控制

wx.playBackgroundAudio(OBJECT)

播放音乐,同时只能有一首音乐正在播放。

OBJECT参数说明

参数 类型 必填 说明
dataUrl String 音乐链接
title String 音乐标题
coverImgUrl String 封面URL
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

示例代码:

wx.playBackgroundAudio({
    dataUrl: '',
    title: '',
    coverImgUrl: ''
})
wx.pauseBackgroundAudio()

暂停播放音乐。

示例代码:wx.pauseBackgroundAudio()

wx.seekBackgroundAudio(OBJECT)

控制音乐播放进度。

OBJECT参数说明:

参数 类型 必填 说明
position Number 音乐位置,单位:秒
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

示例代码:

wx.seekBackgroundAudio({
    position: 30
})
wx.stopBackgroundAudio()

停止播放音乐。

示例代码:wx.stopBackgroundAudio()

监听播放状态事件

wx.onBackgroundAudioPlay(CALLBACK)

监听音乐播放。

tips:一般情况下,被 wx.playBackgroundAudio() 方法触发。

wx.onBackgroundAudioPause(CALLBACK)

监听音乐暂停。

tips:一般情况下,被 wx.pauseBackgroundAudio() 方法触发。

wx.onBackgroundAudioStop(CALLBACK)

监听音乐停止。

tips:一般情况下,被 音乐自然播放停止 或 wx.seekBackgroundAudio() 方法导致 播放位置等于音乐总时长时 触发。

tips:特别地,开发工具最新版本0.12.130400中 wx.stopBackgroundAudio() 方法不能触发该事件(请读者一起验证一下)。这就是为什么,笔者在 onStopTap 仍然编码 改变音乐播放和coverImg的状态的原因。

相关 bug 说明

bug1: iOS 6.3.30 wx.seekBackgroundAudio 会有短暂延迟。(请更新至最新版本的 6.5.3 )

bug2: wx.pauseBackgroundAudio 在开发工具中,表现为 wx.stopBackgroundAudio 的行为,在真机测试中,表现正常。(最新版本0.12.130400 开发工具中已经修复 )

综合案例

音乐控制的内容,为每个API写示例的话,那就不好玩了。这部分就直接一个利用 8 个API设计的完整 Demo,先来效果吧(笔者自夸时间:音乐控制,相当优雅精美哦,注释中有大玄机)!

注意1:gif 展示效果,没有声音,其实快进和快退是有效果的呢!
注意2:图片素材,请点击百度公有盘或者是百度私有盘 密码:tatw

展示效果

wxml(骨架)

<view class="container">
  <image class="bgaudio" src="{{changedImg?music.coverImg:'/images/bgaudio.png'}}" />
  <view class="control-view">
    <!-- 使用 data-how 定义一个0、1表示 快退或快进10秒 -->
    <image src="/images/front10.png" bindtap="onPositionTap" data-how="0"/>
    <image src="/images/{{isPlaying?'play':'pause'}}.png" bindtap="onAudioTap" />
    <image src="/images/stop.png" bindtap="onStopTap" />
    <!-- 使用 data-how 定义一个0、1表示 快退或快进10秒 -->
    <image src="/images/next10.png" bindtap="onPositionTap" data-how="1"/>
  </view>
</view>

wxss(衣服)

.bgaudio{
  height: 350rpx;
  width: 350rpx;
  margin-bottom: 100rpx;
}

.control-view image{
  height: 64rpx;
  width: 64rpx;
  margin: 30rpx;
}

js(小动作)

Page({
  data: {
    // 记录播放状态
    isPlaying: false,
    // 记录 coverImg ,仅当音乐初始时和播放停止时,使用默认的图片。播放中和暂停时,都是用当前音乐的的 coverImg
    changedImg: false,
    // 音乐内容
    music: {
      "url": "http://ws.stream.qqmusic.qq.com/C100002I8eGJ28BI17.m4a?fromtag=38",
      "title": "谭咏麟 - 朋友",
      "coverImg": "http://y.gtimg.cn/music/photo_new/T002R150x150M000004eGsCN3SUheO.jpg?max_age=2592000"
    },
  },
  onLoad: function () {
    // 页面加载时,注册监听事件
    this.onAudioState();
  },
  // 点击播放或者是暂停按钮时触发
  onAudioTap: function (event) {
    if (this.data.isPlaying) {
      // 正常播放的话,就暂停。并修改播放的状态
      wx.pauseBackgroundAudio();
    } else {
      // 暂停的话,就开始播放。并修改播放的状态
      let music = this.data.music;
      wx.playBackgroundAudio({
        dataUrl: music.url,
        title: music.title,
        coverImgUrl: music.coverImg
      })
    }
  },
  // 点击停止音乐的播放
  onStopTap: function () {
    let that = this;
    wx.stopBackgroundAudio({
      success: function () {
        // 改变 coverImg 和 播放状态
        that.setData({ isPlaying: false, changedImg: false });
      }
    })
  },
  // 点击 快进10秒或者是快退10秒时,触发
  onPositionTap: function (event) {
    let how = event.target.dataset.how;
    // 获取音乐的播放状态
    wx.getBackgroundAudioPlayerState({
      success: function (res) {
        // 仅仅在音乐播放中,快进和快退才生效
        // 音乐的播放状态,1 表示播放中
        let status = res.status;
        if (status === 1) {
          // 音乐的总时长
          let duration = res.duration;
          // 音乐播放的当前位置
          let currentPosition = res.currentPosition;

          if (how === "0") {
            //注意: 快退时,当前播放位置快退 10 秒小于 0 的话,直接设置 position 为 1;否则的话直接减去 10 秒秒
            // 快退到达的位置
            let position = currentPosition - 10;
            if (position < 0) {
              position = 1;
            }
            // 执行快退
            wx.seekBackgroundAudio({
              position: position
            });
            // 给出一个友情提示,实际引用中,请删除!!!
            wx.showToast({ title: "快退10s", duration: 500 });
          }

          if (how === "1") {
            //注意: 快进时,当前播放位置快进 10 秒后大于总时长的话,直接设置 position为 总时长减 1 
            // 快进到达的位置
            let position = currentPosition + 10;
            if (position > duration) {
              position = duration - 1;
            }
            // 执行快进
            wx.seekBackgroundAudio({
              position: position
            });
          // 给出一个友情提示,实际引用中,请删除!!!
            wx.showToast({ title: "快进10s", duration: 500 });
          }
        } else {
          // 给出一个友情提示,实际引用中,请删除!!!
          wx.showToast({ title: "音乐未播放", duration: 800 });
        }
      }
    })

  },
  onAudioState: function () {
    let that = this;
    wx.onBackgroundAudioPlay(function () {
      // 当 wx.playBackgroundAudio() 执行时触发
      // 改变 coverImg 和 播放状态
      that.setData({ isPlaying: true, changedImg: true });
      console.log("on play");
    });

    wx.onBackgroundAudioPause(function () {
      // 当 wx.pauseBackgroundAudio() 执行时触发
      // 仅改变 播放状态
      that.setData({ isPlaying: false });
      console.log("on pause");
    });

    wx.onBackgroundAudioStop(function () {
      // 当 音乐自行播放结束时触发
      // 改变 coverImg 和 播放状态
      that.setData({ isPlaying: false, changedImg: false });
      console.log("on stop");
    });
  }
})

如果对于 单个API示例有偏执的同学,请按照下面的说明拆分代码:

  • onAudioState 方法中是监听播放状态事件的小Demo
  • onAudioTap 方法中是音乐播放控制的play和pause两个API的小Demo
  • onStopTap 方法中是音乐播放控制的stop单个API的小Demo
  • onPositionTap 方法中是音乐播放控制的stop和音乐播放状态的seek两个API的小Demo

延伸阅读内容

从无到有系列内容

如有技术问题或对本文有反馈,请加入QQ群:
微信小程序实战5营: 微信小程序Club实战5营