Управление плеером

Обновлено: 12.08.2026

Объект управления плеером вы получаете из create() . Через него запускаете воспроизведение, меняете настройки и подписываетесь на события.

Быстрый пример

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

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

Свойства

Свойство	Тип	Описание
`Events`	`IframePlayerApi.Events`	Перечисление событий плеера

Методы

Подписка на события

Метод	Возвращает	Описание
`on(type, listener)`	`this`	Подписаться на событие
`once(type, listener)`	`this`	Подписаться на событие один раз
`off(type, listener)`	`this`	Отписаться от события

Воспроизведение

Метод	Возвращает	Описание
`play()`	`Promise<void>`	Начать проигрывание
`pause()`	`Promise<void>`	Приостановить проигрывание
`stop()`	`Promise<void>`	Остановить и перемотать в начало
`seekTo(time)`	`Promise<void>`	Перемотать на время в секундах
`isPaused()`	`Promise<boolean>`	На паузе ли воспроизведение
`isEnded()`	`Promise<boolean>`	Дошло ли воспроизведение до конца
`getCurrentTime()`	`Promise<number>`	Текущее время (сек.)
`getDuration()`	`Promise<number>`	Длительность ролика (сек.)
`getPlaybackRate()`	`Promise<number>`	Скорость воспроизведения (`1` — нормальная)
`setPlaybackRate(value)`	`Promise<void>`	Установить скорость воспроизведения

Звук

Метод	Возвращает	Описание
`mute()`	`Promise<void>`	Выключить звук
`unmute()`	`Promise<void>`	Включить звук
`isMuted()`	`Promise<boolean>`	Выключен ли звук
`getVolume()`	`Promise<number>`	Громкость от `0` до `1`
`setVolume(value)`	`Promise<void>`	Установить громкость (`0`…`1`)

Качество и субтитры

Метод	Возвращает	Описание
`getVideoQualityList()`	`Promise<VideoQuality[]>`	Список доступных качеств
`getVideoQuality()`	`Promise<VideoQuality>`	Текущее качество
`setVideoQuality(quality)`	`Promise<void>`	Установить качество
`enableTextTrack(lang)`	`Promise<void>`	Включить субтитры на языке `lang`
`disableTextTrack()`	`Promise<void>`	Выключить субтитры

Полноэкранный режим и PiP

Метод	Возвращает	Описание
`isFullscreen()`	`Promise<boolean>`	Активен ли полноэкранный режим
`setFullscreen(fullscreen)`	`Promise<void>`	Включить или выключить fullscreen
`isPip()`	`Promise<boolean>`	Активен ли режим «картинка в картинке»
`setPip(pip)`	`Promise<void>`	Включить или выключить PiP

Плейлист и CTA

Метод	Возвращает	Описание
`getPlaylistItem()`	`Promise<{ id?: string } \| undefined>`	Текущий ролик в плейлисте
`switchTo(id, options?)`	`Promise<void>`	Переключить на ролик по `id` (опции )
`next()`	`Promise<void>`	Следующий ролик в плейлисте
`previous()`	`Promise<void>`	Предыдущий ролик в плейлисте
`closeCTA()`	`Promise<void>`	Закрыть экран CTA. `@experimental`
`setPlaylistItemOptions(options)`	`Promise<void>`	Параметры текущего ролика (PlaylistItemOptions )

switchTo — опции

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

setPlaylistItemOptions — параметры

Устанавливает параметры текущего ролика: заголовок, субтитры, главы, CTA, DRM, реклама.

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

type AdItemOptions =
  | {
      /** Url рекламного тега. */
      adTagUrl: string | string[];
    }
  | {
      /** @experimental Готовый текст рекламного тега. */
      adTag: string | string[];
    }
  | {
      /** @experimental Объект запроса Google IMA (`adsRequest`). */
      adsRequest: Record<string, unknown>;
    }
  | {
      /** @experimental Настройки для Yandex Video Ads SDK. */
      yaOptions: AdItemYaOptions | AdItemYaOptions[];
    };

interface PlaylistItemOptions {
  /** Заголовок видео-ролика. Отображается в верхней части плеера. */
  title?: string;

  /** Подзаголовок видео-ролика. Отображается под основным заголовком. */
  subtitle?: string;

  /** Картинка с постером для видео-ролика. */
  poster?: string;

  /** Субтитры (Video text tracks). */
  vtt?: {
    /** Заголовок */
    label: string;
    /** Url файла субтитров */
    src: string;
    /** Язык субтитров */
    srcLang: string;
  }[];

  /** Главы - разделение отрезков времени. */
  chapters?: {
    /** Точка времени (в секундах) */
    position: number;
    /** Заголовок */
    title: string;
  }[];

  /** Дополнительные материалы для скачивания. */
  files?: {
    list: {
      name: string;
      url: string;
      mime: string;
      size?: number;
    }[];
    archiveUrl?: string;
  };

  /** @experimental Закладки, привязанные ко времени. */
  bookmarks?: {
    id: string;
    /** Время в секундах. */
    time: number;
  }[];

