Controle do player

Atualizado: 12.08.2026

Você recebe o objeto de controle do player por create() . Use-o para iniciar a reprodução, atualizar configurações e assinar eventos.

Exemplo rápido

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

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

Propriedades

Propriedade	Tipo	Descrição
`Events`	`IframePlayerApi.Events`	Enumeração dos eventos do player

Métodos

Assinatura de eventos

Método	Retorno	Descrição
`on(type, listener)`	`this`	Assina um evento
`once(type, listener)`	`this`	Assina um evento uma única vez
`off(type, listener)`	`this`	Cancela a assinatura de um evento

Reprodução

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

Áudio

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

Qualidade e legendas

Método	Retorno	Descrição
`getVideoQualityList()`	`Promise<VideoQuality[]>`	Lista dos níveis de qualidade disponíveis
`getVideoQuality()`	`Promise<VideoQuality>`	Qualidade atual
`setVideoQuality(quality)`	`Promise<void>`	Define a qualidade
`enableTextTrack(lang)`	`Promise<void>`	Ativa as legendas no idioma `lang`
`disableTextTrack()`	`Promise<void>`	Desativa as legendas

Tela cheia e PiP

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

Playlist e CTA

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

Opções de switchTo

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

Parâmetros de setPlaylistItemOptions

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

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](/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
`setOptions(options)`	`Promise<void>`	Atualiza as opções do player com UpdatablePlayerOptions
`destroy()`	`Promise<void>`	Remove o `<iframe>` do player do DOM

Parâmetros de setOptions

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:

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

Eventos do player

Cada handler recebe um objeto de evento . O campo data depende do tipo de evento e pode estar ausente.

Ciclo de reprodução

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

{
  /** 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}

Evento	Dados	Descrição
`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
`CurrentTrackChanged`	`{ item: { id?: string } }`	A faixa atual mudou
`SizeChanged`	`{ width, height }`	O tamanho do player mudou
`QualityChanged`	`{ quality }`	A qualidade do vídeo mudou
`Play`	—	Reprodução solicitada
`Playing`	—	Reprodução iniciada
`Pause`	—	Reprodução pausada
`Ended`	—	Reprodução encerrada
`TimeUpdate`	`{ currentTime, percent }`	O tempo atual mudou
`Waiting`	—	Armazenamento em buffer
`Progress`	`{ bufferedTime }`	O recurso de mídia está sendo carregado
`DurationChange`	`{ duration }`	A duração do vídeo mudou
`VolumeChange`	`{ volume, muted }`	O nível de volume mudou
`PlaybackRateChange`	`{ playbackRate }`	A velocidade de reprodução mudou
`Seeked`	—	O avanço ou retrocesso foi concluído
`SeekChapter`	`{ position }`	A reprodução mudou para um capítulo
`FullscreenChange`	`{ isFullscreen, type, video? }`	O modo de tela cheia mudou. `type`: `'video' \| 'pseudo' \| 'native'`. `video` é `@deprecated`; use `type`
`PipChange`	`{ isPip }`	Modo Picture-in-Picture. Can I use
`CallAction`	`{ id }`	CTA ativada. `@experimental`
`CallBookmark`	`{ id, time }`	Marcador selecionado. `@experimental`
`AdBreakStateChanged`	`{ active }`	O estado do intervalo de publicidade mudou. `@experimental`
`ControlBarVisibilityChanged`	`{ visible }`	A visibilidade da barra de controle mudou. `@experimental`
`Error`	`{ error }`	Erro crítico
`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 — playlists dinâmicas e estáticas
CTA — chamadas para ação exibidas sobre o vídeo
Publicidade — VAST/IMA e acionadores
player-iframe-api-loader — loader npm e tipos
Conexão automática — API para um iframe existente
Criação de um player — factory e CreateOptions