@hopecloud/jetstream-player 0.2.6 → 0.2.7

package/docs/.vitepress/config.ts

@@ -0,0 +1,55 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: "Jetstream player API",
+  description: "Documentation of embed jetstream player API",
+  themeConfig: {
+    nav: [
+      {
+        text: 'Guide',
+        link: '/guide/'
+      },
+      {
+        text: 'Usage',
+        link: '/usage/using-multiple-iframes'
+      },
+    ],
+
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          {
+            text: 'What is Jetstream player API?',
+            link: '/guide/',
+          },
+          {
+            text: 'Getting Started',
+            link: '/guide/getting-started',
+          },
+        ]
+      },
+      {
+        text: 'Examples of use',
+        items: [
+          {
+            text: 'Using multiple iframes',
+            link: '/usage/using-multiple-iframes',
+          },
+          {
+            text: 'Jetstream player API methods',
+            link: '/usage/player-methods',
+          },
+          {
+            text: 'Jetstream player API events',
+            link: '/usage/player-events',
+          },
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/deeepvision/hcc-jetstream-player' }
+    ]
+  }
+})

package/docs/guide/getting-started.md

@@ -0,0 +1,120 @@
+# Getting Started
+
+## Try It Online
+
+You can try Jetstrem player API directly in your browser on [StackBlitz](https://stackblitz.com/edit/hcc-jetstream-player-demo?file=src%2Fcomponents%2FVideoSandbox.vue).
+
+## How to use?
+
+If you want to use the library in your project, you need to perform the following steps:
+
+- Installation
+- Initialization of Player instance and methods
+- Initialization `JetstreamPlayer` with iframe
+
+## Installation
+
+Jetstrem player API can be installed in an existing project via npm.
+
+```
+npm i @hopecloud/jetstream-player
+```
+
+Once installed, you will be able to import the required methods or variables from the library into your component
+
+```
+import { JetstreamPlayer, onEnded, initPlayerMethods, embedVideosSrc } from '@hopecloud/jetstream-player';
+```
+## Initialization of Player instance and methods
+
+In order for the library to be able to interact with all the embedded windows on your component, you need to grab all the iframes from the web page. To do this, you need to import and call a special function `initPlayerMethods`. This function under the hood grabs and sorts all the iframes present on the web page and determines which player exactly you want to interact with. Also inside the library, the function creates the `JetstreamPlayer` class, which we need to initialize our player and call the necessary methods.
+
+```
+import { initPlayerMethods, JetstreamPlayer } from '@hopecloud/jetstream-player';
+```
+
+### Important ☝️⬇️
+
+The `initPlayerMethods` function should be called when all DOM elements are loaded. Therefore, in our [Vue.js example](https://stackblitz.com/edit/hcc-jetstream-player-demo?file=src%2Fcomponents%2FVideoSandbox.vue), we call this function inside the [onMounted](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) lifecycle hook. The function will be executed when the template is fully loaded.
+
+```
+onMounted(() => {
+  initPlayerMethods();
+});
+```
+
+## Initialization `JetstreamPlayer` with iframe
+
+As mentioned earlier, the library creates a `JetstreamPlayer` class in which we have methods `play`, `pause`, etc.
+
+```
+class JetstreamPlayer {
+    iframe;
+    constructor(selector) {
+        this.iframe = document.querySelector(selector);
+    }
+    play() {
+        this.iframe.contentWindow?.postMessage('play', '*');
+    }
+    pause() {
+        this.iframe.contentWindow?.postMessage('pause', '*');
+    }
+    ...
+}
+```
+
+### Important ☝️⬇️
+
+In order to connect our iframe with `JetstreamPlayer` class, we need to somehow distinguish between embedded windows in our template. Since we can have **_one_** or **_many_** iframes, we **strongly recommend** to assign a separate `id` to each iframe.
+
+For example `id="iframe1"`, `id="iframe2"`
+
+```
+<div style="display: block; position:relative; max-width: 100%; width: 100%;">
+  <div style="padding-top: 56.25%;">
+    <iframe
+        id="iframe1"
+        allow="autoplay; encrypted-media"
+        allowfullscreen
+        style="position:absolute; top:0; left:0; width:100%; height:100%; border-radius: 20px;"
+        src="https://dev.jstre.am/embed/jsv:fEccZ5231KM/jsp:Ov2URVCKycR"
+    ></iframe>
+  </div>
+</div>
+```
+
+Since the iframe already has the specified `id`, we can create a variable _(array of variables)_ to bind the `JetstreamPlayer` with our iframe.
+
+```
+let player: JetstreamPlayer | null;
+
+player = new JetstreamPlayer('#iframe1');
+```
+
+After that, we can access the `player` variable and call the methods available in the `JetstreamPlayer` class.
+Please note that for DOM loading purposes, we do the assignment inside the [onMounted](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) lifecycle hook, along with the `initPlayerMethods` function we mentioned earlier.
+
+```
+setup() {
+  let player: JetstreamPlayer | null;
+  
+  onMounted(() => {
+    initPlayerMethods();
+    player = new JetstreamPlayer('#iframe1');
+  })
+
+  const playVideo = () => {
+    player.play();
+  }
+  
+  const pauseVideo = () => {
+    player.pause();
+  }
+
+  return {
+   playVideo,
+   pauseVideo,
+  }
+}
+```
+

package/docs/guide/index.md

@@ -0,0 +1,11 @@
+# What is Jetstream player API?
+
+## Short description
+
+**Jetstream player API** is a library that allows you to control an embedded video player from the outside of `iframe` and subscribe to events of that player. As you know, videos are embedded in a website through an `iframe` tag. As a user, you can play and stop the video by clicking a button within the iframe itself. But how about playing/stopping the video programmatically and receiving events directly from the player?
+
+Since our embed video player is a separate service that uses the `video.js`  under the hood, we cannot do this directly. Modern browsers don't allow this to be done, including due to `CORS` policy. Therefore, in this library, we use `postMessage()` methods that send directly to the player and where these methods are processed. On its side, embed player has its own methods that it also sends and that can be caught where it is used.
+
+Thus, we can interact with player and subscribe to the events of the required video or playlist.
+
+This library is adapted to work with [Vue.js](https://vuejs.org/) / [React](https://react.dev/) framework components. Just want to try it out? Skip to the [Quickstart](./getting-started).

package/docs/index.md

@@ -0,0 +1,23 @@
+---
+# https://github.com/deeepvision/hcc-jetstream-player
+layout: home
+
+hero:
+  name: "Jetstrem player API"
+  text: "Documentation of embed jetstream player"
+  tagline: 
+  actions:
+    - theme: brand
+      text: Get started
+      link: /guide/index
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/deeepvision/hcc-jetstream-player
+
+features:
+  - title: Convenience
+    details: No need to write special methods in the component. All the necessary methods are in the library
+  - title: Ease of use
+    details: All you need is to import the library
+---
+

package/docs/usage/player-events.md

@@ -0,0 +1,82 @@
+# Jetstrem player API events
+
+## `Embed player` available events
+
+### Next events are available in this version of the library:
+
+- `onEnded()`
+- `playVideo()`
+- `pauseVideo()`
+
+This list is not exhaustive. New events can be added as needed.
+
+In order to use these events, it is enough to import them from library.
+
+```
+import { onEnded, playVideo, pauseVideo } from '@hopecloud/jetstream-player';
+```
+
+These events are `callbacks` that act as **listeners**. That is, if a certain video or video in the **playlist** ends, the event `onEnded` will fire and transmit the **index** of the embedded window. Let's consider each event separately.
+
+## `onEnded()` event
+
+This event is called when a video or a video in a playlist ends. For example, if your component has two iframes, the first is a video and the second is a playlist. If some video ends in the playlist, `onEnded()` event will be triggered, and we will get index `1` _(the playlist is the second iframe in our component)_.
+
+### Example of use:
+
+```
+import { JetstreamPlayer, initPlayerMethods, onEnded } from '@hopecloud/jetstream-player';
+
+setup() {  
+  onMounted(() => {
+    initPlayerMethods();
+  })
+  
+  onEnded((index) => {
+    console.log(`VIDEO ${index} ENDED`);
+    // Will console 'VIDEO 1 ENDED'
+  });
+}
+```
+
+## `playVideo()` event 
+
+This event is a listener that fires when any video or playlist on your page starts playing. If your page has one or more embedded iframes and a video starts playing in the first window, event will be triggered and we will get index `0`.
+
+### Example of use:
+
+```
+import { initPlayerMethods, playVideo } from '@hopecloud/jetstream-player';
+
+setup() {  
+  onMounted(() => {
+    initPlayerMethods();
+  })
+  
+  playVideo((index) => {
+    console.log(`VIDEO ${index} IS PLAYING`);
+    // Will console 'VIDEO 0 IS PLAYING'
+  });
+}
+```
+
+## `pauseVideo()` event
+
+This event is a listener that fires when any video or playlist on your page paused. If your page has one or more embedded iframes and a video paused in the second window, event will be triggered, and we will get index `1`.
+
+### Example of use:
+
+```
+import { initPlayerMethods, pauseVideo } from '@hopecloud/jetstream-player';
+
+setup() {  
+  onMounted(() => {
+    initPlayerMethods();
+  })
+  
+  pauseVideo((index) => {
+    console.log(`VIDEO ${index} PAUSED`);
+    // Will console 'VIDEO 1 PAUSED'
+  });
+}
+```

package/docs/usage/player-methods.md

@@ -0,0 +1,59 @@
+# Jetstrem player API methods
+
+## `JetstreamPlayer` class available methods
+
+### Next methods are available in this version of the library:
+
+- `play()`
+- `pause()`
+- `playNext()`
+- `playPrevious()`
+
+This list is not exhaustive. New methods can be added to the library as needed.
+
+In order to use these methods, it is enough to import the `JetstreamPlayer`  class and call them as described in the previous section.
+
+```
+import { JetstreamPlayer } from '@hopecloud/jetstream-player';
+
+setup() {
+  let player: JetstreamPlayer | null;
+  
+  onMounted(() => {
+    initPlayerMethods();
+    player = new JetstreamPlayer('#iframe1');
+  })
+
+  const playVideo = () => {
+    player.play();
+  }
+  
+  const pauseVideo = () => {
+    player.pause();
+  }
+
+  return {
+   playVideo,
+   pauseVideo,
+  }
+}
+```
+
+## `play()` `pause()` methods
+
+The `play` or `pause` method can be called for a video as well as for a playlist. We are able to interact with our videos or playlists programmatically in the same way as pressing pause or play within the iframe itself.
+
+### Important ☝️⬇️
+
+When the web page with our embedded windows is just loaded and there has been no user action _(click, play)_ and video has the `sound settings on`, the programmatic `play()` function **will not execute**!
+
+The `play()` function will not work due to [Autoplay policy in Chrome](https://developer.chrome.com/blog/autoplay/). The same behavior occurs with services YouTube, Facebook, etc.
+
+Modern browsers don't provide an opportunity to avoid this setting. Therefore, for the first time, an action on the user side is necessary _(click in the iframe window)_. After this action, all methods will work clearly.
+
+If the video or playlist has **sound settings off** `(muted)`, then all methods work in normal mode.
+
+## `playNext()` `playPrevious()` methods
+
+The `playNext` or `playPrevious` method can be called only for a **playlist**. Calling these methods for a simple video will do nothing.
+We are able to interact with playlist programmatically in the same way as pressing `playNext` or `playPrevious` within the playlist itself.

package/docs/usage/using-multiple-iframes.md

@@ -0,0 +1,106 @@
+# Using multiple iframes
+
+## Two ways to use and assign a player for an iframe.
+
+We can embed one or more windows with our player on web page. If the iframe is one, then the use is very simple. As shown in the previous chapter, this can be done as follows 
+
+```
+import { JetstreamPlayer } from '@hopecloud/jetstream-player';
+
+setup() {
+  let player: JetstreamPlayer | null;
+  
+  onMounted(() => {
+    initPlayerMethods();
+    player = new JetstreamPlayer('#iframe1');
+  })
+
+  const playVideo = () => {
+    player.play();
+  }
+  
+  const pauseVideo = () => {
+    player.pause();
+  }
+
+  return {
+   playVideo,
+   pauseVideo,
+  }
+}
+```
+
+If we have many iframes, there is no need to create a separate variable for each player.
+#### Example of non-recommended use ⬇️
+
+```
+import { JetstreamPlayer } from '@hopecloud/jetstream-player';
+
+setup() {
+  let firstPlayer: JetstreamPlayer | null;
+  let secondPlayer: JetstreamPlayer | null;
+  
+  onMounted(() => {
+    initPlayerMethods();
+    firstPlayer = new JetstreamPlayer('#iframe1');
+    secondPlayer = new JetstreamPlayer('#iframe2');
+  })
+
+  const playVideo = () => {
+    firstPlayer.play();
+  }
+  
+  const pauseVideo = () => {
+    secondPlayer.pause();
+  }
+
+  return {
+   playVideo,
+   pauseVideo,
+  }
+}
+```
+
+### Recommended method
+
+Instead, we can use a simpler method. We can grab all players into an `array`. To do this, we need to import the `embedVideosSrc` variable from the library. This variable is an array that contains all `src` of iframes from our page. This variable will help us create our array of players
+
+```
+import { embedVideosSrc } from '@hopecloud/jetstream-player';
+```
+
+All we need is to create an empty array `const players = [];` and push each player there.
+
+### Example 
+
+```
+import { JetstreamPlayer, initPlayerMethods, embedVideosSrc } from '@hopecloud/jetstream-player';
+
+setup() {
+  const players = [];
+  
+  onMounted(() => {
+    initPlayerMethods();
+    embedVideosSrc.forEach((src, index) => {
+      players.push(new JetstreamPlayer(`#iframe${index + 1}`));
+    });
+  });
+
+  const playEmbedVideo = (index) => {
+    players[index]?.play();
+  }
+
+  const pauseEmbedVideo = (index) => {
+    players[index]?.pause();
+  }
+
+  return {
+   playEmbedVideo,
+   pauseEmbedVideo,
+  }
+}
+```
+
+Now we can `play` and `stop` a video or playlist from an array by specifying an `index`.
+
+We used the same method in the [Stackblitz](https://stackblitz.com/edit/hcc-jetstream-player-demo?file=src%2Fcomponents%2FVideoSandbox.vue) sandbox.

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@hopecloud/jetstream-player",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Embeddable player for Jetstream videos",
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "main": "dist/index.js",
   "devDependencies": {
-    "typescript": "^5.0.2"
+    "typescript": "^5.0.2",
+    "vitepress": "^1.0.0-alpha.65"
   }
-}
+}