-----------------------------------------------------------------------------------------------------
The jQuery HTML5 Audio / Video Library
jPlayer is the completely free and open source (MIT) media library written in JavaScript. A jQueryplugin, (and now a Zepto plugin,) jPlayer allows you to rapidly weave cross platform audio and video into your web pages. jPlayer's comprehensive API allows you to create innovative media solutions whilesupport and encouragement is provided by jPlayer's active and growing community.
Choose jPlayer
- easy to get started, deploy in minutes
- totally customizable and skinnable using HTML and CSS
- lightweight - only 12KB minified and Gzipped
- free and open source, no licensing restrictions
- active and growing community providing support
- free plugins available for popular platforms
- extensive platform support - multi-codec, cross-browser and cross-platform
- comprehensive documentation and getting started guide
- consistent API and interface in all browsers, HTML5 or Adobe® Flash™
- extensible architecture
Platforms and Browsers
- Windows: Chrome, Firefox, Internet Explorer, Safari, Opera
- Windows (legacy): IE6, IE7, IE8, IE9, IE10, IE11
- OSX: Safari, Firefox, Chrome, Opera
- iOS: Mobile Safari: iPad, iPhone, iPod Touch
- Android: Android 2.3 Browser
- Blackberry: OS 7 Phone Browser, PlayBook Browser
Media Support
- HTML5: mp3, mp4 (AAC/H.264), ogg (Vorbis/Theora), webm (Vorbis/VP8), wav
- Flash: mp3, mp4 (AAC/H.264), rtmp, flv
For cross-browser support, a format must be supplied that works in both HTML5 and Flash.
Optional additional formats may be supplied to increase cross-browser HTML5 support.
ejQuery HTML5 音频/视频 库
jPlayer是完全免费和开源的使用JavaScript写的媒体库。一个jQuery插件(和现在的Zepto插件,)jPlayer让你快速的在网页上编织跨平台的音频和视频。jPlayer综合的API让你创建创新的媒体解决方案,而支持和鼓励来自jPlayer活跃和成长中的社区。
选择jPlayer的理由
容易开始,在几分钟内部署
完全自定义和使用HTML+CSS换肤
轻量的 - 缩小和压缩后只有12KB
免费和开源,没有许可证限制
活跃和成长中的社区提供支持
免费的插件对流行平台可用
广泛的平台支持 - 多编解码器,跨浏览器和跨平台
全面的文档和开始指导
在所有的浏览器,HTML5或Adobe Flash上拥有一致的API和接口
可扩展的架构
平台和浏览器
覆盖大部分平台和浏览器。
媒体支持
HTML5: mp3, mp4 (AAC/H.264), ogg (Vorbis/Theora), webm (Vorbis/VP8), wav
Flash: mp3, mp4 (AAC/H.264), rtmp, flv
为了跨浏览器支持,必须提供一个能同时在HTML5和FLASH上工作的格式。
可选的额外格式可以被提供用于增加跨浏览器HTML5支持。
官网:http://jplayer.org
下载jPlayer 2.7.0:http://jplayer.org/download/
GitHub:https://github.com/happyworm/jPlayer/
-----------------------------------------------------------------------------------------------
jPlayer2.9 开发者指南:
一. jplayer基础
1. 必要的音频格式
应用必要的格式之后,其余对应的格式可以用来提高HTML5解决方案的跨浏览器支持,主要选项是: jPlayer({"supplied": "formats"})
Audio: MP3, M4A 必须应用其中一个
Video: M4A 必须应用
2. 设置jplayer大小
设置宽高使用:jPlayer({size:Object}); 全屏幕尺寸使用:jPlayer({sizeFull:Object}); 设置背景色使用:jPlayer({backgroundColor:"#RRGGBB"})
3. Flash安全规则
使用下面的代码, swf文件的安全规则是放松的,可以在任何域名被调用: flash.system.Security.allowDomain("*"); flash.system.Security.allowInsecureDomain("*");
改变路径使用:jPlayer({"swfPath":path}); Flash依靠客户端服务器使用绝对路径:jPlayer("setMedia", media);
在本地运行jplayer会违反flash安全,所以需要在本地搭建环境。
4. 音频编码
使用的音频必须确保解码器被HTML5浏览器支持,提供的音频格式必须确保解码器被Adobe Flash支持。
jplayer区分audio和video,因为jplayer对两种不同的音频类型运行有轻微的不同。
-
MP3
-
Since some browsers use the Flash element of jPlayer, the MP3 files used must be encoded according to the browser's Adobe Flash Plugin limitations:
- Constant Bitrate Encoded.
- Sample Rate a multiple of 11,025Hz. ie., 22,050Hz and 44,100Hz are valid sample rates.
-
M4A / M4V
-
The MP4 file is a container that supports both audio and video. The M4A format is an audio MP4, and the M4V format is a video MP4. The recommended encoding options for standard and mobile browsers are:
- H.264 Baseline Profile Level 3.0 video, up to 640 x 480 at 30 fps. Note that B frames are not supported in the Baseline profile.
- AAC-LC audio, up to 48 kHz.
The metadata should be at the start of the encoded data, since the Flash solution must have the metadata in order to begin playling. The option for this varies from encoder to encoder, but usually refers to optimizing for either web or streaming. This 3rd party link might help if you are having problems with the metadata: MetaData Mover
-
OGA / OGV
-
The OGG file is a container that supports both audio and video. The OGA format is an audio OGG, and the OGV format is a video OGG. The Vorbis and Theora codecs appear to have full support.
-
WEBMA / WEBMV
-
The WebM file is a container that supports both audio and video. The WEBMA format is an audio WebM, and the WEBMV format is a video WebM. The Vorbis and VP8 codecs appear to have full support.
-
WAV
-
The WAV format is supported by many HTML5 browsers. We recommend that you avoid it though as a counterpart format. The recommended encoding options are:
- 8-bit and 16-bit linear PCM
- Only codec "1" (PCM) is supported.
-
FLA / FLV
-
The Flash FLV file is a container that supports both audio and video. The FLA format is an audio FLV, and the FLV format is a video FLV. The FLA/FLV format is supported by the Flash fallback.
-
RTMPA / RTMPV
-
The RTMP protocol uses a Flash Media Server (FMS) to stream media to jPlayer's Flash solution. The RTMPA format is an audio RTMP stream, and the RTMPV format is a video RTMP stream. The HTML solution does not support RTMP.
-
M3U8A / M3U8V
-
The M3U8 playlist format is an Apple HLS (HTTP Live Streaming) file. m3u8a for audio and m3u8v for video. This format works well on Apple devices and browsers (Safari), but has limited support elsewhere.
-
M3UA / M3UV
-
The M3U playlist format is am MPEG URL file. m3ua for audio and m3uv for video.
-
FLAC
-
The flac audio format.
1) 编码器:
2) 参考:
5. 服务端响应
1) MIME类型:
服务端必须为每个音频地址给出正确地MIME类型,给出不正确的MIME类型,音频在一些HTML5浏览器上将终止运行,这是影响Firefox和Operad的常见原因。其它浏览器不严格,但总是应该检查MIME类型是否正确,当你在任何浏览器上遇到音频不能播放的问题的时候。
2) 音频的MIME类型有:
-
- MP3: audio/mpeg
- MP4: audio/mp4 video/mp4
- OGG: audio/ogg video/ogg
- WebM: audio/webm video/webm
- WAV: audio/wav
如果为音频和视频使用常见的后缀,如audio.mp4和video.mp4, 可以简单的使用MIME类型的video版本 audio/mp4.
在Apache服务器上,可以使用.htaccess来基于文件后缀设置MIME类型。
# AddType TYPE/SUBTYPE EXTENSION AddType audio/mpeg mp3 AddType audio/mp4 m4a AddType audio/ogg ogg AddType audio/ogg oga AddType audio/webm webma AddType audio/wav wav AddType video/mp4 mp4 AddType video/mp4 m4v AddType video/ogg ogv AddType video/webm webm AddType video/webm webmv
3) 禁止GZIP编码音频文件:
音频文件已经被压缩,GZIP仅仅浪费服务器的CPU。如果GZIP音频文件,Adobe Flash插件将遇到问题。同样不要GZIP jplayer.swf文件,随时修改javascript。
4) 字节范围要求
服务器必须支持字节范围,通过查看服务器响应的header中的Accept-Ranges来检测,大多数HTML5浏览器支持在下载期间查找新文件位置,所以服务器必须支持新的字节请求。
持续时间常常不能从文件读取因为一些格式需要读取文件开始到结束才能知道持续时间。chrome浏览器会有最多的问题,如果服务端不支持字节请求的话,但是所有的浏览器都会有一些问题,即使只是在你跳到结尾前让你等待所有音频加载。
jplayer社区写的一个PHP函数可以提供音频文件支持字节请求。在话题中查找jPlayer Support Group Post。
5) 保护你的音频文件
当尝试限制访问你的音频文件时需要小心,音频地址需要能在网络上被用户访问到并且以预期的格式响应。
使用服务端响应来阻止本地缓存音频的方式,在一些HTML5浏览器上会导致一些问题。它会导致音频的持续时间不可知,在jplayer上显示出来就是NaN。如果在后端做一些使其更安全的事情时,它们确保你能接收上面描述的字节范围请求。
6. 如何通过CSS或jQuery让jplayer不可用
当jplayer在浏览器上使用Flash,jplayer的<div>必须不被隐藏。同样移动端浏览器不要出现被隐藏的HTML5音频。
如果想使它不可见,可以把jplayer的<div>尺寸调为0,你应该小心任何jQuery动画,如fadeIn()和fadeOut(),不要应用在jplayer的<div>或任何它的父元素上。
<!-- 不允许做的例子 --> <head> <style> #jquery_jplayer { display:none; /* Disables jPlayer when using Flash */ } </style> <script type="text/javascript"> $("#jquery_jplayer").hide(); /* Disables jPlayer when using Flash */ </script> </head> <body> <div id="jquery_jplayer"></div> </body>
7. 安全限制
为了消除跨站脚本攻击(XSS), {noConflict}选项上和jplayer元素的ID名称上要有一些限制,这些限制是因为需要jQuery变量和jplayer元素ID的页面上Flash和Javascript之间的通信。它暴露了一个通过直接访问jplayer.swf文件潜在的易受攻击的需要通过额外的这些规则来限制的地方。
白名单字符是:A-Z
a-z
0-9
_
-
. 或者是在其它单词中,字母数字组成的字符,下划线,连字符/减号和句号。
8. jplayer数据
jplayer数据通常通过事件对象访问,然而里面的数据往往在事件产生前更新。下面是一个事件更新如何被创建的例子:
$('#jp').jPlayer({ timeupdate: function(event) { // 4Hz // Restrict playback to first 60 seconds. if (event.jPlayer.status.currentTime > 60) { $(this).jPlayer('stop'); } } // Then other options, such as: ready, swfPath, supplied and so on. });
jplayer对象自身同样可以通过 $('#jp').data('jPlayer'); 访问,然而,在给所有的读/写访问给所有的数据和所有的方法访问权之前,即使里面的方法,仅仅推荐给先前的开发者。读取数据是好的,但设置数据可能有出乎意料的影响。
前面的更新事件代码可以直接被模仿,使用一个间隔:
var jp = $('#jp'), jpData = jp.data('jPlayer'); setInterval(function() { // Restrict playback to first 60 seconds. if (jpData.status.currentTime > 60) { jp.jPlayer('stop'); } },100); // 10Hz
见:jPlayer("option")
9. jPlayer和Zepto
jplayer已被微调,为了你可以现在使用Zepto代替jQuery。
和数据模块编译的Zepto1.0+是需要的。
如果想使用jplayer作为Zepto的一个AMD模块,你需要编辑源码里的几行代码。默认AMD模块有设置为jQuery的依赖,而不是Zepto。下面是jplayer顶部的代码,你可以清楚的看到两行需要切换。
(function (root, factory) { if (typeof define === 'function' && define.amd) { // AMD. Register as an anonymous module. define(['jquery'], factory); // jQuery Switch // define(['zepto'], factory); // Zepto Switch } else { // Browser globals if(root.jQuery) { // Use jQuery if available factory(root.jQuery); } else { // Otherwise, use Zepto factory(root.Zepto); } } }(this, function ($, undefined) {
如果你没有使用AMD模块,那么jplayer安装准备使用Zepto. 简单的在页面中包含Zepto代替jQuery。
Zepto支持正式在jplayer2.4中发布。
二. jplayer文件
jplayer需要两个文件上传至你的服务器:jquery.jplayer.min.js 和 Jplayer.swf
当更新jplayer,由于文件更改,确保插件ZIP包中的所有文件被上传。
1. 插件文件
jquery.jplayer.min.js
插件的JS文件,需要添加在<head>里,在jQuery文件之后,下面是使用绝对路径和相对路径的引入方式。
<head> <script type="text/javascript" src="//code.jquery.com/jquery-1.11.1.min.js"> </script> <script type="text/javascript" src="/jPlayer/js/jquery.jplayer.min.js"> </script> </head>
jquery.jplayer.swf
jplayer插件的Flash10.1文件,使用grunt mxmlc模块,被Adobe Flex 4.6 SDK编译。
这个文件在不支持HTML5 <video>
和 <audio> 的浏览器中使用。
文件必须上传至你的服务器,修改路径使用swfPath方法,下面是设置相对路径的方式。
$("#jpId").jPlayer( { swfPath: "/scripts/jPlayer" });
2. 源文件
jquery.jplayer.js
jplayer的JS源文件,可以切换到jquery.jplayer.min.js,运行是相同的,但这个文件更大。JS源文件使用JSHint检测。这个文件是可以被人阅读的。
Jplayer.fla
这个文件不再需要,作为Flex编译器现在被用来编译ActionScript。它被留在了源码里,你可以有选择的使用它来编译ActionScript。
Jplayer.as
jplayer的ActionScript3源文件,jplayer不再需要这个文件除非用来编译。
happyworm.jPlayer AS3 package
同上。
三. jplayer结构
1. 描述
$(id).jPlayer(object:options):jQuery
jplayer构造器应用在jQuery选择器上,并使用提供的选项。被jplayer使用的div应该是空的,并且不被任何其它东西使用。
在一些例子中,jplayer的div可以放在body的最高级别上来防止页面上对jplayer的操作影响。
最重要的选项时ready事件句柄,用来定义jplayer开始使用的一个操作函数。 在ready事件发生前对jplayer使用命令会导致jplayer出错并且命令被忽略,即使使用的是Flash。
接下来最重要的选项是swfPath元素,定义了jplayer的swf文件。记得上传到你的服务器上。
2. 在实例化jplayer之后改变选项
在实例化jplayer后使用 jPlayer("option", key, value); 方法。具体在: http://jplayer.org/latest/developer-guide/#jPlayer-option
3. 事件句柄通过jplayer选项创建。
4. 参数
1) 选项:
ready:
Function : (Default: undefined)
事件绑定在.jPlayer命名空间下。
swfPath:
String : (Default: "js")
使用例如 jPlayer({swfPath:"/scripts/banana.swf"}); 通过使用 jPlayer({solution:"flash, html");来测试HTML5浏览器是否支持Flash。当 jPlayer("setMedia", media) 正确时,不正确的swfPath会产生 $.jPlayer.event.error 事件,类型是:$.jPlayer.error.FLASH。
solution:
String : (Default: "html, flash")
定义html和flash解决方案的优先权,上面的优先使用html其次是flash,调整顺序即可优先使用flash。
根据使用的格式,jplayer可能同时使用两种方案。如:{supplied:"mp3,oga,m4v"},flash方法来播放视频,音频可以在HTML方法中播放。
虽然你可以只指定一种方案,但是不推荐。
下面是一个aurora.js的解决方案,使用方式:
# 核心库添加对WAV的支持
<script src="aurora.js"></script>
添加Aurora编解码器到页面中,如添加FLAC和OGG支持(OGGs使用Vorbis或Opus)。
<script src="flac.js"></script> <script src="ogg.js"></script> <script src="vorbis.js"></script> <script src="opus.js"></script>
添加autora到solution选项中,如:{solution:"html,flash,aurora"}将把aurora排在第三个顺序。
设置auroraFormats,如:{auroraFormats:"wav,flac,oga"}告诉jplayer Aurora播放器可以播放这些格式,定义的格式应该以相同的方式,如jplayer的命名应用选项的惯例,如:{auroraFormats:"m4a"}
当Aurora的页面访问文件中的数据时,音频必须在同一个域名下。(可以安装CORS头,但不一定生效)
记住Aurora播放器解决方案是实验性的,仅仅有经验的开发者才应该尝试使用它。作者质疑其它任何人将需要它,部分是由于Aurora库要被其它类库使用需要修复它的seek()方法。
supplied:
String : (Default: "mp3")
定义jplayer使用的格式。顺序定义了优先级,最左边的格式优先级最高。
格式上的更多细节见:Media Encoding ,为什么一些格式成本上升的细节见:Essential Formats
基本的音频格式:mp3 或 m4a
基本的视频格式:m4v
相应的格式:webma, webmv, oga, ogv, wav, fla, flv, rtmpa, rtmpv。
所有格式个应用选项必须在 jPlayer("setMedia",media) 命令里。
solution的优先级决定了应用格式的优先级,jplayer通过找到给出的第一个运行的格式才工作。所以 {solution:"html,flash"} 和 {supplied:"mp3,oga"} 在Chrome里,mp3文件将使用原生的HTML播放,即使Chrome可以同时使用来播放。
( jplayer挑选的格式依赖于你的浏览器和solution选项。基础的格式是那些被flash支持的和幸运地被不支持flash的浏览器ie./iPad/iPhone所支持的格式。对应部分的格式用来提高跨浏览器的HTML5音频支持。)
size:
用来设置保存屏幕模式的大小。默认依赖应用的格式是音频还是视频。当同时应用两种类型时,视频格式默认被使用。
对象属性:
width
String : (Default: [Video:"480px"] [Audio:"0px"]) ;宽度作为CSS规则。
height
String : (Default: [Video:"270px"] [Audio:"0px"]) ;高度作为CSS规则。
cssClass
String : (Default: [Video:"jp-video-270p"] [Audio:""]);css类名添加到css选择器上。
sizeFull:
设置全屏幕模式。其余同上。
width
String : (Default: [Video:"100%"] [Audio:"0px"])
height
String : (Default: [Video:"100%"] [Audio:"0px"])
cssClass
String : (Default: [Video:"jp-video-full"] [Audio:""])
smoothPlayBar:
Boolean : (Default: false); 平滑过渡的进度条。
播放条宽度的改变动画是超过250ms的平滑变化,相当于一步的改变。这同样影响在播放条上的点击。
短的音频受影响最大,因为它们的一步改变是最大的。
fullScreen:
Boolean : (Default: false);设置初始状态为全屏幕模式。
这个选项通常通过界面上得全屏和恢复按钮改变。如果浏览器支持,视频将在全屏幕显示,否则在整个窗口。
改变fullScreen选项将改变fullWindow选项来匹配它。这条规则的异常情况是当WebKit视频在IOS上使用时,fullWindow选项将不会改变。
fullWindow:
Boolean : (Default: false) ;设置初始状态为全窗口模式。
这个选项是当设置为全屏,但全屏不可用时自动被设置的备选方式。
这个选项影响 jPlayer({cssSelectorAncestor}),为了jplayer显示不同于GUI界面。
改变 fullWindow 选项不会影响 fullScreen 选项。
audioFullScreen:
Boolean : (Default: false); 使键盘能够控制视频的全屏显示。
这个选项允许键控制全屏显示音频的图片,这对音频播放器来说是有用的。
更多关于键盘控制的信息见 jPlayer({keyEnabled}); 选项。
autohide:
为GUI在屏幕中的显示状态设置自动隐藏选项。
参数:
restored
Boolean : (Default: false);恢复屏幕显示时自动隐藏GUI。
full
Boolean : (Default: true);全屏幕显示时自动隐藏GUI。
fadeIn
Number : (Default: 200); 在毫秒内渐显的动画。
fadeOut
Number : (Default: 600); 毫秒内渐隐的动画。
hold
Number : (Default: 1000);毫秒内自动隐藏前暂停。
preload:
String : (Default: "metadata");有效的值是“none”,“metadata” 和 “auto”,符合HTML5标准。使用“auto”来预加载文件。
预加载是给用户代理的一个示意,不是一个命令。一些浏览器忽略这个选项。
volume:
Number : (Default: 0.8);用0到1的值定义开始的音量。
muted:
Boolean : (Default: false);定义开始的停止状态。
globalVolume:
Boolean : (Default: false);打开globalVolume选项会使volume选项应用到其它jplayer实例上。
verticalVolume:
Boolean : (Default: false) ;默认点击音量条是从左计算。设置该选项为ture,会使计算从底部开始。
如果使用这个选项,下面的CSS样式需要使用在音量条上来使它们垂直的显示。
<style> .jp-volume-bar { position:relative; } .jp-volume-bar-value { position:absolute; bottom: 0; } </style>
remainingDuration:
Boolean : (Default: false);