Video Player Javascript Control Functions and Events

Tutorials, technical documents and downloads

Advanced Customization

Rev. Jun. 9, 2023

Description

List of control and event Javascript functions supported by the WS.WebTV's video players (Flash and HTML5).

Tutorial requirements

• WS.WebTV 1.7.5+
• HTML Knowledge (basic/medium).

Here you will find the list of the Javascript functions supported by the WS.WebTV video players (Flash and HTML5).

Control Functions

Control functions are those who perform actions on the video player.

wsvp_play()

Plays/resumes the current Clip.

wsvp_pause(disable_ui_play_resume)

Pauses the current Clip.

Parameters:
• disable_ui_play_resume (boolean): [OPTIONAL, available since v56pf3] - default is false - If true, it is only possible to resume playback through the wsvp_play() function.

wsvp_seek(t)

Seeks the current Clip to the specified time (when possible).

Parameters:
• t (string): Time to seek to, formatted as "h:m:s", where h is hour (integer), m is minutes (integer) and s is seconds (decimal).

Example:
wsvp_seek("0:0:120"); // Seek to second 120
wsvp_seek("0:10:3.5"); // Seek to minute 10, second 3.5

wsvp_skipFwd()

Skip to the next Clip of a playlist.

wsvp_skipBwd()

Skip to the previous Clip of a playlist (if current playback time is <= 2; otherwise, the current Clip will start playing back from the beginning).

wsvp_resize(width,height)

Resizes the video player.

Parameters:
• width (integer): The width, in pixels.
• height (integer): The height, in pixels.

Example:
wsvp_resize(640,480); // Will resize the player to 640px by 480px

wsvp_playClip(id_clip,play_in_current_playlist,id_as_number)

Playbacks a Clip by providing the ID or the number of the Clip in a playlist (Channel).

Parameters:
• id_clip (integer): The ID of the Clip or the number of the Clip in the current playlist (Channel). In this last case the id_as_num parameter must be true.
• id_as_number (boolean): Ops: true/false. If the id_clip is the actual Clip ID then set it to false, otherwise (if it is the number of the Clip in the current playlist) set it to true.
• play_in_current_playlist (string): Ops: "yes"|"no". If set to "yes" then the player will try to playback the Clip in the current playlist. In order for this to work, the Clip must exist in the playlist; if the Clip you intend to playback does not exist on the current playlist, then set it to "no".

Examples:
wsvp_playClip(2,"yes",false); // Will playback the Clip with ID 2 in the current playlist.
wsvp_playClip(2,"yes",true); // Will playback the Clip number 2 in the current playlist.
wsvp_playClip(2,"no",false); // Will playback the Clip with ID 2 by reloading the video player (the current platylist will be lost).

wsvp_switchQuality(quality_id)

Available since WS.WebTV 2.2.0.3
Selects a video quality (it is the equivalent of selecting a video quality from the "gear" icon of the video player).

Parameters:
• quality_id (int): ID of the quality. If the quality is not available (or it is invalid), the current one will be kept. NOTE: WebTV qualities are defined in Configuration > Video.

Example:
wsvp_switchQuality(1); // selects (and play) quality 1
wsvp_switchQuality(2); // selects (and play) quality 2

wsvp_getCurrentQuality()

Available since WS.WebTV 2.2.0.3
Returns the ID (int) of the current video quality.

wsvp_getVideoElementID()

Available since WS.WebTV 56pf3
Returns the ID of the player's <video> element.

wsvp_getUIWrapperElementID()

Available since WS.WebTV 56pf3
Returns the ID of the UI wrapper element.

wsvp_getUIElementID()

Available since WS.WebTV 56pf3
Returns the ID of the UI element.

wsvp_getPlaylist()

Available since WS.WebTV 56pf3
Returns the playlist (excluding certain properties like associated media).

Events (available since v56pf3)

The WebTV video player dispatches several Javascript events that you can listen to.
NOTE: Since v60, it is also possible to listen to these events triggered from an Embed, through postMessages.

Global events, dispatched on the <body> element

You must listen for these events on the <body> HTML element.

