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

Для управления плеером используется объект со следующими свойствами и методами:

Свойства

Events: IframePlayerApi.Events

Перечисление событий плеера.

Методы

on(type: IframePlayerApi.Events, listener: Function): this

Подписаться на событие плеера. См. события плеера.
once(type: IframePlayerApi.Events, listener: Function): this

Подписаться на событие плеера. Обработчик события будет вызван только один раз.
off(type: IframePlayerApi.Events, listener: Function): this

Отписаться от события плеера.
isPaused(): Promise<boolean>

Проигрывание приостановлено?
isEnded(): Promise<boolean>

Проигрывание дошло до конца?
isMuted(): Promise<boolean>

Выключен ли звук?
getCurrentTime(): Promise<number>

Текущее время воспроизведения (в секундах).
getDuration(): Promise<number>

Продолжительность ролика (в секундах).
play(): Promise<void>

Начать проигрывание.
pause(): Promise<void>

Приостановить проигрывание.
stop(): Promise<void>

Остановить проигрывание и установить текущее время на начало.
seekTo(time: number): Promise<void>

Поиск и перемотка на указанное время (в секундах).
mute(): Promise<void>

Выключить звук.
unmute(): Promise<void>

Включить звук.
getVolume(): Promise<number>

Уровень громкости (0..1, где 0 это 0%, а 1 это 100%).
setVolume(value: number): Promise<void>

Установить уровень громкости (0..1, где 0 это 0%, а 1 это 100%).
getPlaybackRate(): Promise<number>

Скорость воспроизведения (1 - нормальная скорость воспроизведения).
setPlaybackRate(value: number): Promise<void>

Установить скорость воспроизведения (1 - нормальная скорость воспроизведения).
getVideoQualityList(): Promise<VideoQuality[]>

Список доступных качеств.
getVideoQuality(): Promise<VideoQuality>

Текущее качество видео.
setVideoQuality(quality: VideoQuality): Promise<void>

Установить качество видео.
enableTextTrack(lang: string): Promise<void>

Включить субтитры на указанном языке.
disableTextTrack(): Promise<void>

Выключить субтитры.
isFullscreen(): Promise<boolean>

Активен ли полноэкранный режим просмотра.
setFullscreen(fullscreen: boolean): Promise<void>

Установить значение для полноэкранного режима.
isPip(): Promise<boolean>

Активен ли режим просмотра картинка в картинке.
setPip(pip: boolean): Promise<void>

Установить значение для режима картинка в картинке.

setPlaylistItemOptions(options: PlaylistItemOptions): Promise<void>

Установить параметры для текущего ролика.


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 Настройки для 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). */
  cta?: {
    id: string;
    title?: string;
    description?: string;
    /** Возможность закрыть/пропустить. */
    skippable?: boolean;
    button: {
      text: string;
      style?: CSSProperties;
    };
    /** Срабатывание CTA */
    trigger: {
      /** Процент текущего времени, например: `[0, 100]`. */
      percentages?: number[];
      /** Точки времени (сек.), например: `[60, 600]`. */
      timePoints?: number[];
      /** На паузе */
      pause?: boolean;
    };
  }[];
 
  /** DRM. */
  drm?: {
    auth?: {
      /** Пользовательский токен для авторизации при запросе лицензии. */
      token?: string;
    };
  };
 
  /** Реклама. */
  ad?:
    | AdItemOptions
    | (AdItemOptions & {
        /** Срабатывание рекламы. */
        trigger: {
          /** Процент текущего времени, например: `[0, 100]`. */
          percentages?: number[];
          /** Точки времени (сек.), например: `[60, 600]`. */
          timePoints?: number[];
          /** Повтор (сек), например: `600`, каждые 10 мин. */
          interval?: number;
        };
      })[];
}

getPlaylistItem(): Promise<{ id: string | undefined } | undefined>

Текущий ролик в плейлисте.
switchTo(id: string, options?: SwitchToOptions): Promise<void>

