@kinescope/vue-kinescope-player
Version:
Vue.js wrapper for Kinescope player
607 lines (575 loc) • 11.6 kB
Markdown
# Vue wrapper for Kinescope Embed Player
Starting from version 2.0.0, this package works with Vue 3.
## Installation
Using npm:
```bash
npm install @kinescope/vue-kinescope-player --save
```
Using yarn:
```bash
yarn add @kinescope/vue-kinescope-player
```
## Getting Started
You can either import it in your whole project
```js
import KinescopePlayer from "@kinescope/vue-kinescope-player";
import { createApp } from "vue";
const app = createApp(App);
app.use(KinescopePlayer);
app.mount("#app");
```
or import it locally in a component
```js
import { KinescopePlayer } from "@kinescope/vue-kinescope-player";
export default {
components: { KinescopePlayer },
};
```
```vue
<!-- events -->
<template>
<kinescope-player
:video-id="200702846"
@ready="handleReady"
@play="handlePlay"
></kinescope-player>
</template>
```
```vue
<!-- methods -->
<template>
<div>
<kinescope-player
ref="kinescope"
:video-id="200702846"
@ready="handleReady"
></kinescope-player>
<button @click="handleClick" :disabled="!ready">Play</button>
</div>
</template>
<script>
import { ref } from "vue";
import { KinescopePlayer } from "@kinescope/vue-kinescope-player";
export default {
components: { KinescopePlayer },
setup() {
const ready = ref(false);
const kinescope = ref(null);
const handleReady = () => {
ready.value = true;
};
const handleClick = () => {
kinescope.value.player.play();
};
return {
ready,
kinescope,
handleReady,
handleClick,
};
},
};
</script>
```
## Props
### General
<table>
<tr>
<th>Prop</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>video-id</td>
<td>Number, String</td>
<td>-</td>
<td>Video id from <a href="https://app.kinescope.io/">app.kinescope.io</a></td>
<td>Yes</td>
</tr>
<tr>
<td>width</td>
<td>Number, String</td>
<td>100%</td>
<td>Player width</td>
<td>No</td>
</tr>
<tr>
<td>height</td>
<td>Number, String</td>
<td>100%</td>
<td>Player height</td>
<td>No</td>
</tr>
<tr>
<td>external-id</td>
<td>String</td>
<td>-</td>
<td>External user ID passed to Kinescope analytics</td>
<td>No</td>
</tr>
</table>
### Behavior
<table>
<tr>
<th>Prop</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>auto-play</td>
<td>Boolean, String</td>
<td>false</td>
<td>Autostart playback. <code>'viewable'</code> — start when player enters viewport, <code>'hover'</code> — play while cursor is over player</td>
<td>No</td>
</tr>
<tr>
<td>muted</td>
<td>Boolean</td>
<td>false</td>
<td>Start video muted</td>
<td>No</td>
</tr>
<tr>
<td>loop</td>
<td>Boolean</td>
<td>false</td>
<td>Loop the video</td>
<td>No</td>
</tr>
<tr>
<td>plays-inline</td>
<td>Boolean</td>
<td>true</td>
<td>Play inline on mobile without auto-entering fullscreen</td>
<td>No</td>
</tr>
<tr>
<td>volume</td>
<td>Number</td>
<td>-</td>
<td>Initial volume level (0–1). Reactive: updates volume without reloading the player</td>
<td>No</td>
</tr>
<tr>
<td>playback-rate</td>
<td>Number</td>
<td>-</td>
<td>Initial playback rate (1 = normal). Reactive: updates speed without reloading the player</td>
<td>No</td>
</tr>
<tr>
<td>text-track</td>
<td>Boolean, String</td>
<td>-</td>
<td>Enable subtitles on load. Pass <code>true</code> for default or a language code e.g. <code>'ru'</code></td>
<td>No</td>
</tr>
</table>
### UI
<table>
<tr>
<th>Prop</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>language</td>
<td>String</td>
<td>en</td>
<td>Player UI language</td>
<td>No</td>
</tr>
<tr>
<td>controls</td>
<td>Boolean</td>
<td>true</td>
<td>Show all player controls. When <code>false</code>, hides everything including title and control bar</td>
<td>No</td>
</tr>
<tr>
<td>title</td>
<td>Boolean</td>
<td>true</td>
<td>Show video title overlay</td>
<td>No</td>
</tr>
<tr>
<td>control-bar</td>
<td>Boolean, String</td>
<td>true</td>
<td>Show bottom control bar. <code>'always'</code> — keep visible even during playback</td>
<td>No</td>
</tr>
<tr>
<td>progress-bar</td>
<td>Boolean</td>
<td>true</td>
<td>Show progress / seek bar</td>
<td>No</td>
</tr>
<tr>
<td>main-play-button</td>
<td>Boolean</td>
<td>true</td>
<td>Show the large center play button</td>
<td>No</td>
</tr>
<tr>
<td>play-button</td>
<td>Boolean</td>
<td>true</td>
<td>Show play/pause button in the control bar</td>
<td>No</td>
</tr>
<tr>
<td>volume-button</td>
<td>Boolean</td>
<td>true</td>
<td>Show volume button in the control bar</td>
<td>No</td>
</tr>
<tr>
<td>playback-rate-button</td>
<td>Boolean</td>
<td>false</td>
<td>Show playback rate button in the control bar</td>
<td>No</td>
</tr>
<tr>
<td>playback-rates</td>
<td>Array, Boolean</td>
<td>-</td>
<td>Available playback rates list e.g. <code>[0.5, 1, 1.5, 2]</code>. <code>false</code> hides the button</td>
<td>No</td>
</tr>
<tr>
<td>subtitles-button</td>
<td>Boolean</td>
<td>true</td>
<td>Show subtitles (CC) button in the control bar</td>
<td>No</td>
</tr>
<tr>
<td>settings-button</td>
<td>Boolean</td>
<td>true</td>
<td>Show settings button in the control bar</td>
<td>No</td>
</tr>
<tr>
<td>pip-button</td>
<td>Boolean</td>
<td>true</td>
<td>Show Picture-in-Picture button in the control bar</td>
<td>No</td>
</tr>
<tr>
<td>fullscreen-button</td>
<td>Boolean, String</td>
<td>true</td>
<td>Show fullscreen button. <code>'force'</code> — always show even if fullscreen API is unavailable</td>
<td>No</td>
</tr>
<tr>
<td>video-fit</td>
<td>String</td>
<td>contain</td>
<td>How video fits the player container: <code>'contain'</code> | <code>'cover'</code> | <code>'fill'</code></td>
<td>No</td>
</tr>
<tr>
<td>watermark</td>
<td>String, Object</td>
<td>-</td>
<td>
Watermark displayed over the video. Pass a string as shorthand or a full options object:<br/>
<code>{ text: string, mode?: 'random' | 'stripes', scale?: number, displayTimeout?: number | { visible: number, hidden: number } }</code><br/>
Reactive: changing this prop updates the watermark without reloading the player.
</td>
<td>No</td>
</tr>
</table>
## Events
<table>
<tr>
<th>Event</th>
<th>Data</th>
</tr>
<tr>
<td>js-load</td>
<td>No</td>
</tr>
<tr>
<td>js-load-error</td>
<td>No</td>
</tr>
<tr>
<td>ready</td>
<td>
currentTime: number<br/>
duration: number<br/>
quality: string | number<br/>
qualityLevels: {}
</td>
</tr>
<tr>
<td>quality-changed</td>
<td>quality: string | number</td>
</tr>
<tr>
<td>auto-quality-changed</td>
<td>quality: string | number</td>
</tr>
<tr>
<td>seek-chapter</td>
<td>position: number</td>
</tr>
<tr>
<td>size-changed</td>
<td>
width: number<br/>
height: number
</td>
</tr>
<tr>
<td>play</td>
<td>No</td>
</tr>
<tr>
<td>playing</td>
<td>No</td>
</tr>
<tr>
<td>waiting</td>
<td>No</td>
</tr>
<tr>
<td>pause</td>
<td>No</td>
</tr>
<tr>
<td>ended</td>
<td>No</td>
</tr>
<tr>
<td>time-update</td>
<td>currentTime: number</td>
</tr>
<tr>
<td>progress</td>
<td>bufferedTime: number</td>
</tr>
<tr>
<td>duration-change</td>
<td>duration: number</td>
</tr>
<tr>
<td>volume-change</td>
<td>
muted: boolean<br/>
volume: number
</td>
</tr>
<tr>
<td>playback-rate-change</td>
<td>playbackRate: number</td>
</tr>
<tr>
<td>seeking</td>
<td>No</td>
</tr>
<tr>
<td>seeked</td>
<td>No</td>
</tr>
<tr>
<td>fullscreen-change</td>
<td>
isFullscreen: boolean<br/>
video: boolean
</td>
</tr>
<tr>
<td>call-action</td>
<td>
id: string<br/>
title?: string<br/>
type: string
</td>
</tr>
<tr>
<td>call-bookmark</td>
<td>
id: string<br/>
time: number<br/>
title?: string
</td>
</tr>
<tr>
<td>error</td>
<td>error: unknown</td>
</tr>
<tr>
<td>destroy</td>
<td>No</td>
</tr>
</table>
## Methods
<table>
<tr>
<th>Method</th>
<th>Params</th>
<th>Result</th>
</tr>
<tr>
<td>isPaused</td>
<td>No</td>
<td>Promise<boolean></td>
</tr>
<tr>
<td>isEnded</td>
<td>No</td>
<td>Promise<boolean></td>
</tr>
<tr>
<td>play</td>
<td>No</td>
<td>Promise<void></td>
</tr>
<tr>
<td>pause</td>
<td>No</td>
<td>Promise<boolean></td>
</tr>
<tr>
<td>stop</td>
<td>No</td>
<td>Promise<void></td>
</tr>
<tr>
<td>getCurrentTime</td>
<td>No</td>
<td>Promise<number></td>
</tr>
<tr>
<td>getDuration</td>
<td>No</td>
<td>Promise<number></td>
</tr>
<tr>
<td>seekTo</td>
<td>(time: number)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>isMuted</td>
<td>No</td>
<td>Promise<boolean></td>
</tr>
<tr>
<td>mute</td>
<td>No</td>
<td>Promise<void></td>
</tr>
<tr>
<td>unmute</td>
<td>No</td>
<td>Promise<void></td>
</tr>
<tr>
<td>getVolume</td>
<td>No</td>
<td>Promise<number></td>
</tr>
<tr>
<td>setVolume</td>
<td>(value: number)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>getPlaybackRate</td>
<td>No</td>
<td>Promise<number></td>
</tr>
<tr>
<td>setPlaybackRate</td>
<td>(value: number)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>getVideoQualityList</td>
<td>No</td>
<td>Promise<VideoQuality[]></td>
</tr>
<tr>
<td>getCurrentVideoQuality</td>
<td>No</td>
<td>Promise<VideoQuality></td>
</tr>
<tr>
<td>setVideoQuality</td>
<td>(quality: VideoQuality)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>enableTextTrack</td>
<td>(lang: string)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>disableTextTrack</td>
<td>No</td>
<td>Promise<void></td>
</tr>
<tr>
<td>closeCTA</td>
<td>No</td>
<td>Promise<void></td>
</tr>
<tr>
<td>isFullscreen</td>
<td>No</td>
<td>Promise<boolean></td>
</tr>
<tr>
<td>setFullscreen</td>
<td>(fullscreen: boolean)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>isPip</td>
<td>No</td>
<td>Promise<boolean></td>
</tr>
<tr>
<td>setPip</td>
<td>(pip: boolean)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>getPlaylistItem</td>
<td>No</td>
<td>Promise<object></td>
</tr>
<tr>
<td>switchTo</td>
<td>(id: string)</td>
<td>Promise<void></td>
</tr>
<tr>
<td>next</td>
<td>No</td>
<td>Promise<void></td>
</tr>
<tr>
<td>previous</td>
<td>No</td>
<td>Promise<void></td>
</tr>
</table>