doc

h1. jquery.mb.vimeoPlayer

This is a jQuery component that let you play a Vimeo® movie in a chromeless player.
You can even use a movie as background of your HTML page.

!http://pupunzi.open-lab.com/wp-content/uploads/2010/06/DSC03762.jpg!

h3. go to "Demo page":http://pupunzi.com/#mb.components/mb.vimeoPlayer/vimeoPlayer.html
go to the "Download page":http://pupunzi.open-lab.com/mb-jquery-components/mb-vimeoPlayer/

h3. Available also as WordPress® component:
go to the "WordPress® component page":https://wordpress.org/plugins/wp-vimeoplayer/

h3. Important notice!

* The plug in <b>works only if used under a web server</b>. It doesn't work if you run the HTML page as file (file://...).
If you want to run it locally on your computer you need a web server installed (for ex: MAMP for Mac, XAMP for Windows, LAMP for linux) and reach the file from http://localhost... or whatever you mapped in the Host file as localhost.

* This player <b>doesn't work as background for devices</b> due to the restriction policy adopted by all on managing multimedia files via javascript. It fallsback to the default Vimeo player if used as player (not applied to the body).

h2. head inclusions:

<pre><code>
<link href="css/vimeoPlayer.css" media="all" rel="stylesheet" type="text/css">

<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.0.0/jquery.min.js"></script>
<script src="inc/jquery.mb.vimeoPlayer.js"></script>

</code></pre>

h2. JS call:

<pre><code>
    jQuery(function(){
      jQuery("#[playerID]").vimeoPlayer();
    });
</code></pre>

h2. HTML constructor:

<pre><code><div id="bgndVideo" class="player" data-property="{videoURL:'https://vimeo.com/199167955',containment:'body',autoPlay:true, mute:true, startAt:0, opacity:1}">My video</div></code></pre>

h2. data-property:

*data-property* is an attribute of the TAG where you can pass the options of the player as an Object. Any of the below parameter can also be passed as option within the initialize function. The one defined as attribute of the TAG wins.

  * *mute*:  true (boolean) mute the audio;
  * *showControls*: true (boolean) show or hide the player controls;
  * *ratio*: '4/3', '16/9' or 'auto' (string) to set the aspect ratio of the movie; if 'auto' the aspect ratio will be retreived form the getDataFromFeed method.
  * *quality*: 'default' or "small", "medium", "large", "hd720", "hd1080", "highres".
  * *opacity*: 0 to 1 (number) define the opacity of the video.
  * *containment*: (string) the CSS selector of the DOM element where you want the video background; if not specified it takes the "body"; if set to "self" the player will be instanced on that element.
  * *optimizeDisplay*: true (boolean) will fit the video size into the window size optimizing the view.
  * *loop*: false (boolean) or a number rapresenting how many times the video should loops once ended.
  * *vol*: 1 to 100 (number) set the volume level of the video.
  * *startAt*: 20 (number) Set the seconds the video should start at.
  * *stopAt*: 20 (number) Set the seconds the video should stop at. If 0 is ignored.
  * *autoPlay*: true (boolean) or false play the video once ready.
  * *showYTLogo*: true (boolean) Show or hide the YT logo and the link to the original video URL.
  * *addRaster*: false (boolean) Show or hide a raster image over the video.
  * *mask*: 'path/to/mask' or object {0:'path/to/mask1', 20:'path/to/mask2', ...} or false. *From version 3.0*. Add a mask to the player or a map of masks for each time specified.
  * *realfullscreen*: true (boolean) activate the new HTML5 full screen behavior.
  * *stopMovieOnBlur*: true (boolean) activate the pause behavior when the window loose focus.
  * *gaTrack*: true (boolean) activate the Google Analytics event tracker for that player.
  * *align*: 'ceter,center' (string) *From version 3.0.3*. Define how the video will behave once the window is resized; possible value are: 'top,bottom,left,right,center'; it accept a pair of value comma separated (ex: 'top,right' or 'bottom,left').


h2. Using jquery.mb.vimeoPlayer:

*To initialize a vimeoPlayer as simple player:*

<pre><code>
<div id="P1" class="player" 
     data-property="{videoURL:'https://vimeo.com/199167955',containment:'self',startAt:50,mute:false,autoPlay:false,loop:false,opacity:.8}">
