Videogular’s API

With Videogular you can write your own plugins through a public API that you can inject in your directives and retrieve in your controllers through vgPlayerReady callback.

Let’s going to stop here to understand the methods and variables that you have available.


  • vgPlayerReady($API): Called when Videogular has been initialized. Returns the API with the listed methods and properties below.
  • vgComplete(): Called when media file has been completed.
  • vgUpdateVolume($volume): Called when volume has been changed. Returns the new volume.
  • vgUpdateTime($currentTime, $duration): Called when progress time has been updated. Returns the current time and the total duration.
  • vgUpdateState($state): Called when Videogular state has been changed. Returns the new state (“play”, “pause” or “stop”).
  • vgChangeSource($source): Called when video source has been changed. Returns the new media source.
  • vgError($event): Called when has been an error. Returns an error event.


  • play(): Plays media.
  • pause(): Pause media.
  • stop(): Stops media.
  • playPause(): Toggles play and pause.
  • changeSource(array): Updates current media source. Param “array” must be an array of media source objects. A media source is an object with two properties “src” and “type”. The “src” property must contains a trustful url resource. {src: $sce.trustAsResourceUrl(“path/to/video/video.mp4”), type: “video/mp4”}
  • seekTime(value, byPercent): Seeks to a specified time position. Param value must be an integer representing the target position in seconds or a percentage. By default seekTime seeks by seconds, if you want to seek by percentage just pass byPercent to true.
  • setVolume(volume): Sets volume. Param volume must be an integer with a value between 0 and 1.
  • toggleFullScreen(): Toggles between fullscreen and normal mode.
  • updateTheme(css-url): Removes previous CSS theme and sets a new one.
  • clearMedia(): Cleans the current media file.


  • config: String with a url to JSON config file.
  • isReady: Boolean value with current player initialization state.
  • isBuffering: Boolean value to know if player is buffering media.
  • isCompleted: Boolean value to know if current media file has been completed.
  • isLive: Boolean value to know if current media file is a Live Streaming.
  • playsInline: Boolean value to know if Videogular if fullscreen mode will use native mode or inline playing.
  • mediaElement: Reference to video/audio object.
  • videogularElement: Reference to videogular tag.
  • sources: Array with current sources.
  • tracks: Array with current tracks.
  • isFullScreen: Boolean value to know if we’re in fullscreen mode.
  • currentState: String value with “play”, “pause” or “stop”.
  • currentTime: Number value with current media time progress.
  • totalTime: Number value with total media time.
  • timeLeft: Number value with current media time left.
  • volume: Number value with current volume between 0 and 1.


Using the API in your controller

Ok, I have a video playlist and I want to switch between videos in my controller. This will be the common case when you use Videogular, so let’s do it.

First we’re going to create our HTML and it should be pretty similar than in the past tutorial:

Pretty much the same except by a new callback that is called vg-player-ready that is binded to a function in your controller called onPlayerReady. When onPlayerReady will be called you will receive the API as a parameter.

We recommend to save the API in your controller to make it accessible in your templates:

Now that you have the API in your controller you can add your video playlist and change between them.

Modify your controller to add a few videos, a config object and a setVideo(index) method:

This is all you need in your JS but to change our videos we need a couple of buttons in our HTML first.

Update your HTML with a couple of buttons with links to setVideo() method:

Let’s see the final result:

See the Pen Videogular – Using the API in your controller by Two Fucking Developers (@2fdevs) on CodePen.

Now you know how to use Videogular’s API in your controller, let’s going to see how to do the same in your own plugins!


Using the API in your plugins

If you’re used building directives to create a Videogular plugin is easy as pie.

In this example we’re going to add a plugin to show a big replay button when the video is completed, a common use case on video players.

As in other examples and our previous tutorials we need to add our HTML:

And a config file in our controller:

Now we can create our plugin, just add below your controller your new directive!

The important thing here is that require: “^videogular” that adds a new parameter in our link function. That parameter is in fact Videogular’s API, a directive controller with all the methods and properties available to control your video player.

Now the rest is pretty simple, just show the plugin (with ng-show) when the video has been completed and is stopped, and show a text that when you click (with ng-click) plays again the video.

With your directive completed you just need to add it to the HTML:

To finish this, add a few CSS classes and we’re done:

Take a look to the final result!

See the Pen Videogular – Using the API in your plugins by Two Fucking Developers (@2fdevs) on CodePen.

You can inspire yourself by taking a look to this examples: