Controlling the player

Updated: 12.08.2026

You receive the player control object from create() . Use it to start playback, update settings, and subscribe to events.

Quick example

player.on(player.Events.Playing, () => {
  console.log('playback started')
})

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

Properties

Property	Type	Description
`Events`	`IframePlayerApi.Events`	Enumeration of player events

Methods

Event subscriptions

Method	Returns	Description
`on(type, listener)`	`this`	Subscribe to an event
`once(type, listener)`	`this`	Subscribe to an event once
`off(type, listener)`	`this`	Unsubscribe from an event

Playback

Method	Returns	Description
`play()`	`Promise<void>`	Start playback
`pause()`	`Promise<void>`	Pause playback
`stop()`	`Promise<void>`	Stop playback and seek to the beginning
`seekTo(time)`	`Promise<void>`	Seek to a time in seconds
`isPaused()`	`Promise<boolean>`	Check whether playback is paused
`isEnded()`	`Promise<boolean>`	Check whether playback has ended
`getCurrentTime()`	`Promise<number>`	Current time in seconds
`getDuration()`	`Promise<number>`	Video duration in seconds
`getPlaybackRate()`	`Promise<number>`	Playback speed. `1` is the normal speed
`setPlaybackRate(value)`	`Promise<void>`	Set the playback speed

Audio

Method	Returns	Description
`mute()`	`Promise<void>`	Mute the player
`unmute()`	`Promise<void>`	Unmute the player
`isMuted()`	`Promise<boolean>`	Check whether the player is muted
`getVolume()`	`Promise<number>`	Volume from `0` to `1`
`setVolume(value)`	`Promise<void>`	Set the volume from `0` to `1`

Quality and subtitles

Method	Returns	Description
`getVideoQualityList()`	`Promise<VideoQuality[]>`	List of available quality levels
`getVideoQuality()`	`Promise<VideoQuality>`	Current quality
`setVideoQuality(quality)`	`Promise<void>`	Set the quality
`enableTextTrack(lang)`	`Promise<void>`	Enable subtitles in the `lang` language
`disableTextTrack()`	`Promise<void>`	Disable subtitles

Fullscreen and PiP

Method	Returns	Description
`isFullscreen()`	`Promise<boolean>`	Check whether fullscreen mode is active
`setFullscreen(fullscreen)`	`Promise<void>`	Enable or disable fullscreen mode
`isPip()`	`Promise<boolean>`	Check whether Picture-in-Picture is active
`setPip(pip)`	`Promise<void>`	Enable or disable PiP

Playlist and CTA

Method	Returns	Description
`getPlaylistItem()`	`Promise<{ id?: string } \| undefined>`	Current playlist video
`switchTo(id, options?)`	`Promise<void>`	Switch to the video with this `id` and optional options
`next()`	`Promise<void>`	Switch to the next playlist video
`previous()`	`Promise<void>`	Switch to the previous playlist video
`closeCTA()`	`Promise<void>`	Close the CTA screen. `@experimental`
`setPlaylistItemOptions(options)`	`Promise<void>`	Set the current video options with PlaylistItemOptions

switchTo options

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

setPlaylistItemOptions parameters

Set the title, subtitles, chapters, CTA, DRM, and advertising for the current video.

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

type AdItemOptions =
  | {
      /** Advertising tag URL. */
      adTagUrl: string | string[];
    }
  | {
      /** @experimental Complete advertising tag text. */
      adTag: string | string[];
    }
  | {
      /** @experimental Google IMA request object (`adsRequest`). */
      adsRequest: Record<string, unknown>;
    }
  | {
      /** @experimental Settings for Yandex Video Ads SDK. */
      yaOptions: AdItemYaOptions | AdItemYaOptions[];
    };

interface PlaylistItemOptions {
  /** Video title. Displayed at the top of the player. */
  title?: string;

  /** Video subtitle. Displayed below the main title. */
  subtitle?: string;

  /** Video poster image. */
  poster?: string;

  /** Subtitles (video text tracks). */
  vtt?: {
    /** Title */
    label: string;
    /** Subtitle file URL */
    src: string;
    /** Subtitle language */
    srcLang: string;
  }[];

  /** Chapters that divide the video timeline. */
  chapters?: {
    /** Time in seconds */
    position: number;
    /** Title */
    title: string;
  }[];

  /** Additional downloadable materials. */
  files?: {
    list: {
      name: string;
      url: string;
      mime: string;
      size?: number;
    }[];
    archiveUrl?: string;
  };

  /** @experimental Time-based bookmarks. */
  bookmarks?: {
    id: string;
    /** Time in seconds. */
    time: number;
  }[];

