Wellcome to vidim

skip to the docs | GitHub

Why do we need another library?

While there are a couple of libraries out there, I was not very satisfied with any of them. First of all, I could not find any that supports both self hosted videos as well as YouTube hosted ones. Second, most of them rely on jQuery. And third, they were not easy to pick up for beginners.

Also, it's

Documentation

Most mobile devices do not support auto-playback of videos, in which case the video will be initialized in the paused state. For video to start playing, it requires a user interaction, like clicking on the element. You could use API to listen to a click event and trigger the video playback.

The problem arises when you want to detect which devices can autoplay videos. A foolish approach is detecting touch screens, but not only is it really hard, it's also not precise because a lot of laptops have touch screens. It is left up to the developer to implement detection that best suits his project.

On devices you don't want to display videos on, I suggest only providing poster and leaving out the src to stop the video from unnecessary loading.

Include the library before your own javascript:

<script type="text/javascript" src="js/vidim.min.js"></script>

You can download the latest stable version from here

or event better, npm install it:

npm install vidim --save

Creating a new instance

var myBackground = new vidim( '#element-id', {
  src: [
    {
      type: 'video/mp4',
      src: 'path/to/your/video.mp4'
    },
    {
      type: 'video/ogv',
      src: 'path/to/your/video.ogv'
    }
  ],
  poster: 'path/to/your/poster.jpg'
});

Note: you can pass any valid CSS selector as a first argument, it doesn't have to be an id. It can also be a DOM element itself. For example, if you were using jQuery, you would pass $( '.some-element' )[0]

or directly from the dom:

<div style="padding-bottom: 65.25%;" data-vidim="{ src: [{ type: 'video/mp4', src: 'path/to/your/video.mp4'}]}></div>

Note: when using dom attribute, make sure you use no quotes on object keys and single quotes around strings.

Calling API methods on the instance

myBackground.play();
myBackground.pause();

Listening for events

myBackground.on( 'pause', function() {
  console.log( 'Video paused!' );
});

Options

wrapperClass: ''

Class assigned to the wrapper element.

overlayClass: ''

Class assigned to the overlay element.

src: false

Self hosted video: an array of objects, each with keys type and src, where type is for example video/mp4 and src is a path to the source of that type.
YouTube: a url to the YouTube video or a YouTube video ID.

type: 'HTML5'

Self hosted video: you don't need to pass this options, as it's a default.
YouTube: set this to 'YouTube' or player won't work.

ratio: 1.7778

Aspect ratio of the video you are passing. Supports float number or '4/3' and '16/9' strings (for convenience only). Default is the same as passing '16/9'.

autoplay: true

Set to false if you don't want video to start playing automatically (autoplay: true is mostly not supported on mobile devices).

loop: true

Set to false if you don't want video to loop and instead play only once.

poster: ''

Path to image you want to use as poster. Poster can be configured to display before the video loads and after it finishes, as well as during pause. You can also only pass poster and leave out the src to display image bg only.

showPosterBeforePlay: true

Whether poster should be displayed before the video begins playing for the first time (for example while it's loading).

showPosterOnEnd: false

Whether poster should be displayed after the video finishes playing (will of course not work if the video is set to loop).

showPosterOnPause: false

Set to true to show the poster while the video is paused.

zIndex: 0

Sets the z-index css proeprty of the background video.

autoResize: true

Resizes the video automatically when the browser window is resized. You can also call .resize() manually on the vidim instance to trigger a resize.

muted: true

Set to false if you want to play sound (most users won't appreciate that).

startAt: 0

Number of seconds into the video where playback should start from.

onReady: false

You can set this to a function that will be called once the player is ready to receive API calls. Function is passed a single argument, a vidim instance, which you can use to call API methods on.

preload: 'auto'

Self hosted video only: sets a preload attribute on a video element.

quality: 'hd1080'

YouTube only: sets a desired playback quality (it's up to the YouTube to honour this request). Check https://developers.google.com/youtube/iframe_api_reference#Playback_quality for a list of possible qualities.

Methods

play()

Plays the video.

pause()

Pauses the video.

setVolume( volume )

Sets the video volume. Minimum is 0, and maximum is 100.

getVolume()

Gets the video volume. Minimum is 0, and maximum is 100.

mute()

Mutes the video.

unMute()

Unmutes the video.

setTime( time )

Sets the current time (in seconds) for the video.

getTime()

Gets the current time (in seconds) for the video.

getDuration()

Gets the duration (in seconds) of the video.

showPoster()

Pauses the video and shows the poster.

changeSource( newSource, newPoster (optional) )

Sets the new source for the video. This allows you to not have to destroy the current instance and create a new one if you simply want to show another video.

destroy()

Destroys the background and cleans up after itself, basically leaving you with thee state before you created the background video.

resize()

Resizes the video so that it adjusts to the containing element dimensions. If you are using autoResize: true in your optiosn then generally you won't need to call this manually, however if the containing element could resize regardless of the browser video changing its size (for example inserting dynamic content), then you should call this manually to update the background video size.

Global methods

vidim.getInstanceFromID( ID )

When created, each vidim instance gets assigned a unique numeric ID. If you only have an ID and want to get the instance back, use this method.

vidim.getInstanceFromElement( element )

Useful when you don't store the instance in a variable, but you need it to call some methods on it. You can use this method to retrieve the instance from the container you called it on. element can be either a selector string or an actual DOM element.

vidim.registerProvider( type, configuration )

You can use this method to register another provider except the ones that the library ships with (HTML% and YouTube). Check the src/providers folder on GitHub for an example.

vidim.destroyAllInstances()

If you want to destroy all active instances, you can use this simple method instead of calling destroy() on each instance separately.

vidim.scanDOM()

Scans the DOM for any elements that have a data-vidim attribute and creates a background on each based on the options provided in the attribute.

Events

To listen for a specific event, call .on( eventName, yourFunction ) on your vidim instance. To stop listening, call .off( eventName, yourFunction ). To listen for an event only once, use .once( eventName, yourFunction ), and to trigger an event, use .emit( eventName ).

ready

This event is emitted once the player is ready to receive API calls.

play

This event is emitted once the player starts playing (either initially or after a pause).

end

Emitted once the video ends (will not be triggered if video is set to loop).

destroy

Emitted just before the instance is about to be destroyed.

resize

Emitted after the video has been resized (i.e. on every resize() method call).

canplay

Self hosted video only. Emitted once the video has loaded enough to start playing, but not necessarily enough to play the whole duration without buffering.

canplaythrough

Self hosted video only. Emitted once the video has loaded enough that it should be able to play for the whole duration without the need for buffering.

buffering

YouTube only. Emitted when the video is buffering.