EXTERNAL INTERFACE

Using the external interface of the TSVideo Player, you can obtain information of the video player, or perform actions on the player, through the use of javascript functions executed on the web page where the video player is inserted.

The video player includes two functions that can be executed via javascript, getValue and sendAction, to obtain the information related to the video player and to execute actions in the video player, respectively.

getValue

The getValue function, accesible from the code external to the video player, is used to obtain information related to the playe. It can be general information, or specific data of the video file being played.

getValue admits as parameter an array with the term that needs to be queried. The admissible terms are:

status, information on player's status: loading, playing, paused, stopped.

volume, value of the player's volume at the time of query.

playing, returns the URL of the video being played.

caption, returns the URL of the subtitle file associated to the video being played.

elapsed, returns the time in seconds that has lapsed since the video started playing.

duration, returns the total length of the active video, in seconds.

Any other term queried through this function will return an error message.

The return value of getValue is an array of two elements, the first element is the boolean value that indicates if the function has been realized successfully or not; in case of success, the second element will be the result of the query, otherwise it will be an error message.

Note: The fact that the parameter passed to the getValue function is an array even when it only has one element, is in anticipation of future versions where it will have more functionalities.

sendAction

The sendAction function is used to execute actions on the video player from a code external to the player itself.

sendAction admits as parameter an array with the action to be executed and a value associated to that action. Among possible actions there are:

load, tells the player to load a video or a playlist. The URL of the video or of the playlist to be loaded is indicated in the second element of the array passed as parameter.

caption, tells the player to load a subtitles file which it will associate to the active video. The URL of the subtitle file is indicated in the second element of the array.

play, resumes playing if the active video is paused or stopped. This action does not require more elements in the array passed as parameter.

pause, pauses the active video. This action does not require more elements in the array.

stop, stops the active video and returns to its beginning. This action does not require more elements in the array passed as parameter.

volume, sets a value for the video player's volume. This action requires an integer between 0 and 100 as a second element in the array passed as a parameter.

seek, is used to play other sections of the active video. This action requires a value between 0 and 100 in the second element in the array passed as parameter; this value indicates what percentage of the active video has to be played.

sendAction's return value is an array of one or two elements. If the execution of the action was completed successfully, the return value is the array with just one boolean value, a true. If there was an execution error, the return value is an array of two elements, the first one a boolean value a false. An error message is the second element.

Note: it is recommended to only execute video player's external interface functions once the player is fully loaded.

JAVASCRIPT WRAPPER FOR TSVIDEO

Taking advantage of TSVideo Player's external interface facilities, we have developed a javascript based class that allows to easily control the video player externally.

The class is named TSVideo, same as the player.

The TSVideo class has the following public methods:

play(), begins playing of the active video.

pause(), passes video to the paused mode.

stop(), stops active video.

setVolume (Number), enters a value for the video player's volume. The parameter is an integer between 0 and 100.

load(URL), loads the video or the playlist determined by the URL passed as a parameter.

seek(Number), skips the video to a different fragment. The number passed as parameter means the percentage of the video length to which we want to skip; it is a number between 0 and 100.

caption(URL), loads a file with subtitles determined by the URL passed as a parameter; associates it with the active video.

getStatus(), returns the status of the player. The return value is a chain with any of the following values: loading, playing, paused, stopped.

getVolume (), returns the value of the player's volume at the moment when the function is called. The returned value is a number between 0 and 100.

getPlaying(), returns the URL of the active video.

getCaption(), returns the URL of the subtitle file associated to the active video.

getDuration(), returns the length, in seconds, of the active video.

getElapsed (), returns the lapsed time, in seconds, of the active video.

Instances of TSVideo class are created in a way that greatly facilitates development of an HTML interface for a video player.

To create an instance of the TSVideo class we use the reserved javascript word new and a class builder. The TSVideo class builder has the following protocol:

TSVideo( "Video Player ID”, object with the ID of every one of the video player's controls, optional”);

The first parameter of the TSVideo class builder is a chain with the ID assigned to the video player, this ID must be unique within the webpage.

The second parameter is an object through which we define the elements that control the video player. By determining this object we avoid having to call TSVideo class' public methods explicitly.

The object attributes to define controls are:

play_control, receives a chain with the identifier of the element that will control the play action.

pause_control, receives a chain with the identifier of the element that will control the pause action.

stop_control, receives a chain with the identifier of the element that will control the stop action.

mute_control, receives a chain with the identifier of the element that will control the mute action.

volume_control, receives a chain with the identifier of the element that will control the volume. This control has more complexity than other: it admits Drag and Drop action in the area comprised by the interior of the element that contains it, and its final position - relative to the element that includes it - is what determines the volume value sent to the player.

seek_control, receives a chain with the identifier of the element that will control the portion of the video to play. This control has the same complexity as the volume control. It admits Drag and Drop action in the area comprised by the interior of the element that contains it, and its final position is the one that determines the portion of the video to be played.

Note: All control identifiers must be unique within the webpage.

Please see below a functional example:

Pay special attention to the text in bold. The instance of the TSVideo class is created in the interior of the event "onload" of the webpage to make sure that the video player is loaded before creating the wrapper in javascript.