@gcorevideo/player 2.22.0 → 2.22.2

package/docs/api/player.bottomgear.additem.md

@@ -0,0 +1,95 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [BottomGear](./player.bottomgear.md) &gt; [addItem](./player.bottomgear.additem.md)
+
+## BottomGear.addItem() method
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Adds a custom option to the gear menu
+
+**Signature:**
+
+```typescript
+addItem(name: string, $subMenu?: ZeptoResult): ZeptoResult;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+name
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+A unique name of the option
+
+
+</td></tr>
+<tr><td>
+
+$subMenu
+
+
+</td><td>
+
+[ZeptoResult](./player.zeptoresult.md)
+
+
+</td><td>
+
+_(Optional)_ The submenu to attach to the option
+
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[ZeptoResult](./player.zeptoresult.md)
+
+The added item placeholder to attach custom markup
+
+## Remarks
+
+When called with $submenu param, a click on the added item will toggle the submenu visibility.
+
+When added without submenu, it's responsibility of the caller to handle the click event however needed.
+
+## Example
+
+
+```ts
+class MyPlugin extends UICorePlugin {
+  override render() {
+    this.$el.html('<div class="my-awesome-settings">...</div>')
+    this.core.getPlugin('bottom_gear')
+      ?.addItem('custom', this.$el)
+      .html($('<button>Custom settings</button>'))
+    return this
+  }
+}
+```
+

package/docs/api/player.bottomgear.md

@@ -7,7 +7,7 @@
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
-`PLUGIN` that adds the gear button with an extra options menu on the right side of the [media control](./player.mediacontrol.md) UI
+`PLUGIN` that adds a button to extend the media controls UI with extra options.
 
 **Signature:**
 
@@ -18,12 +18,70 @@ export declare class BottomGear extends UICorePlugin
 
 ## Remarks
 
-The plugins provides a base for attaching custom settings UI in the gear menu
+The plugin renders small gear icon to the right of the media controls. It provides a base for attaching custom settings UI in the gear menu
 
 Depends on:
 
 - [MediaControl](./player.mediacontrol.md)
 
+## Example
+
+You can use bottom gear to add custom settings UI to the gear menu.
+
+```ts
+import { BottomGear } from '@gcorevideo/player/plugins/bottom-gear';
+
+class CustomOptionsPlugin extends UICorePlugin {
+  // ...
+
+  override get events() {
+    return {
+      'click #my-button': 'doMyAction',
+    }
+  }
+
+  private doMyAction() {
+    // ...
+  }
+
+  override render() {
+    const bottomGear = this.core.getPlugin('bottom_gear');
+    if (!bottomGear) {
+      return this;
+    }
+    this.$el.html('<button class="custom-option">Custom option</button>');
+    // Put rendered element into the gear menu
+    bottomGear.addItem('custom').html(this.$el)
+    return this;
+  }
+
+  // alternatively, add an option with a submenu
+  override render() {
+    this.$el.html(template(templateHtml)({
+      // ...
+    })));
+    return this;
+  }
+
+  private addGearOption() {
+    this.core.getPlugin('bottom_gear')
+      .addItem('custom', this.$el)
+      .html($('<button class="custom-option">Custom option</button>'))
+  }
+
+  override bindEvents() {
+    this.listenToOnce(this.core, ClapprEvents.CORE_READY, () => {
+      const bottomGear = this.core.getPlugin('bottom_gear');
+      assert(bottomGear, 'bottom_gear plugin is required');
+      // simple case
+      this.listenTo(bottomGear, GearEvents.RENDERED, this.render);
+      // or with a submenu
+      this.listenTo(bottomGear, GearEvents.RENDERED, this.addGearOption);
+     });
+  }
+}
+```
+
 ## Methods
 
 <table><thead><tr><th>
@@ -44,7 +102,7 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[getElement(name)](./player.bottomgear.getelement.md)
+[addItem(name, $subMenu)](./player.bottomgear.additem.md)
 
 
 </td><td>
@@ -52,7 +110,7 @@ Description
 
 </td><td>
 
-**_(BETA)_**
+**_(BETA)_** Adds a custom option to the gear menu
 
 
 </td></tr>
@@ -66,21 +124,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** Re-renders the gear menu. It fires the [MEDIACONTROL\_GEAR\_RENDERED](./player.mediacontrolevents.md) event, which the plugins that attach to the gear menu can listen to to re-render themselves.
-
-
-</td></tr>
-<tr><td>
-
-[setContent(content)](./player.bottomgear.setcontent.md)
-
-
-</td><td>
-
-
-</td><td>
-
-**_(BETA)_** Replaces the content of the gear menu
+**_(BETA)_** Collapses any submenu open back to the gear menu.
 
 
 </td></tr>

package/docs/api/player.bottomgear.refresh.md

@@ -7,7 +7,7 @@
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
-Re-renders the gear menu. It fires the [MEDIACONTROL\_GEAR\_RENDERED](./player.mediacontrolevents.md) event, which the plugins that attach to the gear menu can listen to to re-render themselves.
+Collapses any submenu open back to the gear menu.
 
 **Signature:**
 
@@ -18,3 +18,7 @@ refresh(): void;
 
 void
 
+## Remarks
+
+Should be called by the UI plugin that added a gear item with a submenu when the latter is closed (e.g., when a "back" button is clicked).
+

package/docs/api/player.clapprnerdstats.md

@@ -20,8 +20,6 @@ export declare class ClapprNerdStats extends UICorePlugin
 
 Depends on:
 
-- [MediaControl](./player.mediacontrol.md)
-
 - [BottomGear](./player.bottomgear.md)
 
 - [ClapprStats](./player.clapprstats.md)

package/docs/api/player.clicktopause.md

@@ -7,7 +7,7 @@
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
-`PLUGIN` that adds a behavior of toggling the playback state on click over the container
+A small `PLUGIN` that toggles the playback state on click over the video container
 
 **Signature:**
 

package/docs/api/player.closedcaptions.md

@@ -18,7 +18,7 @@ export declare class ClosedCaptions extends UICorePlugin
 
 ## Remarks
 
-The plugin is activated when closed captions tracks are provided with the media source. It shows a familiar "CC" button with a dropdown menu to select the subtitles language.
+The plugin is activated when closed captions tracks are detected in the media source. It shows a familiar "CC" button with a dropdown menu to select the subtitles language.
 
 Depends on:
 
@@ -37,7 +37,7 @@ Player.registerPlugin(ClosedCaptions)
 new Player({
   ...
   cc: {
-    language: 'en',
+    language: 'pt-BR',
   },
 })
 ```

