西瓜播放器 HTML5 video video.js 播放器 HTML5播放器 mp4 hls hls.js flv flv.js dash dash.js 无缝切换

音乐播放器

西瓜音乐播放器是多功能、与视频播放使用同一套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
    }
  },
  preset: [MusicPreset], // 如果要同时使用默认preset,那么配置是['default', MusicPreset]
})

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

})

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

配置项含义
preloadNext开启预加载下一曲功能,当前歌曲播放到一半或列表循环顺序发生改变时会提前请求下一曲并存储在IndexedDB中
switchKeepProgresstrue切换歌曲时保持上一曲的播放进度,false切换歌曲时从0开始播放。默认false
abCycleAB循环配置对象,start表示AB循环段起始时间,end表示AB循环段结束时间,loop表示AB段循环播放
listAB循环配置对象,start表示AB循环段起始时间,end表示AB循环段结束时间,loop表示AB段循环播放

结合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'为波形显示
size用于配置确定频域的FFT的大小详见
status频谱指示器功能是否开启'on'为开启状态,'off'为关闭状态

频谱指示器方法

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

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插件

Notice

2.X时期用于播放m4a的xgplayer-m4a插件,在v3版本中合并到了xgplayer-mp4, xgplayer-mp4同时监听只有音频轨(即m4a)和只有视频轨的文件解析播放

针对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
    }
  },
  preset: [MusicPreset], // 如果要同时使用默认preset,那么配置是['default', MusicPreset]
  plugins: [Mp4Plugin]
})