_videoplayerloaded

This event is dispatched when the player is ready for dispatching other events and executing functions.

Event data properties:
     - videoPlayerElementID (string): The ID of the video player element (you will need to use this ID for listening to the other player events).

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
  });

Events dispatched on the video player element (videoPlayerElementID)

Add listeners to these events only after the global _videoplayerloaded event is dispatched.

_loadedclipdata

This event is dispatched when the Clip data has been loaded.

Event data properties:
     - date (string): Formatted date of the Clip.
     - description (string): Description of the Clip.
     - dislikes (integer): Number of "dislikes" for the Clip.
     - duration (string): Formatted duration of the Clip.
     - id (integer): ID of the Clip.
     - is_ad (integer): Whether the Clip is an Ad or not. Possible values: 1|0
     - likes (integer): Number of "likes" for the Clip.
     - on_sale (integer): Whether the Clip is on sale or not. Possible values: 1|0
     - playlist_index (integer): The index of the Clip in the current playlist.
     - product_url (string): If the Clip is on sale this is the URL of the corresponding products.
     - socialize (integer): Whether the Clip should display the sharing options or not. Possible values: 1|0
     - title (string): Title of the Clip.
     - trailer (integer): If the Clip is on sale, this specifies whether the playback corresponds to a trailer (a preview) or not.
     Possible values: 1|0
     - url (string): URL of the Clip.
     - user (string): Alias of the User (Clip Author).
     - user_href (string): URL of the User (Clip Author).
     - user_id (integer): ID of the User (Clip Author).
     - views (string): Statistics / Formatted number of total views for the Clip.

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_loadedclipdata",function(evt,evtData){ console.log("[Video Player Loaded Clip Data]",evtData); });
  });

_playerstatechange

This event is dispatched when the video player changes its state.

Event data properties:
     - status (string): Possible values: paused, playing, ended, buffering

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_playerstatechange",function(evt,evtData){ console.log("[Video Player State Change]",evtData.status); });
  });

_playererror

This event is dispatched when an error occurred while playing a video.

Event data properties:
     - error (string): The error message.

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_playererror",function(evt,evtData){ console.log("[Video Player Error]",evtData.error); });
  });

_fullscreenchange

This event is dispatched when the full screen button has been clicked and returns the toggled mode.

Event data properties:
     - mode (string): Possible values: fs_real (real full screen mode has been activated), fs_sim (real full screen is not supported. Simulating full screen by resizing the video player to fill the browser window size), normal (not in fullscreen).

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_fullscreenchange",function(evt,evtData){ console.log("[Video Player Fullscreen Change]",evtData.mode); });
  });

_timechange

This event is dispatched when the video time changes (during playback).

Event data properties:
     - time (integer): Current playback time in seconds.

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_timechange",function(evt,evtData){ console.log("[Video Player Time Change]",evtData.time); });
  });

_durationchange

This event is dispatched when the duration of the video changes.

Event data properties:
     - time (integer): Video duration in seconds.

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_durationchange",function(evt,evtData){ console.log("[Video Player Duration Change]",evtData.time); });
  });

_statsrec

This event is dispatched every time the player sends statistics. It is useful for implementing custom video statistics registration systems.

Event data properties:
     - type (string): Type of statistic.
Possible values: clip_views_play, ad_views_play, clip_views_play_complete, ad_views_play_complete, channel_views_embed, interactivity_views, interactivity_clicks, ad_clicks, user_stats. It is worth mentioning that "user_stats" is sent every few seconds and after certain actions are performed (like skipping or seeking).
     - id (integer): The Clip or Interactivity ID... In the case of "channel_views_embed", it will be the Channel ID.
     - title (string): The Clip title or Interactivity Content.
     - id_user (integer): The ID of the current User (0 if the viewer is not logged in).
     - id_channel (integer): The ID of the current Channel (0 if not playing inside a Channel).
    The following additional properties are provided with the following stat types: clip_views_play_complete, ad_views_play_complete and user_stats.
     - duration (integer): The Clip duration.
     - last_viewed_second (integer): The last viewed second.
     - current_viewing_time (integer): Incremental* - The current viewing time since the last sent.
     - heatmap (string): Incremental* - The view heatmap since the last sent. The heatmap is a string consisting of 0 and 1. The length of the string normally matches the length of the video, in seconds; for example, if the duration is 53s, the string would have 53 or less characters. 1 means the corresponding second was watched and 0 means it wasn't.