package/docs/api/player.closedcaptionspluginsettings.md

@@ -4,6 +4,11 @@
 
 ## ClosedCaptionsPluginSettings type
 
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Configuration options for the [ClosedCaptions](./player.closedcaptions.md) plugin.
+
 **Signature:**
 
 ```typescript

package/docs/api/player.errorscreen.md

@@ -4,10 +4,7 @@
 
 ## ErrorScreen class
 
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-> 
-
-`PLUGIN` that displays errors nicely in the overlay on top of the player.
+`PLUGIN` that displays fatal errors nicely in the overlay on top of the player.
 
 **Signature:**
 
@@ -16,3 +13,20 @@ export declare class ErrorScreen extends UICorePlugin
 ```
 **Extends:** UICorePlugin
 
+## Remarks
+
+A fatal error is an error that prevents the player from playing the content. It's usually a network error that persists after multiple retries.
+
+The error screen should not be confused with the content stub that is shown when no media sources are available. This can happen due to the lack of the support of the given sources type or because the sources are misconfigured (e.g., omitted).
+
+Configuration options - [ErrorScreenPluginSettings](./player.errorscreenpluginsettings.md)
+
+## Example
+
+
+```ts
+import { ErrorScreen, Player } from '@gcorevideo/player'
+
+Player.registerPlugin(ErrorScreen)
+```
+

