# Controle do player


Você recebe o objeto de controle do player por [`create()`](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-create-player/#create). Use-o para iniciar a reprodução, atualizar configurações e assinar eventos.

## Exemplo rápido

```js
player.on(player.Events.Playing, () => {
  console.log('reprodução iniciada')
})

await player.setVolume(0.5)
await player.play()
```

## Propriedades {#events}

| Propriedade | Tipo | Descrição |
| :--- | :--- | :--- |
| `Events` | `IframePlayerApi.Events` | Enumeração dos [eventos do player](#event-data) |

## Métodos

### Assinatura de eventos

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| <a id="on"></a>`on(type, listener)` | `this` | Assina um [evento](#event-data) |
| <a id="once"></a>`once(type, listener)` | `this` | Assina um evento uma única vez |
| <a id="off"></a>`off(type, listener)` | `this` | Cancela a assinatura de um evento |

### Reprodução

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| <a id="play"></a>`play()` | `Promise<void>` | Inicia a reprodução |
| <a id="pause"></a>`pause()` | `Promise<void>` | Pausa a reprodução |
| <a id="stop"></a>`stop()` | `Promise<void>` | Interrompe a reprodução e volta ao início |
| <a id="seekTo"></a>`seekTo(time)` | `Promise<void>` | Avança ou retrocede até um tempo em segundos |
| <a id="isPaused"></a>`isPaused()` | `Promise<boolean>` | Verifica se a reprodução está pausada |
| <a id="isEnded"></a>`isEnded()` | `Promise<boolean>` | Verifica se a reprodução terminou |
| <a id="getCurrentTime"></a>`getCurrentTime()` | `Promise<number>` | Tempo atual em segundos |
| <a id="getDuration"></a>`getDuration()` | `Promise<number>` | Duração do vídeo em segundos |
| <a id="getPlaybackRate"></a>`getPlaybackRate()` | `Promise<number>` | Velocidade de reprodução. `1` é a velocidade normal |
| <a id="setPlaybackRate"></a>`setPlaybackRate(value)` | `Promise<void>` | Define a velocidade de reprodução |

### Áudio

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| <a id="mute"></a>`mute()` | `Promise<void>` | Desativa o som do player |
| <a id="unmute"></a>`unmute()` | `Promise<void>` | Ativa o som do player |
| <a id="isMuted"></a>`isMuted()` | `Promise<boolean>` | Verifica se o player está sem som |
| <a id="getVolume"></a>`getVolume()` | `Promise<number>` | Volume de `0` a `1` |
| <a id="setVolume"></a>`setVolume(value)` | `Promise<void>` | Define o volume de `0` a `1` |

### Qualidade e legendas

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| <a id="getVideoQualityList"></a>`getVideoQualityList()` | `Promise<VideoQuality[]>` | Lista dos [níveis de qualidade](https://docs-br.kinescope.com/player-docs/optimization/#qualidade-do-video) disponíveis |
| <a id="getVideoQuality"></a>`getVideoQuality()` | `Promise<VideoQuality>` | [Qualidade](https://docs-br.kinescope.com/player-docs/optimization/#qualidade-do-video) atual |
| <a id="setVideoQuality"></a>`setVideoQuality(quality)` | `Promise<void>` | Define a [qualidade](https://docs-br.kinescope.com/player-docs/optimization/#qualidade-do-video) |
| <a id="enableTextTrack"></a>`enableTextTrack(lang)` | `Promise<void>` | Ativa as legendas no idioma `lang` |
| <a id="disableTextTrack"></a>`disableTextTrack()` | `Promise<void>` | Desativa as legendas |

### Tela cheia e PiP

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| <a id="isFullscreen"></a>`isFullscreen()` | `Promise<boolean>` | Verifica se o modo de tela cheia está ativo |
| <a id="setFullscreen"></a>`setFullscreen(fullscreen)` | `Promise<void>` | Ativa ou desativa o modo de tela cheia |
| <a id="isPip"></a>`isPip()` | `Promise<boolean>` | Verifica se o Picture-in-Picture está ativo |
| <a id="setPip"></a>`setPip(pip)` | `Promise<void>` | Ativa ou desativa o PiP |

### Playlist e CTA

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| <a id="getPlaylistItem"></a>`getPlaylistItem()` | `Promise<{ id?: string } \| undefined>` | Vídeo atual da playlist |
| <a id="switchTo"></a>`switchTo(id, options?)` | `Promise<void>` | Muda para o vídeo com este `id` e as [opções](#switchTo-options) opcionais |
| <a id="next"></a>`next()` | `Promise<void>` | Muda para o próximo vídeo da playlist |
| <a id="previous"></a>`previous()` | `Promise<void>` | Muda para o vídeo anterior da playlist |
| <a id="closeCTA"></a>`closeCTA()` | `Promise<void>` | Fecha a tela de CTA. `@experimental` |
| <a id="setPlaylistItemOptions"></a>`setPlaylistItemOptions(options)` | `Promise<void>` | Define as opções do vídeo atual com [PlaylistItemOptions](#setPlaylistItemOptions-options) |

#### Opções de switchTo {#switchTo-options}

```ts
interface SwitchToOptions {
  autoPlay?: boolean;
  time?: number;
}
```

#### Parâmetros de setPlaylistItemOptions {#setPlaylistItemOptions-options}

Define título, legendas, capítulos, CTA, DRM e publicidade para o vídeo atual.

```ts
interface AdItemYaOptions {
  // Consulte https://yandex.ru/dev/video-sdk/doc/ru/sdk-html5/AdConfig-interface
  adConfig: Record<string, unknown>;
  // Consulte https://yandex.ru/dev/video-sdk/doc/ru/sdk-html5/PlaybackParameters-interface
  playbackParameters?: Record<string, unknown>;
}

type AdItemOptions =
  | {
      /** URL da tag de publicidade. */
      adTagUrl: string | string[];
    }
  | {
      /** @experimental Texto completo da tag de publicidade. */
      adTag: string | string[];
    }
  | {
      /** @experimental Objeto de solicitação do Google IMA (`adsRequest`). */
      adsRequest: Record<string, unknown>;
    }
  | {
      /** @experimental Configurações do Yandex Video Ads SDK. */
      yaOptions: AdItemYaOptions | AdItemYaOptions[];
    };

interface PlaylistItemOptions {
  /** Título do vídeo. Exibido na parte superior do player. */
  title?: string;

  /** Subtítulo do vídeo. Exibido abaixo do título principal. */
  subtitle?: string;

  /** Imagem de capa do vídeo. */
  poster?: string;

  /** Legendas (faixas de texto do vídeo). */
  vtt?: {
    /** Título */
    label: string;
    /** URL do arquivo de legenda */
    src: string;
    /** Idioma da legenda */
    srcLang: string;
  }[];

  /** Capítulos que dividem a linha do tempo do vídeo. */
  chapters?: {
    /** Tempo em segundos */
    position: number;
    /** Título */
    title: string;
  }[];

  /** Materiais adicionais para download. */
  files?: {
    list: {
      name: string;
      url: string;
      mime: string;
      size?: number;
    }[];
    archiveUrl?: string;
  };

  /** @experimental Marcadores associados a momentos do vídeo. */
  bookmarks?: {
    id: string;
    /** Tempo em segundos. */
    time: number;
  }[];

  /**
   * @experimental Chamadas para ação (CTA).
   * `type`: overlay | popup | panel | banner | buttons | leadgen. Padrão: overlay.
   * Consulte todos os campos de cada tipo na seção CTA: /player-docs/cta/
   */
  cta?: {
    id: string;
    type?: 'overlay' | 'popup' | 'panel' | 'banner' | 'buttons' | 'leadgen';
    title?: string;
    description?: string;
    skippable?: boolean;
    button?: { text: string; style?: CSSProperties; url?: string };
    trigger: {
      percentages?: number[];
      timePoints?: number[];
      pause?: boolean;
    };
    // + campos do tipo selecionado (link, position, list, fields, url, …)
  }[];

  /** DRM. */
  drm?: {
    auth?: {
      /** Token de autorização personalizado para solicitações de licença. */
      token?: string;
    };
  };

  /** Publicidade. Consulte [Publicidade](https://docs-br.kinescope.com/player-docs/advertising/). */
  ad?:
    | AdItemOptions
    | (AdItemOptions & {
        /** Acionador de publicidade. */
        trigger: {
          /** Porcentagem do tempo atual. Por exemplo: `[0, 100]`. */
          percentages?: number[];
          /** Momentos em segundos. Por exemplo: `[60, 600]`. */
          timePoints?: number[];
          /** Intervalo de repetição em segundos. Por exemplo, `600` significa a cada 10 minutos. */
          interval?: number;
        };
      })[];
}
```

### Configurações e destruição

| Método | Retorno | Descrição |
| :--- | :--- | :--- |
| <a id="setOptions"></a>`setOptions(options)` | `Promise<void>` | Atualiza as opções do player com [UpdatablePlayerOptions](#setOptions-options) |
| <a id="destroy"></a>`destroy()` | `Promise<void>` | Remove o `<iframe>` do player do DOM |

#### Parâmetros de setOptions {#setOptions-options}

```ts
interface UpdatablePlayerOptions {
  /** Configurações da interface */
  ui?: {
    /** Marca d'água. */
    watermark?: {
      /** Texto */
      text: string;
      /**
       * - `stripes` - exibe em linhas;
       * - `random` - exibe em posições aleatórias;
       * Padrão: `random`.
       */
      mode?: 'stripes' | 'random';
      /** Fator de escala do texto baseado no tamanho do player. Padrão: `0.25`. */
      scale?: number;
      /** Duração da exibição e ocultação em milissegundos. Se omitido, o texto permanece visível. */
      displayTimeout?: number | { visible: number; hidden: number };
    };
  };
}
```

Exemplo:

```ts
player.setOptions({ ui: { watermark: { text: 'marca d’água' } } })
```

## Eventos do player {#player-events}

Cada handler recebe um [objeto de evento](#event-object). O campo `data` depende do tipo de evento e pode estar ausente.

### Ciclo de reprodução {#lifecycle}

Os principais eventos ocorrem nesta ordem:

```
create → Loaded → Play → Playing → TimeUpdate* → Pause / Ended → Destroy
```

| Evento | Quando ocorre |
| :--- | :--- |
| `Loaded` | O player está pronto para reproduzir. Com `preload: false`, ocorre quando a reprodução começa |
| `Play` | A reprodução é solicitada pelo botão Play ou por `play()` |
| `Playing` | A reprodução começou |
| `TimeUpdate` | Periodicamente durante a reprodução |
| `Waiting` | O player está armazenando dados em buffer |
| `Pause` / `Ended` | A reprodução está pausada ou o vídeo terminou |
| `Destroy` | O player foi removido do DOM |

Quando o vídeo da playlist muda, `CurrentTrackChanged` ocorre primeiro, seguido por `Loaded` para o novo vídeo.

### Objeto de evento {#event-object}

```ts
{
  /** Tipo de evento */
  type: IframePlayerApi.Events;
  /** Dados do evento. A estrutura depende do tipo de evento e pode estar ausente. */
  data: Data;
  /** Objeto de controle do player associado ao evento */
  target: IframePlayerApi;
}
```

### Enumeração de eventos {#event-data} <a id="EventListeners"></a>

| Evento | Dados | Descrição |
| :--- | :--- | :--- |
| <a id="Events.Loaded"></a>`Loaded` | `{ currentTime, duration, quality, audioTrack }` | Os dados do vídeo foram carregados e o player está pronto. Com `preload: 'none'`, ocorre quando a reprodução começa |
| <a id="Events.CurrentTrackChanged"></a>`CurrentTrackChanged` | `{ item: { id?: string } }` | A faixa atual mudou |
| <a id="Events.SizeChanged"></a>`SizeChanged` | `{ width, height }` | O tamanho do player mudou |
| <a id="Events.QualityChanged"></a>`QualityChanged` | `{ quality }` | A qualidade do vídeo mudou |
| <a id="Events.Play"></a>`Play` | — | Reprodução solicitada |
| <a id="Events.Playing"></a>`Playing` | — | Reprodução iniciada |
| <a id="Events.Pause"></a>`Pause` | — | Reprodução pausada |
| <a id="Events.Ended"></a>`Ended` | — | Reprodução encerrada |
| <a id="Events.TimeUpdate"></a>`TimeUpdate` | `{ currentTime, percent }` | O tempo atual mudou |
| <a id="Events.Waiting"></a>`Waiting` | — | Armazenamento em buffer |
| <a id="Events.Progress"></a>`Progress` | `{ bufferedTime }` | O recurso de mídia está sendo carregado |
| <a id="Events.DurationChange"></a>`DurationChange` | `{ duration }` | A duração do vídeo mudou |
| <a id="Events.VolumeChange"></a>`VolumeChange` | `{ volume, muted }` | O nível de volume mudou |
| <a id="Events.PlaybackRateChange"></a>`PlaybackRateChange` | `{ playbackRate }` | A velocidade de reprodução mudou |
| <a id="Events.Seeked"></a>`Seeked` | — | O avanço ou retrocesso foi concluído |
| <a id="Events.SeekChapter"></a>`SeekChapter` | `{ position }` | A reprodução mudou para um capítulo |
| <a id="Events.FullscreenChange"></a>`FullscreenChange` | `{ isFullscreen, type, video? }` | O modo de tela cheia mudou. `type`: `'video' \| 'pseudo' \| 'native'`. `video` é `@deprecated`; use `type` |
| <a id="Events.PipChange"></a>`PipChange` | `{ isPip }` | Modo Picture-in-Picture. [Can I use](https://caniuse.com/picture-in-picture) |
| <a id="Events.CallAction"></a>`CallAction` | `{ id }` | CTA ativada. `@experimental` |
| <a id="Events.CallBookmark"></a>`CallBookmark` | `{ id, time }` | Marcador selecionado. `@experimental` |
| <a id="Events.AdBreakStateChanged"></a>`AdBreakStateChanged` | `{ active }` | O estado do intervalo de publicidade mudou. `@experimental` |
| <a id="Events.ControlBarVisibilityChanged"></a>`ControlBarVisibilityChanged` | `{ visible }` | A visibilidade da barra de controle mudou. `@experimental` |
| <a id="Events.Error"></a>`Error` | `{ error }` | Erro crítico |
| <a id="Events.Destroy"></a>`Destroy` | — | Player removido do DOM |

Os eventos estão disponíveis como `player.Events.<Name>`. Por exemplo, use `player.Events.Playing`.

## Próximos passos

- [Playlists](https://docs-br.kinescope.com/player-docs/playlists/) — playlists dinâmicas e estáticas
- [CTA](https://docs-br.kinescope.com/player-docs/cta/) — chamadas para ação exibidas sobre o vídeo
- [Publicidade](https://docs-br.kinescope.com/player-docs/advertising/) — VAST/IMA e acionadores
- [player-iframe-api-loader](https://docs-br.kinescope.com/player-docs/libraries/player-iframe-api-loader/) — loader npm e tipos
- [Conexão automática](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-auto-connect/) — API para um iframe existente
- [Criação de um player](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-create-player/) — factory e `CreateOptions`