Example of heatmap for a Clip of 10 seconds: "1111000000". Interpretation: Only the first 4 seconds have been watched.
     *Incremental values are user statistics which are reset every time user stats are sent. Therefore, they must be added to previous values.

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_statsrec",function(evt,evtData){ console.log("[Video Player Stats Registered]",evtData); });
  });

_uiresizerequired

This event is dispatched when an UI resize is required (useful for knowing when it is necessary to resize/adjust any custom element which may have been added/overlaid in the video player).

Event data properties:
     - width (integer): Video player width.
     - height (integer): Video player height.

Example:
$("body").on("_videoplayerloaded",function(evt,evtData){
    console.log("[Video Player Loaded!]",evtData);
    var videoPlayerElementID = evtData.videoPlayerElementID;
    // player element event listeners from here...
    $("#"+videoPlayerElementID).on("_uiresizerequired",function(evt,evtData){ console.log("[Video Player UI Resize Required]",evtData); });
  });

Listen to events triggered from Embeds, through postMessages (since v60)

The aforementiones global and player element events are also triggered from Embedded players. The following sample Javascript code that allows listening to events triggered from an Embedded video player:
// Javascript code on container page
window.addEventListener('message', function(message)
{
   if ( typeof(message.data)!=="undefined" && typeof(message.data.from)!=="undefined" && message.data.from.indexOf("vpembed")>=0 )
   {
     console.log("Embedded player event",message.data);
     /*
       message.data will be an object with the following properties:
       {
       from: "vpembed_<CT>_<CID>", // <CT> = content type ("clip" | "channel") and <CID> = content ID (Clip or Channel ID)<br>
       event: "_videoplayereventname", // the name of the video player event (check the video player functions and events document to know all possible player events)<br>
       eventData: {} // the data object sent by the event
       }
     */
   }
});

Event Functions (Callbacks) - Deprecated (previous to v56pf3)

These functions are called from the video player, when certain events are triggered. Please note that, in order for the video player to do the calls, the functions must be defined in Javascript.

wsvp_onPlayerStateChange(data)

This function is called when the video player changes its state.

Parameters:
• data (object): The object returned by the video player, with the data.
     Object properties:
     - status (string): Possible values: paused, playing, ended, buffering

Example:
function wsvp_onPlayerStateChange(data)
{
   // Display the status in the Browser's console
   console.log("Player status change: "+data.status);
}

wsvp_onTimeChange(data)

This function is called when the video time changes (during playback).

Parameters:
• data (object): The object returned by the video player, with the data.
     Object properties:
     - time (number): Current playback time in seconds.

