# 音乐播放器

西瓜音乐播放器是多功能、与视频播放使用同一套UI的强大播放器，支持浏览器实现了多种格式的音频播放，包括：

1. M4A
2. MP3
3. 3GP
4. OGG
5. WebM

在线代码运行示例

# 安装与配置

音乐播放功能以插件的方式安装和使用，如下所示：

import Player from 'xgplayer';
// 现在music作为一个固定的preset使用，不再继承player, 解决耦合性过大问题
import MusicPreset, { Analyze } from 'xgplayer-music';

let player = new Player({
  id: 'vs',
  mediaType: 'audio',
  ...,
  volume: 0.8,
  width: 900,
  height: 50,
  // 音乐播放控制模块配置
  music: {
    list: [{
      src: './song01.m4a',
      title: 'song01',
      vid: '000001',
      poster: 'poster01.jpg'
    },
    {
      src: './song02.m4a',
      title: 'song02',
      vid: '000002',
      poster: 'poster02.jpg'
    }]，
    preloadNext: true, // 预加载下一首
    switchKeepProgress: false, // 切换歌曲保持进度
    abCycle: { // AB段循环播放
      start: 3,
      end: 9,
      loop: true
    }
  },
  presets: [MusicPreset], // 如果要同时使用默认preset，那么配置是['default', MusicPreset]
})

// 初始化频谱
window.analyze = new Analyze(player, document.querySelector('canvas'), {
  bgColor: 'rgba(0,0,0,0.65)',
  stroke: 1,

})

音乐播放控制模块配置信息如下

# 结合mse

# 属性

可通过音乐播放控制插件实例设置或者获取属性，以下属性均挂载在player.plugins.music对象上

# mode

• 属性名： mode [可读可写]
• 含义： 当前播放模式，'order' | 'random' | 'loop'
• 备注： 'order'为顺序播放, 'random'为随机播放, 'loop'为循环播放

// 实例化之后修改播放模式
player.plugins.music.mode = 'random'

# timeScale

• 属性名： timeScale [可读可写]
• 含义： 歌曲快进或后退的时间间隔，单位为秒，默认15秒
• 备注： 无

// 实例化之后修改每次快进/快退时长
player.plugins.music.timeScale = 5

# 方法

以下API属性均需要通过player.plugins.music.xx来调用

# add

• 说明： 向播放列表中加入歌曲
• 参数： 对象类型，其属性src的值表示歌曲资源地址，属性name的值表示歌曲名
• 返回： 无
• 举例：

player.plugins.music.add({src:'url', name:'name', vid: 'xxx', poster: ''});

# remove

• 说明： 从播放列表中移除歌曲
• 参数： 字符串类型，表示所要移除歌曲的资源地址
• 返回： 无
• 举例：

player.plugins.music.remove('vid');

# random

• 说明： 随机获取播放列表中某一首歌曲
• 参数： 无
• 返回： 歌曲对象，其属性src的值表示歌曲资源地址，属性name的值表示歌曲名
• 举例：

{src, name} = player.plugins.music.random();

# next

• 说明： 播放下一首歌曲
• 参数： 无
• 返回： 无
• 举例：

player.plugins.music.next();

# prev

• 说明： 播放上一首歌曲
• 参数： 无
• 返回： 无
• 举例：

player.plugins.music.prev();

# setIndex

• 说明： 选择第n首歌曲
• 参数： 数字类型，表示歌曲在列表中的序号
• 返回： 无
• 举例：

player.plugins.music.setIndex(index);

# forward

• 说明： 歌曲快进timeScale秒
• 参数： 无
• 返回： 无
• 举例：

player.plugins.music.forward();

# backward

• 说明： 歌曲后退timeScale秒
• 参数： 无
• 返回： 无
• 举例：

player.plugins.music.backward();

# setAbCycle

• 说明： 设置AB循环
• 参数： AB循环片段的起始和结束时间，单位为秒
• 返回： 无
• 举例：

player.plugins.music.setAbCycle(start, end);

# removeAbCycle

• 说明： 删除AB循环
• 参数： 无
• 返回： 无
• 举例：

player.plugins.music.removeAbCycle();

# 事件

可监听音乐播放器事件进行响应：

# change

• 事件名： change
• 含义： 发生切换歌曲事件
• 参数： 新歌曲对象，src歌曲资源地址，name歌曲名，vid歌曲唯一编号，poster歌曲专辑封面图

# 可视化频谱

西瓜播放器通过页面上的Canvas标签和Html5 AudioContext对象为开发者提供了柱状和波形两种可视化频谱指示器(也可以阅读播放器源码开发其它模式的频谱指示器)。 在实例化音乐播放器对象后就可以通过player.analyze(canvasDom)方法获取频谱指示器对象：

import Player from 'xgplayer'
import { Analyze } from 'xgplayer-music'

const player = new Player({
  ...,
})
let an = new Analyze(player, document.querySelector('canvas'), {}); //参数为页面上的canvas元素

# 频谱指示器属性