  /**
   * @experimental Призывы к действию (CTA).
   * `type`: overlay | popup | panel | banner | buttons | leadgen (по умолчанию overlay).
   * Полные поля по типам — в разделе CTA: /dokumentaciya-pleera/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;
    };
    // + поля конкретного type (link, position, list, fields, url, …)
  }[];

  /** DRM. */
  drm?: {
    auth?: {
      /** Пользовательский токен для авторизации при запросе лицензии. */
      token?: string;
    };
  };

  /** Реклама. См. [Реклама](/dokumentaciya-pleera/reklama/). */
  ad?:
    | AdItemOptions
    | (AdItemOptions & {
        /** Срабатывание рекламы. */
        trigger: {
          /** Процент текущего времени, например: `[0, 100]`. */
          percentages?: number[];
          /** Точки времени (сек.), например: `[60, 600]`. */
          timePoints?: number[];
          /** Повтор (сек), например: `600`, каждые 10 мин. */
          interval?: number;
        };
      })[];
}

Настройки и уничтожение

Метод	Возвращает	Описание
`setOptions(options)`	`Promise<void>`	Обновить параметры плеера (UpdatablePlayerOptions )
`destroy()`	`Promise<void>`	Удалить плеер (`<iframe>`) из DOM

setOptions — параметры

interface UpdatablePlayerOptions {
  /** Настройки UI */
  ui?: {
    /** Водяной знак. */
    watermark?: {
      /** Текст */
      text: string;
      /**
       * - `stripes` - линиями;
       * - `random` - в случайных местах;
       * По умолчанию `random`.
       */
      mode?: 'stripes' | 'random';
      /** Коэффициент масштабирования размера текста в зависимости от размера плеера. По умолчанию `0.25`. */
      scale?: number;
      /** Длительность показа/скрытия (мс). Если не указано, текст показывается постоянно. */
      displayTimeout?: number | { visible: number; hidden: number };
    };
  };
}

Пример:

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

События плеера

В каждый обработчик передаётся объект события . Поле data зависит от типа события и может отсутствовать.

Жизненный цикл воспроизведения

Основные события возникают в следующем порядке:

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

Событие	Когда срабатывает
`Loaded`	Плеер готов к воспроизведению. При `preload: false` — в начале воспроизведения
`Play`	Запрос на воспроизведение (кнопка Play или `play()`)
`Playing`	Воспроизведение фактически началось
`TimeUpdate`	Периодически во время воспроизведения
`Waiting`	Буферизация
`Pause` / `Ended`	Пауза или конец ролика
`Destroy`	Плеер удалён из DOM

При переключении ролика в плейлисте срабатывает CurrentTrackChanged, затем Loaded для нового ролика.

Объект события

{
  /** Тип события */
  type: IframePlayerApi.Events;
  /** Данные события, зависят от типа события, могут отсутствовать */
  data: Data;
  /** Объект управления плеером, соответствующий событию */
  target: IframePlayerApi;
}

Перечисление событий {#event-data}

Событие	Данные	Описание
`Loaded`	`{ currentTime, duration, quality, audioTrack }`	Данные ролика загружены, плеер готов. При `preload: 'none'` — в начале воспроизведения
`CurrentTrackChanged`	`{ item: { id?: string } }`	Смена текущего трека
`SizeChanged`	`{ width, height }`	Изменился размер плеера
`QualityChanged`	`{ quality }`	Изменилось качество видео
`Play`	—	Запрос на запуск воспроизведения
`Playing`	—	Воспроизведение фактически началось
`Pause`	—	Пауза
`Ended`	—	Окончание воспроизведения
`TimeUpdate`	`{ currentTime, percent }`	Изменение текущего времени
`Waiting`	—	Буферизация
`Progress`	`{ bufferedTime }`	Загружается медиаресурс
`DurationChange`	`{ duration }`	Изменение длительности ролика
`VolumeChange`	`{ volume, muted }`	Изменён уровень звука
`PlaybackRateChange`	`{ playbackRate }`	Изменение скорости
`Seeked`	—	Перемотка завершена
`SeekChapter`	`{ position }`	Переход к главе
`FullscreenChange`	`{ isFullscreen, type, video? }`	Изменение fullscreen. `type`: `'video' \| 'pseudo' \| 'native'`. `video` — `@deprecated`, используйте `type`
`PipChange`	`{ isPip }`	Режим «картинка в картинке». Can I use
`CallAction`	`{ id }`	Вызов CTA. `@experimental`
`CallBookmark`	`{ id, time }`	Нажатие на закладку. `@experimental`
`AdBreakStateChanged`	`{ active }`	Состояние рекламной паузы. `@experimental`
`ControlBarVisibilityChanged`	`{ visible }`	Видимость панели управления. `@experimental`
`Error`	`{ error }`	Критическая ошибка
`Destroy`	—	Плеер удалён из DOM

События доступны как player.Events.<Name>, например player.Events.Playing.

Что дальше?

Плейлисты — динамические и статические плейлисты
CTA — призывы к действию поверх видео
Реклама — VAST/IMA и триггеры
player-iframe-api-loader — npm-загрузчик и типы
Автоподключение — API для уже вставленного iframe
Создание плеера — фабрика и CreateOptions