package/docs/api/player.errorscreenpluginsettings.md

@@ -4,10 +4,7 @@
 
 ## ErrorScreenPluginSettings type
 
-> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-> 
-
-Configuration options for the [error screen](./player.errorscreen.md) plugin.
+Configuration options for the [ErrorScreen](./player.errorscreen.md) plugin.
 
 **Signature:**
 

package/docs/api/player.errorscreensettings.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [ErrorScreenSettings](./player.errorscreensettings.md)
+
+## ErrorScreenSettings type
+
+Settings for the [ErrorScreen](./player.errorscreen.md) plugin.
+
+**Signature:**
+
+```typescript
+export type ErrorScreenSettings = {
+    noReload?: boolean;
+};
+```

package/docs/api/{player.mediacontrolevents.md → player.gearevents.md}

@@ -1,18 +1,18 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [MediaControlEvents](./player.mediacontrolevents.md)
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [GearEvents](./player.gearevents.md)
 
-## MediaControlEvents enum
+## GearEvents enum
 
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
-Custom events emitted by the plugins to communicate with one another
+Events triggered by the plugin
 
 **Signature:**
 
 ```typescript
-export declare enum MediaControlEvents 
+export declare enum GearEvents 
 ```
 
 ## Enumeration Members
@@ -35,17 +35,17 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-MEDIACONTROL\_GEAR\_RENDERED
+RENDERED
 
 
 </td><td>
 
-`"mediacontrol:gear:rendered"`
+`"rendered"`
 
 
 </td><td>
 
-**_(BETA)_** Emitted when the gear menu is rendered
+**_(BETA)_** Use this event to accurately attach an item to the gear menu
 
 
 </td></tr>

package/docs/api/player.levelselector.events.md

@@ -12,7 +12,6 @@
 ```typescript
 get events(): {
         'click .gear-sub-menu_btn': string;
-        'click .gear-option': string;
         'click .go-back': string;
     };
 ```

package/docs/api/player.levelselector.md

@@ -75,7 +75,7 @@ Description
 
 </td><td>
 
-{ 'click .gear-sub-menu\_btn': string; 'click .gear-option': string; 'click .go-back': string; }
+{ 'click .gear-sub-menu\_btn': string; 'click .go-back': string; }
 
 
 </td><td>

package/docs/api/player.md

@@ -72,7 +72,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** `PLUGIN` that adds the gear button with an extra options menu on the right side of the [media control](./player.mediacontrol.md) UI
+**_(BETA)_** `PLUGIN` that adds a button to extend the media controls UI with extra options.
 
 
 </td></tr>
@@ -105,7 +105,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** `PLUGIN` that adds a behavior of toggling the playback state on click over the container
+**_(BETA)_** A small `PLUGIN` that toggles the playback state on click over the video container
 
 
 </td></tr>
@@ -160,7 +160,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** `PLUGIN` that displays errors nicely in the overlay on top of the player.
+`PLUGIN` that displays fatal errors nicely in the overlay on top of the player.
 
 
 </td></tr>
@@ -314,7 +314,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** `PLUGIN` that is responsible for managing the automatic failover between sources.
+`PLUGIN` that is responsible for managing the automatic failover between media sources.
 
 
 </td></tr>
@@ -325,7 +325,7 @@ Description
 
 </td><td>
 