Example:
function wsvp_onTimeChange(data)
{
   // Display the video time in the Browser's console
   console.log("Video current time: "+data.time+" seconds);
}

wsvp_onDurationChange(data)

This function is called when the duration of the video changes.

Parameters:
• data (object): The object returned by the video player, with the data.
     Object properties:
     - time (number): Video duration in seconds.

Example:
function wsvp_onDurationChange(data)
{
   // Display the video duration in the Browser's console
   console.log("Video duration is: "+data.time+" seconds");
}

wsvp_onFullScreenChange(data)

[Since WS.WebTV 1.8 postfixes v1] This function is called when the full screen button has been clicked and returns the toggled mode.

Parameters:
• data (object): The object returned by the video player, with the data.
     Object properties:
     - mode (string): Possible values: fs_real (real full screen mode has been activated), fs_sim (real full screen is not supported. Simulating full screen by resizing the video player to fill the browser window size), normal (not in fullscreen)

Example:
function wsvp_onFullScreenChange(data)
{
   // Display the video duration in the Browser's console
   console.log("Toggled screen mode: "+data.mode);
}

wsvp_onLoadedClipData(data)

This function is called when the Clip data has been loaded.

Parameters:
• data (object): The object returned by the video player, with the data.
     Object properties:
     - date (string): Formatted date of the Clip.
     - description (string): Description of the Clip.
     - dislikes (integer): Number of "dislikes" for the Clip.
     - duration (string): Formatted duration of the Clip.
     - id (integer): ID of the Clip.
     - is_ad (integer): Whether the Clip is an Ad or not. Possible values: 1|0
     - likes (integer): Number of "likes" for the Clip.
     - on_sale (integer): Whether the Clip is on sale or not. Possible values: 1|0
     - product_url (string): If the Clip is on sale this is the URL of the corresponding products.
     - socialize (integer): Whether the Clip should display the sharing options or not. Possible values: 1|0
     - title (string): Title of the Clip.
     - trailer (integer): If the Clip is on sale, this specifies whether the playback corresponds to a trailer (a preview) or not.
     Possible values: 1|0
     - url (string): URL of the Clip.
     - user (string): Alias of the User (Clip Author).
     - user_href (string): URL of the User (Clip Author).
     - user_id (integer): ID of the User (Clip Author).
     - views (string): Statistics / Formatted number of total views for the Clip.

Example:
function wsvp_onLoadedClipData(data)
{
   // Display the Clip title in the Browser's console
   console.log("Clip title: "+data.title);

   // Display the Clip whole data object in the Browser's console
   console.log("Clip data:");
   console.log(data);
}

wsvp_onPlayerError(data)

Available since WS.WebTV 2.2.0.2
This function is called when an error occurred while playing a video.

Parameters:
• data (object): The object returned by the video player, with the data.
     Object properties:
     - error (string): The error message...

Example:
function wsvp_onPlayerError(data)
{
   // Display the error in the Browser's console
   console.log("Error playing the video: "+data.error);
}

wsvp_statsRec(data)

Available since WS.WebTV 53pf7
This function is called every time the player sends statistics. It is useful for implementing custom video statistics registration systems.

Parameters:
• data (object): The object returned by the video player, with the data.
     Object properties:
     - type (string): Type of statistic.
Possible values: clip_views_play, ad_views_play, clip_views_play_complete, ad_views_play_complete, channel_views_embed, interactivity_views, interactivity_clicks, ad_clicks, user_stats. It is worth mentioning that "user_stats" is sent every few seconds and after certain actions are performed (like skipping or seeking).
     - id (integer): The Clip or Interactivity ID... In the case of "channel_views_embed", it will be the Channel ID.
     - title (string): The Clip title or Interactivity Content.
     - id_user (integer): The ID of the current User (0 if the viewer is not logged in).
     - id_channel (integer): The ID of the current Channel (0 if not playing inside a Channel).
    The following additional properties are provided with the following stat types: clip_views_play_complete, ad_views_play_complete and user_stats.
     - duration (integer): The Clip duration.
     - last_viewed_second (integer): The last viewed second.
     - current_viewing_time (integer): Incremental* - The current viewing time since the last sent.
     - heatmap (string): Incremental* - The view heatmap since the last sent. The heatmap is a string consisting of 0 and 1. The length of the string normally matches the length of the video, in seconds; for example, if the duration is 53s, the string would have 53 or less characters. 1 means the corresponding second was watched and 0 means it wasn't.
Example of heatmap for a Clip of 10 seconds: "1111000000". Interpretation: Only the first 4 seconds have been watched.
     *Incremental values are user statistics which are reset every time user stats are sent. Therefore, they must be added to previous values.

Example:
function wsvp_statsRec(data)
{
   // Display the stats type in the Browser's console
   console.log("Stat type: "+data.type);

   // Display the whole data object in the Browser's console
   console.log("Stats data:");
   console.log(data);
}

Video Player Javascript Control Functions and Events | Advanced Customization | WS.WebTV Documentation | WebTV Solutions

Professional and affordable online video solutions

Installation and Maintenance

Configuration

Solving Login Problems

Statistics

Content Administration

‹Ext› Adv. Users Manag.

‹Ext› Store

Advanced Customization

Others

Advanced Customization