@millicast/vue-viewer-plugin
Version:
Vue.js plugin to embed viewer of a Millicast stream. This plugin allows developers to simplify Millicast services integration into their own Vue.js apps.
157 lines (111 loc) • 12.1 kB
Markdown
# Millicast Vue.js Web Viewer Plugin
A Vue.js plugin to embed a Millicast player into your app. This plugin allows developers to simplify the integration of Millicast services into their own Vue.js apps.
## Installation
To add this library to your project, from the command line execute the following instruction:
```bash
npm install @millicast/vue-viewer-plugin
```
or if you use [Yarn](https://yarnpkg.com)
```bash
yarn add @millicast/vue-viewer-plugin
```
## Basic Usage
To import the plugin into your Vue application, have the following structure in your `main.js` file:
```javascript
import { createApp } from 'vue'
import App from './App.vue'
// import the plugin
import VideoPlayer from '@millicast/vue-viewer-plugin'
const Vue = createApp(App)
// install within your app
Vue.use(VideoPlayer, {})
Vue.mount('#app')
```
You can either include the following dependecy at the **end** of your `App.vue` file:
```html
<style>
@import '@millicast/vue-viewer-plugin/dist/millicast-vue-viewer-plugin.css';
</style>
```
Or add the following dependecy at the beginning of your `main.js` file:
```javascript
import '@millicast/vue-viewer-plugin/dist/millicast-vue-viewer-plugin.css'
```
You can now use the plugin in any Vue file of your project as a component.
### Configuration Parameters
| Name | Type | Attribute | Default | Description |
| ---------------------- | ---------------- | --------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId` | `String` | Mandatory | | Millicast existing _Account ID_ where you want to get the stream. |
| `streamName` | `String` | Mandatory | | Millicast existing _Stream Name_ where you want to get the stream. |
| `image` | `String` | Optional | | Placeholder image while stream is offline. By default it is a solid black. |
| `muted` | `Boolean` | Optional | `false` | The streaming will start muted. |
| `autoplay` | `Boolean` | Optional | `true` | The streaming will autoplay when connected. |
| `hideButtons` | `Array.<String>` | Optional | `[]` | Specify a list of buttons to hide. See the [hide buttons](#hidebuttons-options) section for details. |
| `reportUrl` | `String` | Optional | `null` | Configure the URL to which reports should be sent to. |
| `chromecastId` | `String` | Optional | `null` | The Chromecast ID of your application. |
| `multisource` | `Boolean` | Optional | `false` | Configure your stream to show multiple streams. |
| `noDelay` | `Boolean` | Optional | `false` | Sets the minimum and maximum delay (sets `forcePlayoutDelayMin` and `forcePlayoutDelayMax` to 0). |
| `showLabels` | `Boolean` | Optional | `true` | Show stream label in multiview mode. |
| `environment` | `Object` | Optional | `.env file content` | Plugin environment. See [Environment options](#environment-options) on how to configure. |
| `mainLabel` | `String` | Optional | | Allows to change the label of the main video. |
| `metadata` | `Boolean` | Optional | `false` | Set to start listening to metadata events emitted by the SDK. |
| `startingQuality` | `String` | Optional | `null` | Allows to start the stream at a specific resolution when available. Possible values: 'High', 'Medium', 'Low', <Number> specifying the desired frame height (i.e. 360). |
| `hideToast` | `String` | Optional | `null` | Allows to hide a specific type of toast notification. To hide multiple toast types, separate them using `,`. Possible values: `success`, `error`, `warning`, `info`. |
| `audioFollowsVideo` | `Boolean` | Optional | `false` | Allows automatically switching the audio to the one associated with the selected video source. |
| `forcePlayoutDelayMin` | `Number` | Optional | `null` | Sets a minimum value for a custom delay to playback the stream. It needs to be set with its maximum value, forcePlayoutDelayMax. |
| `forcePlayoutDelayMax` | `Number` | Optional | `null` | Sets a maximum value for a custom delay to playback the stream. It needs to be set with its minimum value, forcePlayoutDelayMin. |
| `showTimer` | `Boolean` | Optional | `false` | The current playing time will be displayed next to the volume icon. |
| `abrStrategy` | `string` | Optional | `null` | The ABR strategy to be utilized for initial playback. Possible values inlude `bandwidth`, `quality` and `performance`. |
| `abrBandwidth` | `number` | Optional | `null` | The initial bitrate, in bits per second, to be used in conjunction with the ABR strategy. |
To be able to use the viewer, just reference the `VideoPlayer` component, and pass the parameters of your choice as an object in the parameter `paramsOptions`. Refer to the [example usage](#example-apps).
#### hideButtons options
You can choose to show or hide certain buttons in the player in order to customize your experience.
| Option | Description |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| `play` | Hides the _play_ button. |
| `volume` | Hides the _volume_ button. |
| `pip` | Hides the button that allows the small reproduction (picture-in-picture mode), in a corner of the window. |
| `fullscreen` | Hides the _fullscreen_ button. |
| `liveBadge` | Hides the message that indicates whether the stream is live or not. |
| `userCount` | Hides the number of concurrent viewers of the stream. |
| `settings` | Hides the _settings_ button. |
In case you want to disable all buttons at once, you can simply pass the `controls: false` paremeter, instead of using `hideButtons`.
#### Environment options
You are able to set up the following environment settings. You can refer to [`.env.sample`](.env.sample) as a starting point.
| Option | type | Description |
| --------------------------- | --------------------------- | -------------------------------------------------------------------- |
| `NODE_ENV` | `production \| development` | Determines if the main app is a `production` or `development` build. |
| `VUE_APP_TURN_ENDPOINT` | `url: string` | Sets the turn endpoint. |
| `VUE_APP_LIVEWS_ENDPOINT` | `url: string` | Sets the live views endpoint. |
| `VUE_APP_DIRECTOR_ENDPOINT` | `url: string` | Sets the director endpoint. |
| `VUE_APP_PUBLIC_PATH` | `url: string` | Sets the public path endpoint. |
| `VUE_APP_REPORT_URL` | `url: string` | The report playback URL. |
| `VUE_APP_CHROMECAST_ID` | `url: string` | Chromecast ID of your application. |
In case these parameters are not sent as a property, the plugin will use the default values specified in the .env file.
### Example of Use
```html
<VideoPlayer
:paramsOptions="{accountId: '...', streamName: '...', autoplay: false, hideButtons: ['liveBadge'] }"
/>
```
- Remember that `accountId` and `streamName` are the only requeried parameters.
- At the moment, this plugin allows **only one** instance of the component at a time in a project.
## Example Apps
## Live Chat Example
An example app is also provided which integrates [PubNub](https://www.pubnub.com/docs/) based live chat. You can find this example in the `examples/live-chat` folder.
To set your private PubNub & Dolby.io credentials, create a `.env` file in the root of your project directory. An example of this may be found in the `examples/live-chat/.env.sample`. More information on how to obtain your Dolby.io streaming credentials is available on the [Dolby.io Streaming Docs](https://docs.dolby.io/streaming-apis/docs) page.
In order to run this example app, execute the following commands:
```bash
cd examples/live-chat
npm install
npm run serve
```
This will install the dependencies and run the app.
## Plugin Test App
An example of an interactive and resizable sample app using the vue viewer plugin can be found in the `examples/plugin-test` folder.
This app is for testing purposes.
## Contribute
To develop and contribute to this project, refer to the instructions on how to set up your environment to start contributing [here](https://github.com/millicast/vue-viewer-plugin/blob/main/developer-info.md).
## License
Please refer to [LICENSE](https://github.com/millicast/vue-viewer-plugin/blob/main/LICENSE) file.