-**_(BETA)_** `PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state
+`PLUGIN` that shows a pending operation indicator when playback is buffering or in a similar state.
 
 
 </td></tr>
@@ -379,12 +379,12 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[MediaControlEvents](./player.mediacontrolevents.md)
+[GearEvents](./player.gearevents.md)
 
 
 </td><td>
 
-**_(BETA)_** Custom events emitted by the plugins to communicate with one another
+**_(BETA)_** Events triggered by the plugin
 
 
 </td></tr>
@@ -417,7 +417,7 @@ A top-level event on the player object
 
 </td><td>
 
-**_(BETA)_** Custom events emitted by the plugin
+Custom events emitted by the plugin
 
 
 </td></tr>
@@ -615,15 +615,6 @@ A level of quality within a media source.
 **_(BETA)_** Plugin settings
 
 
-</td></tr>
-<tr><td>
-
-[TextTrackItem](./player.texttrackitem.md)
-
-
-</td><td>
-
-
 </td></tr>
 <tr><td>
 
@@ -669,6 +660,8 @@ Description
 
 </td><td>
 
+**_(BETA)_** Configuration options for the [ClosedCaptions](./player.closedcaptions.md) plugin.
+
 
 </td></tr>
 <tr><td>
@@ -733,60 +726,73 @@ Levels of severity of errors. Non-fatal errors usually can be ignored.
 
 </td><td>
 
-**_(BETA)_** Configuration options for the [error screen](./player.errorscreen.md) plugin.
+Configuration options for the [ErrorScreen](./player.errorscreen.md) plugin.
 
 
 </td></tr>
 <tr><td>
 
-[GearItemElement](./player.gearitemelement.md)
+[ErrorScreenSettings](./player.errorscreensettings.md)
 
 
 </td><td>
 
+Settings for the [ErrorScreen](./player.errorscreen.md) plugin.
+
 
 </td></tr>
 <tr><td>
 
-[GearOptionsItem](./player.gearoptionsitem.md)
+[LangTag](./player.langtag.md)
 
 
 </td><td>
 
-**_(BETA)_** An element inside the gear menu
+An ISO 639-1 language code.
 
 
 </td></tr>
 <tr><td>
 
-[LangTag](./player.langtag.md)
+[MediaControlElement](./player.mediacontrolelement.md)
 
 
 </td><td>
 
-An ISO 639-1 language code.
+**_(BETA)_** Media control elements, mount points for additional plugins
 
 
 </td></tr>
 <tr><td>
 
-[MediaControlElement](./player.mediacontrolelement.md)
+[PlaybackModule](./player.playbackmodule.md)
 
 
 </td><td>
 
-**_(BETA)_** Media control elements, mount points for additional plugins
+Module to perform the playback.
 
 
 </td></tr>
 <tr><td>
 
-[PlaybackModule](./player.playbackmodule.md)
+[PlaybackRateOption](./player.playbackrateoption.md)
 
 
 </td><td>
 
-Module to perform the playback.
+**_(BETA)_**
+
+
+</td></tr>
+<tr><td>
+
+[PlaybackRateSettings](./player.playbackratesettings.md)
+
+
+</td><td>
+
+**_(BETA)_**
 
 
 </td></tr>
@@ -882,15 +888,6 @@ A media source to fetch the media data from
 
 
 
-</td></tr>
-<tr><td>
-
-[SubtitlesPluginSettings](./player.subtitlespluginsettings.md)
-
-
-</td><td>
-
-
 </td></tr>
 <tr><td>
 

package/docs/api/{player.bottomgear.setcontent.md → player.mediacontrol.handlecustomarea.md}

@@ -1,18 +1,16 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [BottomGear](./player.bottomgear.md) &gt; [setContent](./player.bottomgear.setcontent.md)
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [MediaControl](./player.mediacontrol.md) &gt; [handleCustomArea](./player.mediacontrol.handlecustomarea.md)
 
-## BottomGear.setContent() method
+## MediaControl.handleCustomArea() method
 
 > This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
-Replaces the content of the gear menu
-
 **Signature:**
 
 ```typescript
-setContent(content: ZeptoResult): void;
+handleCustomArea(handler: (name: string, content: HTMLElement) => void): void;
 ```
 
 ## Parameters
@@ -35,18 +33,16 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-content
+handler
 
 
 </td><td>
 
-[ZeptoResult](./player.zeptoresult.md)
+(name: string, content: HTMLElement) =&gt; void
 
 
 </td><td>
 
-Zepto result of the element
-
 
 </td></tr>
 </tbody></table>