# Vue


A component for embedding Kinescope Player in Vue 3 applications, supported since package version 2.0.0. It uses an iframe and the [IFrame API](https://docs.kinescope.com/player-docs/embedding/iframe-api/) under the hood. Repository: [kinescope/vue-kinescope-player](https://github.com/kinescope/vue-kinescope-player).

## Installation

```bash
npm install @kinescope/vue-kinescope-player --save
```

## Quick start

Register the component globally:

```js
import { createApp } from 'vue'
import KinescopePlayer from '@kinescope/vue-kinescope-player'
import App from './App.vue'

const app = createApp(App)
app.use(KinescopePlayer)
app.mount('#app')
```

Register it locally in a component:

```vue
<script setup>
import { KinescopePlayer } from '@kinescope/vue-kinescope-player'
</script>

<template>
  <kinescope-player video-id="VIDEO_ID" />
</template>
```

### Events

```vue
<template>
  <kinescope-player
    video-id="VIDEO_ID"
    @ready="handleReady"
    @play="handlePlay"
  />
</template>
```

### Methods

Methods are available through `ref` → `player`:

```vue
<template>
  <div>
    <kinescope-player
      ref="kinescope"
      video-id="VIDEO_ID"
      @ready="ready = true"
    />
    <button :disabled="!ready" @click="kinescope.player.play()">Play</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { KinescopePlayer } from '@kinescope/vue-kinescope-player'

const ready = ref(false)
const kinescope = ref(null)
</script>
```

## Props

Use kebab-case in templates (`video-id`) and camelCase in scripts.

### Core props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `video-id` | `number \| string` | — | Video ID (**required**) |
| `width` | `number \| string` | `100%` | Width |
| `height` | `number \| string` | `100%` | Height |
| `external-id` | `string` | — | External ID for analytics |

### Behavior

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `auto-play` | `boolean \| string` | `false` | Autoplay. `'viewable'` starts playback when the player enters the viewport; `'hover'` starts it on hover |
| `muted` | `boolean` | `false` | Start muted |
| `loop` | `boolean` | `false` | Loop playback |
| `plays-inline` | `boolean` | `true` | Play inline on mobile without automatically entering fullscreen |
| `volume` | `number` | — | Volume from 0 to 1. Updates reactively without reloading the player |
| `playback-rate` | `number` | — | Playback speed. `1` is normal speed. Updates reactively |
| `text-track` | `boolean \| string` | — | Subtitles on load: `true` or a language code such as `'en'` |

### Interface

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `language` | `string` | `en` | UI language |
| `controls` | `boolean` | `true` | All controls. `false` hides both the title and control bar |
| `title` | `boolean` | `true` | Title displayed over the video |
| `control-bar` | `boolean \| string` | `true` | Bottom control bar. Use `'always'` to keep it visible |
| `progress-bar` | `boolean` | `true` | Progress bar |
| `main-play-button` | `boolean` | `true` | Large Play button in the center |
| `play-button` | `boolean` | `true` | Play/Pause button on the control bar |
| `volume-button` | `boolean` | `true` | Volume button |
| `playback-rate-button` | `boolean` | `false` | Playback speed button |
| `playback-rates` | `array \| boolean` | — | List of speeds, for example `[0.5, 1, 1.5, 2]`. Set to `false` to hide the button |
| `subtitles-button` | `boolean` | `true` | Subtitles button |
| `settings-button` | `boolean` | `true` | Settings button |
| `pip-button` | `boolean` | `true` | Picture-in-Picture button |
| `fullscreen-button` | `boolean \| string` | `true` | Fullscreen button. Use `'force'` to always show it |
| `video-fit` | `string` | `contain` | `contain` \| `cover` \| `fill` |
| `watermark` | `string \| object` | — | Watermark as a string or object. Updates reactively |

Watermark object:

```ts
{
  text: string
  mode?: 'random' | 'stripes'
  scale?: number
  displayTimeout?: number | { visible: number; hidden: number }
}
```

## Events

| Event | Data |
| :--- | :--- |
| `js-load` | — |
| `js-load-error` | — |
| `ready` | `{ currentTime, duration, quality, qualityLevels }` |
| `quality-changed` | `{ quality }` |
| `auto-quality-changed` | `{ quality }` |
| `seek-chapter` | `{ position }` |
| `size-changed` | `{ width, height }` |
| `play` | — |
| `playing` | — |
| `waiting` | — |
| `pause` | — |
| `ended` | — |
| `time-update` | `{ currentTime }` |
| `progress` | `{ bufferedTime }` |
| `duration-change` | `{ duration }` |
| `volume-change` | `{ muted, volume }` |
| `playback-rate-change` | `{ playbackRate }` |
| `seeking` | — |
| `seeked` | — |
| `fullscreen-change` | `{ isFullscreen, video }` |
| `call-action` | `{ id, title?, type }` |
| `call-bookmark` | `{ id, time, title? }` |
| `error` | `{ error }` |
| `destroy` | — |

## Methods

Call a method with `kinescope.value.player.play()`.

| Method | Parameters | Result |
| :--- | :--- | :--- |
| `isPaused` | — | `Promise<boolean>` |
| `isEnded` | — | `Promise<boolean>` |
| `play` | — | `Promise<void>` |
| `pause` | — | `Promise<boolean>` |
| `stop` | — | `Promise<void>` |
| `getCurrentTime` | — | `Promise<number>` |
| `getDuration` | — | `Promise<number>` |
| `seekTo` | `(time: number)` | `Promise<void>` |
| `isMuted` | — | `Promise<boolean>` |
| `mute` | — | `Promise<void>` |
| `unmute` | — | `Promise<void>` |
| `getVolume` | — | `Promise<number>` |
| `setVolume` | `(value: number)` | `Promise<void>` |
| `getPlaybackRate` | — | `Promise<number>` |
| `setPlaybackRate` | `(value: number)` | `Promise<void>` |
| `getVideoQualityList` | — | `Promise<VideoQuality[]>` |
| `getCurrentVideoQuality` | — | `Promise<VideoQuality>` |
| `setVideoQuality` | `(quality: VideoQuality)` | `Promise<void>` |
| `enableTextTrack` | `(lang: string)` | `Promise<void>` |
| `disableTextTrack` | — | `Promise<void>` |
| `closeCTA` | — | `Promise<void>` |
| `isFullscreen` | — | `Promise<boolean>` |
| `setFullscreen` | `(fullscreen: boolean)` | `Promise<void>` |
| `isPip` | — | `Promise<boolean>` |
| `setPip` | `(pip: boolean)` | `Promise<void>` |
| `getPlaylistItem` | — | `Promise<object>` |
| `switchTo` | `(id: string)` | `Promise<void>` |
| `next` | — | `Promise<void>` |
| `previous` | — | `Promise<void>` |

## Next steps

- [React](https://docs.kinescope.com/player-docs/libraries/react/)
- [Angular](https://docs.kinescope.com/player-docs/libraries/angular/)
- [IFrame API](https://docs.kinescope.com/player-docs/embedding/iframe-api/)