Переключить на указанный ролик в плейлисте.
```
interface SwitchToOptions {
  autoPlay?: boolean;
  time?: number;
}
```
next(): Promise<void>

Переключить на следующий ролик в плейлисте.
previous(): Promise<void>

Переключить на предудыщий ролик в плейлисте.
closeCTA(): Promise<void>

Close a CTA. @experimental

setOptions(options: UpdatablePlayerOptions): Promise<void>

Установить параметры для плеера.


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' } } });

destroy(): Promise<void>

Удалить плеер (<iframe>) из DOM.

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

В каждый обработчик события передается объект события с данными о нем.

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


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

Перечисление событий

IframePlayerApi.Events.Ready - Плеер загрузил все необходимые данные и готов к воспроизведению. При выключенной предзагрузке (preload=‘none’) это событие сработает при начале воспроизведения.
```
{
  currentTime: number;
  duration: number;
  quality: VideoQuality;
  audioTrack: string;
}
```
IframePlayerApi.Events.CurrentTrackChanged - Смена текущего трека.
```
{
  item: { id?: string }
}
```
IframePlayerApi.Events.SizeChanged - Размер плеера изменился.
```
{
  width: number;
  height: number;
}
```
IframePlayerApi.Events.QualityChanged - Изменилось качество видео.
```
{
  quality: VideoQuality;
}
```
IframePlayerApi.Events.Play - Запуск воспроизведения.

У события нет данных.
IframePlayerApi.Events.Playing - Воспроизведение началось.

У события нет данных.
IframePlayerApi.Events.Pause - Пауза.

У события нет данных.
IframePlayerApi.Events.Ended - Окончание воспроизведения.

У события нет данных.
IframePlayerApi.Events.TimeUpdate - Изменение текущего времени воспроизведения.
```
{
  currentTime: number;
  percent: number;
}
```
IframePlayerApi.Events.Waiting - Буферизация.

У события нет данных.
IframePlayerApi.Events.Progress - Загружается медия ресурс.
```
{
  bufferedTime: number;
}
```
IframePlayerApi.Events.DurationChange - Изменение длительности ролика.
```
{
  duration: number;
}
```
IframePlayerApi.Events.VolumeChange - Изменен уровень звука.
```
{
  volume: number;
  muted: boolean;
}
```
IframePlayerApi.Events.PlaybackRateChange - Изменение скорости воспроизведения.
```
{
  playbackRate: number;
}
```
IframePlayerApi.Events.Seeked - Поиск завершен.

У события нет данных.
IframePlayerApi.Events.SeekChapter - Поиск главы, текущее время установлено на позицию главы.
```
{
  position: number;
}
```

IframePlayerApi.Events.FullscreenChange - Изменение полноэкранного режима.


{
  isFullscreen: boolean;
  type: 'video' | 'pseudo' | 'native';
  /** @deprecated Use `type`. */
  video: boolean;
}

IframePlayerApi.Events.PipChange - Изменение режима картинка в картинке. Совместимость с браузерами: https://caniuse.com/picture-in-picture .
```
{
  isPip: boolean;
}
```
IframePlayerApi.Events.CallAction - Вызов действия (CTA). @experimental
```
{
  id: string;
}
```
IframePlayerApi.Events.CallBookmark - Нажатие на закладку. @experimental
```
{
  id: string;
  time: number;
}
```
IframePlayerApi.Events.AdBreakStateChanged - Изменилось состояние рекламной паузы. @experimental
```
{
  active: boolean;
}
```
IframePlayerApi.Events.ControlBarVisibilityChanged - Изменилась видимость панели управления. @experimental
```
{
  visible: boolean;
}
```
IframePlayerApi.Events.Error - Критическая ошибка.
```
{
  error: unknown;
}
```
IframePlayerApi.Events.Destroy - Плеер удален из DOM.

У события нет данных.