</div>
</code></pre>

*To initialize a vimeoPlayer as background:*

<pre><code>
<div id="bgndVideo" class="player" 
     data-property="{videoURL:'https://vimeo.com/199167955',containment:'body',autoPlay:true, mute:true, startAt:0, opacity:1}">
</div>
</code></pre>

*To initialize a vimeoPlayer as element background (from v. 1.2.1):*

<pre><code>
<div id="P1" class="player" 
     data-property="{videoURL:'https://vimeo.com/199167955',containment:'#ElementID',startAt:0,mute:false,autoPlay:false,loop:false,opacity:1}">
</div>
</code></pre>

*What you can pass to the "videoURL" paramenter:*

To retrive the video from Vimeo you can use any of the following string:
* The URL of the page containing the video 
*videoURL: 'https://vimeo.com/199167955'*.
* The video ID 
*videoURL: '199167955'*.

h2. External methods

*jQuery.fn.v_change_movie(opt)*
This method let you change the video of the specified player.
It accept an Object as parameter containing all the data-property (see above) you need for the video; the only required is the *videoURL* parameter that can contain either the complete URL provided by Vimeo or the video ID.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_change_movie({videoURL:'199167955',ratio:'4/3'})"> Change video </button></code></pre>

*jQuery.fn.v_play()*
Let you play the video.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_play()">play</button></code></pre>

*jQuery.fn.v_pause()*
Let you pause the video.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_pause()">pause</button></code></pre>

*jQuery.fn.v_fullscreen()*
Let you switch video from background to front.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_fullscreen()">Full screen</button></code></pre>

*jQuery.fn.v_setVolume(val)*
Let you change the video volume.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_setVolume(20)">change volume</button></code></pre>

*jQuery.fn.v_mute()*
Let you mute the audio.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_mute()">mute</button></code></pre>

*jQuery.fn.v_unmute()*
Let you unmute the audio.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_unmute()">unmute</button></code></pre>

*jQuery.fn.v_toggleVolume()*
Let you switch from mute to unmute.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_toggleVolume()">unmute/unmute</button></code></pre>

*jQuery.fn.v_setAlign()*
Define how the video will behave once the window is resized; possible value are: 'top,bottom,left,right,center'; it accept a pair of value comma separated (ex: 'top,right' or 'bottom,left')
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_setAlign('top,right')">Top/Right</button></code></pre>

*Check the examples "here":http://pupunzi.com/mb.components/mb.vimeoPlayer/demo/demo_ext_methods.html*

h2. Filters: (not yet available)
From version 2.8.5 you can apply css filters to the video (<b>Except for IE that will not render CSS filters</b>). 

The available filters are:

* grayscale : 1-100,
* hue_rotate: 1-360,
* invert    : 1-100,
* opacity   : 1-100,
* saturate  : 1-400,
* sepia     : 1-100,
* brightness: 1-400,
* contrast  : 1-400,
* blur      : 1-100

Below you can find the list of available methods to manage filters; all those methods can be called after the vimeoPlayer has been initialized.

*jQuery.fn.v_applyFilter(filter, value)*
Apply a css filter to the player; accept the name of the filter and the value.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_applyFilter('sepia', 50)">apply sepia effect</button></code></pre>

*jQuery.fn.v_applyFilters(filters)*
Apply multiple css filter to the player; accept an object rapresenting the list of filters to be applied as key: value.
For example:
<pre><code>
var filters = {
  sepia: 50,
  hue_rotate : 220
}
jQuery('#[playerID]').v_applyFilters(filters)
</code></pre>

*jQuery.fn.v_toggleFilter(filter, value)*
Toggles the filter from the passed value to 0 and viceversa; accept the name of the filter and the value.
For example:
<pre><code><button onclick="jQuery('#bgndVideo').v_toggleFilter('sepia', 50)">toggle sepia effect</button></code></pre>

*jQuery.fn.v_toggleFilters(callback)*
Toggles all the filters; accept a callback function.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_toggleFilters(function(val){alert('filters are enabled: ' + val)})">toggle all filters</button></code></pre>

*jQuery.fn.v_removeFilter(filter, callback)*
Removes the specified filter; accept the name of the filter and a callback function.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_removeFilter('sepia', function(filter){alert(filter)})">remove sepia effect</button></code></pre>

