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


Объект управления плеером вы получаете из [`create()`](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-sozdanie-pleera/#create). Через него запускаете воспроизведение, меняете настройки и подписываетесь на события.

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

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

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

## Свойства {#events}

| Свойство | Тип | Описание |
| :--- | :--- | :--- |
| `Events` | `IframePlayerApi.Events` | Перечисление [событий плеера](#event-data) |

## Методы

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

| Метод | Возвращает | Описание |
| :--- | :--- | :--- |
| <a id="on"></a>`on(type, listener)` | `this` | Подписаться на [событие](#event-data) |
| <a id="once"></a>`once(type, listener)` | `this` | Подписаться на событие один раз |
| <a id="off"></a>`off(type, listener)` | `this` | Отписаться от события |

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

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

### Звук

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

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

| Метод | Возвращает | Описание |
| :--- | :--- | :--- |
| <a id="getVideoQualityList"></a>`getVideoQualityList()` | `Promise<VideoQuality[]>` | Список доступных [качеств](https://docs.kinescope.ru/dokumentaciya-pleera/optimizaciya/#video-quality) |
| <a id="getVideoQuality"></a>`getVideoQuality()` | `Promise<VideoQuality>` | Текущее [качество](https://docs.kinescope.ru/dokumentaciya-pleera/optimizaciya/#video-quality) |
| <a id="setVideoQuality"></a>`setVideoQuality(quality)` | `Promise<void>` | Установить [качество](https://docs.kinescope.ru/dokumentaciya-pleera/optimizaciya/#video-quality) |
| <a id="enableTextTrack"></a>`enableTextTrack(lang)` | `Promise<void>` | Включить субтитры на языке `lang` |
| <a id="disableTextTrack"></a>`disableTextTrack()` | `Promise<void>` | Выключить субтитры |

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

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

### Плейлист и CTA

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

#### switchTo — опции {#switchTo-options}

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

#### setPlaylistItemOptions — параметры {#setPlaylistItemOptions-options}

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

```ts
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;
    };
  };

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

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

| Метод | Возвращает | Описание |
| :--- | :--- | :--- |
| <a id="setOptions"></a>`setOptions(options)` | `Promise<void>` | Обновить параметры плеера ([UpdatablePlayerOptions](#setOptions-options)) |
| <a id="destroy"></a>`destroy()` | `Promise<void>` | Удалить плеер (`<iframe>`) из DOM |

#### setOptions — параметры {#setOptions-options}

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

Пример:

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

## События плеера {#player-events}

В каждый обработчик передаётся [объект события](#event-object). Поле `data` зависит от типа события и может отсутствовать.

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

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

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

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

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

### Объект события {#event-object}

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

### Перечисление событий {#event-data} <a id="EventListeners"></a>

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

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

## Что дальше?

- [Плейлисты](https://docs.kinescope.ru/dokumentaciya-pleera/pleylisty/) — динамические и статические плейлисты
- [CTA](https://docs.kinescope.ru/dokumentaciya-pleera/cta/) — призывы к действию поверх видео
- [Реклама](https://docs.kinescope.ru/dokumentaciya-pleera/reklama/) — VAST/IMA и триггеры
- [player-iframe-api-loader](https://docs.kinescope.ru/dokumentaciya-pleera/biblioteki/player-iframe-api-loader/) — npm-загрузчик и типы
- [Автоподключение](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-avtopodklyuchenie/) — API для уже вставленного iframe
- [Создание плеера](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-sozdanie-pleera/) — фабрика и `CreateOptions`