# Vue


Este componente incorpora o Kinescope Player em aplicações Vue 3 e está disponível desde a versão 2.0.0 do pacote. Ele usa um iframe e a [IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api/) internamente. Repositório: [kinescope/vue-kinescope-player](https://github.com/kinescope/vue-kinescope-player).

## Instalação

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

## Início rápido

Registre o componente globalmente:

```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')
```

Registre-o localmente em um componente:

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

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

### Eventos

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

### Métodos

Os métodos ficam disponíveis por `ref` → `player`:

```vue
<template>
  <div>
    <kinescope-player
      ref="kinescope"
      video-id="VIDEO_ID"
      @ready="ready = true"
    />
    <button :disabled="!ready" @click="kinescope.player.play()">Reproduzir</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 nos templates (`video-id`) e camelCase nos scripts.

### Props principais

| Prop | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `video-id` | `number \| string` | — | ID do vídeo (**obrigatória**) |
| `width` | `number \| string` | `100%` | Largura |
| `height` | `number \| string` | `100%` | Altura |
| `external-id` | `string` | — | ID externo para análise de dados |

### Comportamento

| Prop | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `auto-play` | `boolean \| string` | `false` | Reprodução automática. `'viewable'` inicia a reprodução quando o player entra na área visível; `'hover'` inicia ao passar o cursor |
| `muted` | `boolean` | `false` | Inicia sem som |
| `loop` | `boolean` | `false` | Repete a reprodução |
| `plays-inline` | `boolean` | `true` | Reproduz em linha em dispositivos móveis, sem entrar automaticamente no modo de tela cheia |
| `volume` | `number` | — | Volume de 0 a 1. Atualizado de forma reativa, sem recarregar o player |
| `playback-rate` | `number` | — | Velocidade de reprodução. `1` é a velocidade normal. Atualizada de forma reativa |
| `text-track` | `boolean \| string` | — | Legendas ao carregar: `true` ou um código de idioma, como `'en'` |

### Interface

| Prop | Tipo | Padrão | Descrição |
| :--- | :--- | :--- | :--- |
| `language` | `string` | `en` | Idioma da interface |
| `controls` | `boolean` | `true` | Todos os controles. `false` oculta o título e a barra de controle |
| `title` | `boolean` | `true` | Título exibido sobre o vídeo |
| `control-bar` | `boolean \| string` | `true` | Barra de controle inferior. Use `'always'` para mantê-la visível |
| `progress-bar` | `boolean` | `true` | Barra de progresso |
| `main-play-button` | `boolean` | `true` | Botão grande de reprodução no centro |
| `play-button` | `boolean` | `true` | Botão Reproduzir/Pausar na barra de controle |
| `volume-button` | `boolean` | `true` | Botão de volume |
| `playback-rate-button` | `boolean` | `false` | Botão de velocidade de reprodução |
| `playback-rates` | `array \| boolean` | — | Lista de velocidades, por exemplo, `[0.5, 1, 1.5, 2]`. Use `false` para ocultar o botão |
| `subtitles-button` | `boolean` | `true` | Botão de legendas |
| `settings-button` | `boolean` | `true` | Botão de configurações |
| `pip-button` | `boolean` | `true` | Botão Picture-in-Picture |
| `fullscreen-button` | `boolean \| string` | `true` | Botão de tela cheia. Use `'force'` para exibi-lo sempre |
| `video-fit` | `string` | `contain` | `contain` \| `cover` \| `fill` |
| `watermark` | `string \| object` | — | Marca d'água como string ou objeto. Atualizada de forma reativa |

Objeto da marca d'água:

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

## Eventos

| Evento | Dados |
| :--- | :--- |
| `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` | — |

## Métodos

Chame um método com `kinescope.value.player.play()`.

| Método | Parâmetros | Resultado |
| :--- | :--- | :--- |
| `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>` |

## Próximos passos

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