diff --git a/doc/tutorial/add_plugins.md b/doc/tutorial/add_plugins.md new file mode 100644 index 00000000..f0cab2ac --- /dev/null +++ b/doc/tutorial/add_plugins.md @@ -0,0 +1,190 @@ +# Add plugins + +## Installation + +The main `paella-core` library contains only the most basic plugins to make the player work. To have a complete player, we need to complement it with the use of other plugins. In this example we are going to add a plugin library to add the most typical player buttons. + +The first thing we do is install the `paella-basic-plugins` plugin library from `npm`: + +```sh +$ npm install --save paella-basic-plugins +``` + +## Plugin context + +To load a plugin we use a special load function that exports each plugin library. It is a function that returns an object called plugin context. This callback is called by `paella-core` at load time. Each plugin library must define a function that returns the plugin context. Using the `initData` object we will supply the callbacks to the player to load them when needed. Generally, the convention is that the plugin context function is obtained directly by importing the package from the plugin library. + +```js +... +import getBasicPluginContext from 'paella-basic-plugins'; + +const initParams = { + ... + customPluginContext: [ + getBasicPluginContext(), + ] +}; +const player = new PaellaÇ('player-container', initParams); +... +``` + +With this we have imported the plugins library, but to make them work we need to activate them. We are going to activate two plugins: volume and fullscreen, in addition to the plugin we had activated before play/pause: + +**settings.json:*** + +```js +{ + "plugins": { + ... + "es.upv.paella.playPauseButton": { + "enabled": true, + "order": 0 + }, + + "es.upv.paella.volumeButtonPlugin": { + "enabled": true, + "side": "left", + "order": 1 + }, + + "es.upv.paella.fullscreenButton": { + "enabled": true, + "side": "right", + "order": 3 + } + } +} +``` + +In the configuration file we see one new attribute in the plugins configuration: `side`: Para los plugins de tipo botón, indica en qué lado se va a mostrar el botón, que puede ser a la izquierda o a la derecha. + +As for the `order` attribute, we have already seen it in previous chapters. In general, this attribute indicates the loading order for a particular plugin type. But in the particular case of button plugins, they will be used to specify the position of one button relative to another. The lower the value of `order`, the sooner the button will load. + +Buttons on the left are set by default using the `float:left` CSS property, while those on the right are set with `float:right`. In this way, icons on the left are added from left to right, while those on the right are added from right to left. Knowing this, it is possible to use the `order` property to decide in which order the buttons are placed. + +## Video layout selector + +The video layout selector plugin allows you to switch between the available video layouts. In the [two streams](two_streams.md) tutorial we left one attribute to be configured in the layouts: the icon for a specific contentId. This icon will be used by the video layout selector, and we have to configure it before we can use it. The goal is to add an icon to each contentId. In addition to the icon, we already have an identifying text for each contentId, if we don't want to use the icons we can just use the `showIcons: false` attribute: + +```json +{ + "plugins": { + ... + "es.upv.paella.layoutSelector": { + "enabled": true, + "side": "right", + "order": 2, + "showIcons": false + }, + } +} +``` + +Para usar los iconos en los selectores de layout de vídeo, hay que proporcionar las imágenes. Se colocarán en el mismo directorio que la configuración. Las rutas de las imaágenes se cargarán en base a ese directorio. Crea cuatro ficheros en el directorio `settings` con los siguientes nombres: + +**presenter-presentation.svg:** + +```xml + + + + + +``` + +**presenter.svg:** + +```xml + + + + + +``` + +**presentation.svg:** + +```xml + + + + + + +``` + +**pip.svg:** + +```xml + + + + + + + + + + +``` + +Now we associate the icons to each content id in the configuration: + +```json +"es.upv.paella.dualVideoDynamic": { + ... + "validContent": [ + { "id": "presenter-presentation", "content": ["presenter","presentation"], "icon": "presenter-presentation.svg", "title": "Presenter and presentation" } + ], + ... +}, + +"es.upv.paella.singleVideoDynamic": { + ... + "validContent": [ + { "id": "presenter", "content": ["presenter"], "icon": "presenter.svg", "title": "Presenter" }, + { "id": "presentation", "content": ["presentation"], "icon": "presentation.svg", "title": "Presentation" } + ], + ... +}, + +"es.upv.paella.dualVideoPiP": { + ... + "validContent": [ + { "id": "presenter-presentation-pip", "content": ["presenter","presentation"], "icon": "pip.svg", "title": "PiP mode" } + ], + ... +}, +``` + +Finally, we configure the video layout selector plugin to display icons: + +```json +... +"es.upv.paella.layoutSelector": { + "enabled": true, + "side": "right", + "order": 2, + "showIcons": true +}, +``` + +## Botones en contenedor de vídeo + +Button plugins can be placed in the playback bar, but we can also place them in the video container. These buttons can also be placed left or right aligned. To place a button in the video container area, you can use the `parentContainer` property with the value `videoContainer`. If you want to put the button in the playback bar, use the value `playbackBar`, or remove the `parentContainer` property, as its default value is `playbackBar` + +```json +... +"es.upv.paella.layoutSelector": { + "enabled": true, + "side": "right", + "order": 2, + "showIcons": true, + "parentContainer": "videoContainer" +}, +``` + +Note, however, that video layouts can also contain icons, and may overlap with buttons if placed in this way. + +![video_container_button.jpg](video_container_button.jpg) + diff --git a/doc/tutorial/button_description.jpg b/doc/tutorial/button_description.jpg new file mode 100644 index 00000000..6e67b2b0 Binary files /dev/null and b/doc/tutorial/button_description.jpg differ diff --git a/doc/tutorial/group_buttons.md b/doc/tutorial/group_buttons.md new file mode 100644 index 00000000..66a9dc29 --- /dev/null +++ b/doc/tutorial/group_buttons.md @@ -0,0 +1,90 @@ +# Group buttons + +The `parentContainer` property can also be used to group buttons. To do this, we must first create a button group. In the configuration file, we add a new `buttonGroups` property. This is an array where we add an object for each button group. For each object, one button will be added. To add an icon to these groups is done in the same way as for layout icons: add an svg file in the configuration directory. The properties of each group we add are the same as those of a button plugin, so we can use the `order`, `side` and `parentContainer` fields in the same way. + +**settings.json:** + +```json +{ + ... + "buttonGroups": [ + { + "enabled": true, + "groupName": "options", + "description": "Configuration options", + "icon": "settings-icon.svg", + "order": 4, + "side": "right", + "tabIndex": 10, + "parentContainer": "playbackBar" + } + ], + ... +} +``` + +**settings-icon.svg:** + +```xml + + + +``` + +If we run the player, we can see that a new button has been added on the right side of the playback bar. Now let's put the fullscreen and layout selector icons inside. The new button group has the property `groupName: "options"`. So we'll use the name `options` as the `parentContainer` property of the `es.upv.paella.layoutSelector` and `es.upv.paella.fullscreenButton` plugins. + + +```json +{ + "plugins": { + ... + "es.upv.paella.layoutSelector": { + "enabled": true, + "side": "right", + "order": 2, + "showIcons": true, + "parentContainer": "options" + }, + + "es.upv.paella.fullscreenButton": { + "enabled": true, + "side": "right", + "order": 3, + "parentContainer": "options" + } + } +} +``` + +When we expand the new group we see that the buttons have a text: + +![video layout selector](video_layout_selector.jpg) + +That text is the default value of the `description` property of the plugin. We can change it in the configuration file. The text will be translated automatically using the dictionaries installed in the player (which we will see in detail in another tutorial). + +```json +{ + ... + "plugins": { + ... + "es.upv.paella.layoutSelector": { + "enabled": true, + "side": "right", + "order": 2, + "showIcons": true, + "parentContainer": "options", + "description": "Select different layout 🎛️" + }, + + "es.upv.paella.fullscreenButton": { + "enabled": true, + "side": "right", + "order": 3, + "parentContainer": "options", + "description": "Toggle fullscreen player 📺" + } + } +} +``` + +![button description](button_description.jpg) diff --git a/doc/tutorial/index.md b/doc/tutorial/index.md index d5ad0c9b..297fb9e2 100644 --- a/doc/tutorial/index.md +++ b/doc/tutorial/index.md @@ -5,16 +5,15 @@ Welcome to the paella-core tutorial for creating your own video player. This tut 1. [Quick start](quick_start.md) 2. [Two streams](two_streams.md) 3. [Init params](init_params.md) -4. Configuration file -5. Add plugins from libraries -6. Group buttons -7. Customize playback bar -8. Video manifest: formats -9. Video manifest: dual video -10. Video manifest: captions -11. Data plugins -12. Customize icons -13. Create a custom plugin -14. Video manifest: video canvas -15. Trimming basics -16. VideoContainer API +4. [Add plugins from libraries](add_plugins.md) +5. [Group buttons](group_buttons.md) +6. Customize playback bar +7. Video manifest: formats +8. Video manifest: dual video +9. Video manifest: captions +10. Data plugins +11. Customize icons +12. Create a custom plugin +13. Video manifest: video canvas +14. Trimming basics +15. VideoContainer API diff --git a/doc/tutorial/two_streams.md b/doc/tutorial/two_streams.md index 17d25ced..b770f692 100644 --- a/doc/tutorial/two_streams.md +++ b/doc/tutorial/two_streams.md @@ -277,7 +277,7 @@ Below you can see the complete configuration of the three layout plugins. "es.upv.paella.dualVideoPiP": { "enabled": true, "validContent": [ - { "id": "presenter-presentation-pip", "content": ["presenter","presentation"], "icon": "present-mode-3.svg", "title": "Presenter and presentation" } + { "id": "presenter-presentation-pip", "content": ["presenter","presentation"], "icon": "", "title": "PiP mode" } ], "dualVideoContentIds": [ "presenter-presentation" diff --git a/doc/tutorial/video_container_button.jpg b/doc/tutorial/video_container_button.jpg new file mode 100644 index 00000000..085270db Binary files /dev/null and b/doc/tutorial/video_container_button.jpg differ diff --git a/doc/tutorial/video_layout_selector.jpg b/doc/tutorial/video_layout_selector.jpg new file mode 100644 index 00000000..aec1d448 Binary files /dev/null and b/doc/tutorial/video_layout_selector.jpg differ