*jQuery.fn.v_disableFilters()*
Disables all the appied filters.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_disableFilters()">disable all filters</button></code></pre>

*jQuery.fn.v_enableFilters()*
Enables all the appied filters.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_enableFilters()">enable all filters</button></code></pre>

*Check the examples "here":http://pupunzi.com/mb.components/mb.vimeoPlayer/demo/demo.html*

h2. Mask: (not yet available)

You can apply a mask to the video. A mask is a png file that will overlay the video. 

Below you can find the list of available methods to manage mask; all those methods can be called after the vimeoPlayer has been initialized.

*jQuery.fn.v_addMask("path/to/mask")*
Add a mask to the target video player. If you call the YTPAddMask method while a mask has been already applied the previous mask will be replaced.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_addMask('assets/mask-1.png')">Add Mask</button></code></pre>

*jQuery.fn.v_removeMask()*
Remove the previously applied mask from the target video player.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_removeMask()">Remove Mask</button></code></pre>

*jQuery.fn.v_toggleMask()*
toggle actual mask on and off.
For example:
<pre><code><button onclick="jQuery('#[playerID]').v_toggleMask()">Toggle Mask</button></code></pre>

You can also use those method within the "YTPTime" event trigger to display a specific mask at a specific time during the video play.
For example:
<pre><code>
       var myPlayer = jQuery('#[playerID]').vimeoPlayer();
       myPlayer.on("VPTime", function (e) {
            var currentTime = e.time;
            switch (currentTime) {
                case 1:
                    myPlayer.v_addMask('assets/mask-2.png');
                    break;
                case 10:
                    myPlayer.v_addMask('assets/mask-1.png');
                    break;
                case 15:
                    myPlayer.v_removeMask();
                    break;
                case 20:
                    myPlayer.v_addMask('assets/mask-4.png' );
                    break;
            }
        });
</code></pre>

*You can also define the mask via the options:*

<pre><code>
       //Single mask
       var myPlayer = jQuery("#[playerID]").vimeoPlayer({mask:'assets/mask-1.png'});
</code></pre>
Or:
<pre><code>
       //Multiple masks time:mask
       var myPlayer = jQuery("#[playerID]").vimeoPlayer({
            mask:{
                0:'assets/mask-1.png',  // at the beginning
                5:'assets/mask-4.png',
                25:'assets/mask-1.png',
                30: false,
                50:'assets/mask-4.png'
            }
        });
</code></pre>

*Check the examples "here":http://pupunzi.com/mb.components/mb.vimeoPlayer/demo/demo-masked.html*

h2. Events

The player triggers a specific event for each state:

* *VPUnstarted*: Before the video start playing (time is passed on the event object)
* *VPBuffering*: When video is buffering (time is passed on the event object)
* *VPReady*: When the video is ready to start playing
* *VPStart*: When the video start playing (time is passed on the event object)
* *VPPlay*: Each time the video change from paused to play.
* *VPPause*: When the video pause (time is passed on the event object)
* *VPEnd*: When video end; you can retrieve the time on the event object.
* *VPFullScreenStart*: When video goes full screen modality
* *VPFullScreenEnd*: When video exit full screen modality
* *VPMuted*: When video is muted
* *VPUnmuted*: When video is unmuted
* *VPTime*: Fired every seconds (time is passed on the event object: e.time)
* *VPData*: Fired on feed data retrieved (prop are passed on the event object: e.prop)

You can use these events to fire functions on a specific event as follow:

<pre><code>
jQuery('#[playerID]').on("VPEnd",function(e){
   var currentTime = e.time;
   //your code goes here
});

jQuery('#[playerID]').on("VPTime",function(e){
   var currentTime = e.time;
   if(currentTime == 20) //if the player is at the 20th second
      //do something
});
</code></pre>

h2. Google Analytics

If you are tracking your site with Google Analytics each player included into a page will generate a ga_event to get statistics for that video under the "Behavior > Events" Google Analytics tab.

h2. Remove ADs

If you doesn't want ADs on your background video and you are the owner of it you can disable advertisings on your Vimeo channel as explained "here":http://candidio.com/blog/how-to-remove-ads-from-your-Vimeo-videos.