可通过频谱指示器的属性获取其具体参数：

# 频谱指示器方法

可通过频谱指示器的方法对其具体参数进行设置：

#mode

• 说明： 设置频谱指示器模式
• 参数： 字符串，'bars'为柱状频谱指示器(默认)，'wave'为波形频谱指示器
• 返回： 无
• 举例：

an.mode = 'wave';

#size

• 说明： 用于配置确定频域的FFT的大小详见
• 参数： 数字，必须是从32到32768范围内的2的非零幂
• 返回： 无
• 举例：

an.size = 256;

# 歌词

西瓜播放器提供了歌词滚动显示功能，需要提供页面上已存在的DOM元素作为歌词的容器。 在实例化音乐播放器对象后就可以通过 new Lyric(lyricTxt, Dom) 方法设置歌词文本和显示歌词的容器，并调用 lyric.show() 方法显示歌词：

import Player from 'xgplayer'
import { Lyric } from 'xgplayer-music'

const player = new Player({
  ...,
})
let lyric = new Lyric([lyricTxts], document.querySelector('#gc'), {});
lyric.bind(player)
lyric.show();

player.on('destroy', () => {
  lyric.unbind(player)
})

# 歌词属性

可通过歌词对象的属性获取相关参数：

#interval

• 属性名： interval
• 含义： 每行歌词之间的跳转时间点控制参数
• 备注： 默认值为0

#offset

• 属性名： offset
• 含义： 手动同步歌词的总偏差，单位为秒
• 备注： 默认值为0

#offsetScale

• 属性名： offsetScale
• 含义： 手动同步歌词的调整步长，单位为秒
• 备注： 默认值为0.5秒

# 歌词方法

可使用歌词对象的方法进行相应操作：

#interval

• 说明： 用于设置每行歌词之间跳转时间点的控制参数
• 参数： 数字，单位为秒
• 返回： 无
• 举例：

lyric.interval = 0.1;

#offset

• 说明： 用于手动同步歌词
• 参数： 数字，单位为秒
• 返回： 无
• 举例：

lyric.offset -= lyric.offsetScale

#offsetScale

• 说明： 用于设置手动同步歌词的调整步长，单位为秒
• 参数： 数字，单位为秒
• 返回： 无
• 举例：

lyric.offsetScale = 0.2;

#adjust

• 说明： 调整每句歌词的显示时间，使之按照时间匀速显示
• 参数： 无
• 返回： 无
• 举例：

lyric.adjust();

#find

• 说明： 获取播放时间所对应的相关歌词
• 参数： 数字，表示歌曲播放时间，单位为秒
• 返回： 字符串数组，歌曲播放时间所对应的歌词
• 举例：

lyric.find(curTime);

#bind

• 说明： 如果歌词文本格式支持动态显示(即歌词文本中每句歌词有对应的歌曲播放时间点)，那么将音乐播放器与歌词绑定，即支持动态显示歌词：播放器每次触发timeupdate事件时也会触发lyricUpdate事件，lyricUpdate事件会返回当前播放时间对应的歌词。在 player.lyric(lyricTxt, Dom) 方法内部会默认调用bind方法。
• 参数： 对象，音乐播放器对象
• 返回： 布尔值，true为音乐播放器动态歌词绑定成功， false为歌词文本格式不支持动态显示
• 举例：

lyric.bind(player);

#unbind

• 说明： 将音乐播放器与歌词解绑，即删除lyricUpdate事件。
• 参数： 对象，音乐播放器对象
• 返回： 无
• 举例：

lyric.unbind(player);

#show

• 说明： 在player.lyric方法提供的DOM元素中创建歌词相关元素，若歌词文本支持则滚动显示歌词。
• 参数： 无
• 返回： 无
• 举例：

lyric.show();

#hide

• 说明： 歌词停止滚动。
• 参数： 无
• 返回： 无
• 举例：

lyric.hide();

# xgplayer-mp4插件

针对m4a音乐文件，西瓜播放器提供了xgplayer-mp4插件来实现格式解析和分段加载功能，使用方式如下demo

import 'xgplayer';
import MusicPreset from 'xgplayer-music';
import Mp4Plugin from 'xgplayer-mp4';

let player = new Player({
  id: 'vs',
  mediaType: 'audio',
  ...,
  volume: 0.8,
  width: 900,
  height: 50,
  // 音乐播放控制模块配置
  music: {
    list: [{
      src: './song01.m4a',
      title: 'song01',
      vid: '000001',
      poster: 'poster01.jpg'
    },
    {
      src: './song02.m4a',
      title: 'song02',
      vid: '000002',
      poster: 'poster02.jpg'
    }]，
    preloadNext: true, // 预加载下一首
    switchKeepProgress: false, // 切换歌曲保持进度
    abCycle: { // AB段循环播放
      start: 3,
      end: 9,
      loop: true
    }
  },
  presets: [MusicPreset], // 如果要同时使用默认preset，那么配置是['default', MusicPreset]
  plugins: [Mp4Plugin]
})