# Создание плеера


[player-api]: /dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/

Плеер создаётся через фабрику, которую вы получаете в `onKinescopeIframeAPIReady` или из [@kinescope/player-iframe-api-loader](https://docs.kinescope.ru/dokumentaciya-pleera/biblioteki/player-iframe-api-loader/). Ниже — свойства и методы этой фабрики.

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

```js
playerFactory
  .create('player', {
    url: 'https://kinescope.io/VIDEO_ID',
    size: { width: '100%', height: 400 },
  })
  .then((player) => {
    // player — объект управления, см. «Управление плеером»
  })
```

## Свойства

- **`Events: IframePlayerFactory.Events`** <a name="events"></a>

  [Перечисление событий плеера](#event-data).

## Методы

- **`create(elementId: string, options: CreateOptions): Promise<IframePlayerApi>`** <a name="create"></a>

  Создать плеер. Если элемент с id `elementId` не является `<iframe>`, он будет заменён на `<iframe>`. Если передан уже существующий `<iframe>`, плеер встроится в него. Вторым аргументом передаётся объект с [параметрами плеера](#create-options). Возвращается `Promise` с [объектом управления плеером][player-api].

  Если плеер с указанным id уже существует, вернётся существующий экземпляр.

  > **Внимание:**

После создания плеера не удаляйте элемент с id `elementId` и не меняйте URL `<iframe>` вручную. Для удаления используйте метод [`destroy`][player-api].

  При пересоздании дождитесь завершения [`destroy`][player-api] (элемент с id `elementId` будет удалён из DOM), снова создайте элемент с тем же id и только потом вызовите `create`.



  <a name="CreateOptions"></a>
  **Параметры плеера** {#create-options}

  ```ts
  interface CreateOptions {
    /** Url видео */
    url: string;

    /** Настройки размера */
    size?: {
      /** Ширина плеера. */
      width?: number | string;
      /** Высота плеера. */
      height?: number | string;
    };

    /** Настройки поведения */
    behavior?: {
      /**
       * - `none`, `false` - не осуществлять предзагрузку видео (только постер, экономия ресурсов страницы). По умолчанию для мобильных устройств.
       * - `metadata`, `true` - предварительно загружаются необходимые данные видео. По умолчанию (кроме мобильных устройств).
       * - `auto` - предзагрузка на усмотрение браузера и видео драйвера.
       */
      preload?: boolean | 'none' | 'metadata' | 'auto';
      /** Запоминать время воспроизведения, настройки субтитров и т.д. По умолчанию `true`. */
      localStorage?:
        | boolean
        | {
            /**
             * - `item` - запоминать для каждого ролика отдельно.
             * - true | `global` - запоминать глобально, на все ролики.
             * - false - не запоминать.
             * По умолчанию `global`.
             */
            quality?: 'item' | 'global' | boolean;
            /** Запоминать время. */
            time?: boolean;
            /** Запоминать язык субтитров. Аналогично `quality`. */
            textTrack?: 'item' | 'global' | boolean;
          };
      /** Управление плеером с клавиатуры. По умолчанию `true`. */
      keyboard?: boolean;
      /**
       * В случае, если браузер не поддерживает полноэкранный режим для элементов можно указать запасной вариант.
       * - `video` - полноэкранный режим видео элемента. Применяется в iOS.
       * - `pseudo` - растянуть плеер в окне браузера поверх всех других элементов (псевдофулскрин).
       * По умолчанию `video`.
       */
      fullscreenFallback?: 'video' | 'pseudo';
      /** Воспроизводить видео на мобильных устройствах не переходя автоматически в полноэкранный режим. По умолчанию `true`. */
      playsInline?: boolean;
      /** Зацикленное видео. */
      loop?: boolean;
      /**
       * Автоматический запуск плеера.
       * Если не удалось начать воспроизведение со звуком, то плеер попытается начать воспроизведение с выключенным звуком.
       *
       * `viewable` - автоматический запуск при появлении плеера в области видимости на странице.
       * Применимо когда плеер находится внизу страницы и до его появления нужно прокрутить страницу.
       */
      autoPlay?: boolean | 'viewable';
      /** Ставить на паузу (если `true`) или сбрасывать на начальное состояние (если `reset`), если другой плеер на странице начал проигрывание. По умолчанию `true`. */
      autoPause?: boolean | 'reset';
      /**
       * @experimental
       *
       * `visible` - воспроизведение приостанавливается, если плеер вне области видимости на странице. */
      playback?: 'visible';
      /** Выключить звук. */
      muted?: boolean;
      /** Скорость воспроизведения (1 - нормальная скорость воспроизведения). */
      playbackRate?: number;
      /**
       * Включать ли субтитры при загрузке видео.
       * - `true` - автовыбор в следующем порядке: на языке браузера, на языке плеера, первый в списке.
       * - `string` - включать дорожку с указанным языком. */
      textTrack?: boolean | string;
      /** Настройки для плейлиста. */
      playlist?: {
        /** Автопереключение роликов в плейлисте. По умолчанию `true`. */
        autoSwitch?: boolean;
        /** Повторять весь плейлист. По умолчанию `false`. */
        loop?: boolean;
      };
    };

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

    /** Настройки темы. */
    theme?: {
      subtitles?: {
        /** Базовый размер шрифта в em. */
        textScale?: number;
        textAlign?: 'left' | 'center';
        textLength?: 'auto' | number;
      };
      watermark: {
        default: {
          /** Цвет водзнака (CSS color). */
          color: string;
        };
      };
      colors: {
        /** Цвет плеера (CSS color). Например: #4caf50. */
        primary: string;
      };
    };

    /** Настройки для плеера. */
    settings?: {
      /** Какой-либо пользовательский идентификатор. Используется для отправки метрик. */
      externalId?: string;
    };

    /**
     * Настройки, относящиеся к ролику: заголовки, субтитры, DRM и т.д.
     * Интерфейс `PlaylistItemOptions` описан в методе плеера `setPlaylistItemOptions`.
     */
    playlist: PlaylistItemOptions[];
  }
  ```

  > **Информация:**

Интерфейс `PlaylistItemOptions` (заголовки, субтитры, главы, CTA, DRM, реклама) описан в разделе [Управление плеером — setPlaylistItemOptions](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/#setPlaylistItemOptions).



- **`on(type: IframePlayerFactory.Events, listener: Function): this`** <a name="on"></a>

  Подписаться на [событие](#event-data) фабрики. См. [события фабрики](#player-factory-events).

- **`once(type: IframePlayerFactory.Events, listener: Function): this`** <a name="once"></a>

  Подписаться на [событие](#event-data) фабрики. [Обработчик](#player-factory-events) будет вызван только один раз.

- **`off(type: IframePlayerFactory.Events, listener: Function): this`** <a name="off"></a>

  Отписаться от [события](#event-data) фабрики.

## События фабрики {#player-factory-events}

В каждый обработчик передаётся [объект события](#event-object) с [данными](#event-data) о нём.

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

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

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

- **`IframePlayerFactory.Events.Created`** <a name="Events.Created"></a> — плеер создан. В данных события передаётся [объект управления плеером][player-api].

  ```ts
  IframePlayerApi;
  ```

## Рекомендации

> **Внимание:**

Не храните объект плеера в глобальной переменной — к нему можно получить доступ из консоли браузера.



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

- [Управление плеером](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/) — методы и события экземпляра
- [player-iframe-api-loader](https://docs.kinescope.ru/dokumentaciya-pleera/biblioteki/player-iframe-api-loader/) — npm-загрузчик и TypeScript-типы
- [Автоподключение](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-avtopodklyuchenie/) — API для уже вставленного iframe