- Heroku: http://ng-video.herokuapp.com/
bower install ngvideo
ngVideo utilises Angular.js directives extensively which compartmentalises the various components that make-up the overall
ngVideo experience – meaning you get to pick and choose which components you wish to utilise.
ngVideo, the only required directive is the main
ng-video directive which handles all of the core logic, as well as the
vi-screen directive which is the player itself. All other directives are optional.
Terminology: When we mention
videoModel we mean the
object that is returned from
Starting to use
ngVideo is a breeze! Firstly you must define the container which will contain your video node.
Note: You can load multi-sources for each video for fallback purposes with
You then need to fulfill the only other requirement for
ngVideo – the
After that you have all that's necessary to begin playing videos – albeit without any user control.
ngVideo ships with a simple service that can be injected into your controllers, directives, services, et cetera... Since the
video service is what's used for adding video sources, we'll inject
video into one of our controllers:
We can then subsequently add video sources to be played. For this grab yourself a valid video source and add it:
At this point you should notice that the video is visible in the player, but not actually playing – unless you specify the
autoplay attribute on the
video node – for the user to begin playing the video, you need to add the
Not all browsers support the same media types, and therefore
ngVideo comes bundled with a way to load multiple source types for each of your videos –
ngVideo will attempt to play the first video in the source collection, and if unsupported, move to the next one, and so on.
Once you invoke the
save method, the video will be either played, or added to the playlist for later.
- Buffer: Buffered segments of video;
- Controls: Play and pause buttons;
- Feedback: Real-time video data;
- Full Screen: Open player in full screen;
- Meta: Reading meta data from videos;
- Messages: Subscribes to various
- Playback Rate: Adjusting the playback;
- Playlist: Managing a video/audio playlist;
- Seekable: Update the player's current time;
- Screen: Appending the
inputrepresenting current time;
- Volume: Managing the volume control;
With the buffer directive you can display a bar similar to the timeline which displays the buffered segments of the video – using the
ngVideoOptions for modifying the necessary values pertaining to the
ngVideoOptions can be injected into your controllers in the same way as services: see
Example of two buffering segments from Safari with
ngVideo@0.2.2 – notice the two red lines:
vi-controls directive allows you to add a play button and a pause button to your player –
vi-controls-pause respectively, where
vi-controls serves as the parent which contains the logic.
Provides information relating to the video itself – such as the
loading, et cetera... By adding the
vi-feedback directive to a node, your node will inherit lots of useful properties for the end user.
vi-feedback supports the following properties – as of
vi-full-screen directive you can open the player into full-screen mode depending on browser support.
ngVideo whether it should open or close the full screen mode. If you wish to force either the open and close, or have two different buttons for each action, then you can use
vi-full-screen-close in place of vi-full-screen-toggle.
In some cases you may wish to read the meta data of a video without actually playing it. For example, you may wish to know the duration of a video for the playlist – just so the user knows!
Simply wrap the
videoModel in the
vi-meta directive and you will have access to the video's meta data:
vi-messages directive you can subscribe to all of the native
video events and filter them depending on whether they're informational or a more serious error.
By adjusting the playback rate you can increase of decrease the speed of the video – you can achieve this with the
vi-playback-rate directive which sets the playback rate in absolute terms. You also have
vi-playlist directive you can manage your list of videos – by applying the
vi-playlist directive; it overrides the
videos array. With your
videoModel you should attach it to the directive using the
As well as listing the videos in the current playlist, the
vi-playlist contains useful methods for traversing the playlist:
Note: You don't need to use the
vi-playlist has access to the
open method which requires the passing in of the
vi-seekable directive you can update the player's current time either absolutely or relative to the current time. For this
ngVideo has three directives:
Each of the three directive accepts a parameter which is used to either set the time in seconds absolutely – as in the case of
vi-seekable, or relatively, in the case of both
vi-screen directive is the only mandatory directive – along with the core
ng-video directive for managing the core logic. It is also one of the simplest directives, because it simply outputs the
video node – with a little behaviour thrown in.
Keeping with the simplicity of the
vi-screen directive, the
vi-timeline is equally as simple, and contains the
input – with type
range for notifying the user of which position they're at in the current video/audio.
Directive has the ability of modifying the volume and bundles with four useful directives for common tasks:
vi-volume-decrease for decreasing the volume,
vi-volume-increase for increasing,
vi-volume-loudest for the maximum volume, and the
vi-volume-mute directive for muting the audio. However, the
vi-volume directive has access to the
setVolume method which allows you to specify the audio level.
Note: For access to the
volume property, it is necessary for the
vi-volume directive to be a child of the
ngVideoOptions for its configuration parameters –
ngVideoOptions is injectable into a controller in the same way as a service is.
You can inspect the
ngVideoOptions object using your favourite debugger.
Below are a few of the parameters you may wish to play with:
REFRESH: Properties refresh
intervalin milliseconds – default being 50 milliseconds;
VOLUME_STEPS: Incremental and decremental steps of the volume – default 0.1;
VOLUME_MAXIMUM: Maximum volume that can be set – default is 1;
VOLUME_MINIMUM: Minimum volume that can be set – default is 0;
BUFFER_COLOUR: Colour of the
canvaselement in the
BUFFER_HEIGHT: Height of the
canvasnode in the aforementioned directive;
BUFFER_WIDTH: Width of the
canvasnode in the aforementioned directive;
SCREEN_CHANGE: Whether clicking on
videotoggles video state;
TIMELINE_CHANGE: Whether changing
rangereflects in seeking;
ng-video has a modular design, you can compile your own version of
ng-video depending on the directives you wish to use.
For example if you want a simple player with the play and pause buttons, and a volume control, then including the entire
ng-video module would be wasteful. Instead you could compile your own
ng-video.custom.min.js using the following
Each of the modules are separated by a comma – and three essential modules are included no matter what:
Once you've issued the
grunt custom command your custom builds – development and minified, will be present in the dist/custom directory.
ngVideo uses Jasmine with the Karma runner. All contributions to
ngVideo are welcome!
Please add a unit-test for your addition – or removal, and then run all of the tests using
karma start KarmaUnit.js, or with Grunt:
Once you've committed your changes to your branch and all tests are passing, please open a pull request for review.