  /**
   * @experimental Calls to action (CTA).
   * `type`: overlay | popup | panel | banner | buttons | leadgen. Default: overlay.
   * See all fields by type in the CTA section: /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;
    };
    // + fields for the selected type (link, position, list, fields, url, …)
  }[];

  /** DRM. */
  drm?: {
    auth?: {
      /** Custom authorization token for license requests. */
      token?: string;
    };
  };

  /** Advertising. See [Advertising](/player-docs/advertising/). */
  ad?:
    | AdItemOptions
    | (AdItemOptions & {
        /** Advertising trigger. */
        trigger: {
          /** Current time percentage. For example: `[0, 100]`. */
          percentages?: number[];
          /** Time points in seconds. For example: `[60, 600]`. */
          timePoints?: number[];
          /** Repeat interval in seconds. For example, `600` means every 10 minutes. */
          interval?: number;
        };
      })[];
}

Settings and destruction

Method	Returns	Description
`setOptions(options)`	`Promise<void>`	Update player options with UpdatablePlayerOptions
`destroy()`	`Promise<void>`	Remove the player `<iframe>` from the DOM

setOptions parameters

interface UpdatablePlayerOptions {
  /** UI settings */
  ui?: {
    /** Watermark. */
    watermark?: {
      /** Text */
      text: string;
      /**
       * - `stripes` - display in lines;
       * - `random` - display in random locations;
       * Default: `random`.
       */
      mode?: 'stripes' | 'random';
      /** Text scaling factor based on the player size. Default: `0.25`. */
      scale?: number;
      /** Show and hide duration in milliseconds. If omitted, the text remains visible. */
      displayTimeout?: number | { visible: number; hidden: number };
    };
  };
}

Example:

player.setOptions({ ui: { watermark: { text: 'watermark' } } })

Player events

Each handler receives an event object . The data field depends on the event type and may be absent.

Playback lifecycle

The main events occur in this order:

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

Event	When it occurs
`Loaded`	The player is ready for playback. With `preload: false`, this occurs when playback starts
`Play`	Playback is requested with the Play button or `play()`
`Playing`	Playback has started
`TimeUpdate`	Periodically during playback
`Waiting`	The player is buffering
`Pause` / `Ended`	Playback is paused or the video ends
`Destroy`	The player is removed from the DOM

When the playlist video changes, CurrentTrackChanged occurs first, followed by Loaded for the new video.

Event object

{
  /** Event type */
  type: IframePlayerApi.Events;
  /** Event data. Its structure depends on the event type and may be absent. */
  data: Data;
  /** Player control object associated with the event */
  target: IframePlayerApi;
}

Event enumeration {#event-data}

Event	Data	Description
`Loaded`	`{ currentTime, duration, quality, audioTrack }`	Video data loaded and the player is ready. With `preload: 'none'`, this occurs when playback starts
`CurrentTrackChanged`	`{ item: { id?: string } }`	Current track changed
`SizeChanged`	`{ width, height }`	Player size changed
`QualityChanged`	`{ quality }`	Video quality changed
`Play`	—	Playback requested
`Playing`	—	Playback started
`Pause`	—	Playback paused
`Ended`	—	Playback ended
`TimeUpdate`	`{ currentTime, percent }`	Current time changed
`Waiting`	—	Buffering
`Progress`	`{ bufferedTime }`	Media resource is loading
`DurationChange`	`{ duration }`	Video duration changed
`VolumeChange`	`{ volume, muted }`	Volume level changed
`PlaybackRateChange`	`{ playbackRate }`	Playback speed changed
`Seeked`	—	Seek completed
`SeekChapter`	`{ position }`	Playback moved to a chapter
`FullscreenChange`	`{ isFullscreen, type, video? }`	Fullscreen mode changed. `type`: `'video' \| 'pseudo' \| 'native'`. `video` is `@deprecated`; use `type`
`PipChange`	`{ isPip }`	Picture-in-Picture mode. Can I use
`CallAction`	`{ id }`	CTA activated. `@experimental`
`CallBookmark`	`{ id, time }`	Bookmark selected. `@experimental`
`AdBreakStateChanged`	`{ active }`	Ad break state changed. `@experimental`
`ControlBarVisibilityChanged`	`{ visible }`	Control bar visibility changed. `@experimental`
`Error`	`{ error }`	Critical error
`Destroy`	—	Player removed from the DOM

Events are available as player.Events.<Name>. For example, use player.Events.Playing.

Next steps

Playlists — dynamic and static playlists
CTA — calls to action displayed over a video
Advertising — VAST/IMA and triggers
player-iframe-api-loader — npm loader and types
Automatic connection — API for an existing iframe
Create a player — factory and CreateOptions