- What is hypervideos.js?
- How to use Hypervideos.js
- Existing plugins list
- Create your own plugin
- Code style guide
- See the examples
- Hiper: Hypervideos graphical interface
Hypervideos.js is an easy way to create interactive videos and images for your website in a very simple way. You will be able to add diferent interactive elements in a given timestamp of the video. See the examples to a better undestanding of the concept. Is compatible with video/images files and YouTube videos.
Hypervideos is very easy to use. First of all download the hypervideo.min.js (is located in the distri directory) file and import it to your HTML. Here you can also import all the plugins that you will use (check out the existing plugins or create your own). You should also create and import a JS file to setup your Hypervideo.
<head>
<script src="./hypervideo.min.js"></script>
<script src="./SimpleLabel.js"></script> //This is a Plugin
<script src="./main.js"></script>
</head>
Next add a <div> in your html page. You should provide the div with the class "hypervideo" and some unique identifier.
<div id="hypervideo_id" class="hypervideo"></div>
On your main.js file create a object to setup your Hypervideo parameters. The admited parameters are the following ones:
| Field | Type | Description |
|---|---|---|
| id | string | Id of the <div> element on your HTML |
| src | string | Path to the image or video file. If is a video from YouTube provide the video identifier located on the video URL |
| type | string | Type of the media loaded. There are 3 possible types: Hypervideo.VIDEO_TYPE - for video files. Hypervideo.IMAGE_TYPE - for image files. Hypervideo.YOUTUBE_TYPE - for YouTube videos. |
| videoTitle | string | Title for the hypervideo |
| size | object | Size of the hypervideo. Contains two fields: width (number) - Width in pixels. height (number) - Height in pixels. If the source provided is a video the size should have an aspect ratio of 16:9, if the ratio is not met, the video will be resized to match it. |
| tags (OPTIONAL) | array of objects | Each tag represents a "button" that will activate the interactive element. You can add as many tags as you want. Every tag is represented as an object, its fields are presented on the table below. |
Tags configuration object:
| Field | Type | Description |
|---|---|---|
| position | object | Position of the tag in the video/image. Contains two fields: x (number) - position x in % relative to the hypervideo container. y (number) - position y in %. |
| timeConfig | object | All the time parameters of the tag (Ignore for images). Contains two fields: timestamp (number) - time in seconds when the tag should appear. duration (number) - time in seconds of the tag duration on the video. |
| color | string | Color of the tag in hex format. |
| plugin | object | Configuration of the plugin that represents the interactive element in this tag. In order to use a plugin you need to imported first. Contains two fields: name (string) - class name of the plugin. config - configuration of the plugin. Check out the plugin documentation to use this field if needed. |
Configuration example:
const config = {
"src":"./assets/test_video.mp4",
"id":"hypervideo_id",
"type": Hypervideo.VIDEO_TYPE,
"videoTitle": "My first hypervideo",
"size": {
"width": 200,
"height": 200
},
"tags": [
{
"position": {
"x": 50,
"y": 20
},
"timeConfig": {
"timestamp": 1,
"duration": 10
},
"color": "#fcba03",
"plugin": {
"name": "SimpleLabel",
"config": {
"text": "Hi! I'm a label!"
}
}
}
]
};
Finally instantiate the Hypervideo class and call setupHypervideo function:
document.addEventListener("DOMContentLoaded", () => {
const hypervideo = new Hypervideo(config);
hypervideo.setupHypervideo();
})
Enjoy your Hypervideo!
Plugins are the responsable of creating the interactive element when the user interact with a tag. You can create your own plugin or use one of this list:
- SimpleLabel - https://github.com/Aleix88/Hypervideo-SimpleLabel
- Card - https://github.com/Aleix88/Hypervideo-Card
- Questionary - https://github.com/Aleix88/Hypervideo-Questionary
- Decision - https://github.com/Aleix88/Hypervideo-Decision
You can also create your on plugins. To do this create a JS class with your Plugin name. The class should extend from Plugin (this class is imported with the Hypervideo.min.js). The constructor of Plugin is empty so there's no need to overwrite it.
The plugin class has differents attributes that you can use (after onLoad method is called):
| Attribute | Type | Description |
|---|---|---|
| config | object | Data that comes from the hypervideo configuration object. You can use this field to pass data from the main JS file. |
| container | HTMLElement | This element is the hypervideo container. You should only add your views here if they are smaller than the video size or if you want the user to activate other tags while this is also activated. |
| elementsContainer | HTMLElement | This element is the hypervideo elements container. This container is unique for this tag and it will fit all the browser screen. Users will not be able to interact with other elements if this container is active. |
| videoManager | object | Instance of the video controller. You can use the following functions: - play(void) - pause(void) - restartVideo(void) - isVideoPlaying(void) : bool - getVideoDuration(void) : Returns the duration in seconds - loadProgress(Number) - Load any part of the video by a given progress. Progress should be specified between 0 and 1. - seekTo(Number) - Load any time of the video. Time should be in seconds. - setVolume(Number) - Volume should be specified between 0 and 1. You can also get the video currentTime as an attribute. *This object will be null for images |
The Plugin class has some methods that you could overrwrite (always calling super) to implement your plugin functionalities or call:
| Method | Parameters | Description |
|---|---|---|
| onLoad | config, container, elementsContainer, videoManager | This function is called when the plugin and it's atributes are loaded. In this function you should create and setup all your views, but don't show them to the user yet, wait for an interaction with the tag. |
| tagWillAppear | void | This function is called when the tag is going to appear in the screen. |
| tagWillDisappear | void | This function is called when the tag is going to disappear from the screen. |
| onTagClick | event | This function is called when the user clicks on the tag. This may be a good place to show your views to the user. |
| onTagHover | event | This function is called when the user hovers on the tag. |
| onTagLeave | event | This function is called when the users move the cursor outside the tag. |
| fullScreenStateChanged | true if the video/image is now in fullscreen mode, false if is not in full screen |
This function is called when video enters or exit the full screen mode. |
| showElementsContainer | void | DO NOT OVERWRITE THIS METHOD. You can call this method whenever you need to show the elements container. |
| hideElementsContainer | void | DO NOT OVERWRITE THIS METHOD. You can call this method whenever you need to hide the elements container. |
In order to keep the code clean, the following guidelines must be followed:
1 - Each code statement must end in a semicolon.
2 - Private functions names must start with two lower bars. Ex: __myPrivateFunction().
Check out this example: https://aleix88.github.io/Hypervideos-example/
If you are not a programmer but you want to use this library check out Hiper, a multi-platform program to generate the Hypervideo code. - https://github.com/Aleix88/Hiper
The main development team is associated to Aleix Díaz's TFG and GRETEL Research Group, associated to La Salle Campus Barcelona.
- Dr. Daniel Amo Filvà: daniel.amo@salle.url.edu - Github
- Aleix Díaz: aleix.diaz@students.salle.url.edu - Github