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

Плеер создаётся через фабрику, которую вы получаете в onKinescopeIframeAPIReady или из @kinescope/player-iframe-api-loader . Ниже — свойства и методы этой фабрики.

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

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

Свойства

• Events: IframePlayerFactory.Events

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

Методы

• create(elementId: string, options: CreateOptions): Promise<IframePlayerApi>

  Создать плеер. Если элемент с id elementId не является <iframe>, он будет заменён на <iframe>. Если передан уже существующий <iframe>, плеер встроится в него. Вторым аргументом передаётся объект с параметрами плеера . Возвращается Promise с объектом управления плеером .

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

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

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

  Параметры плеера {#create-options}

  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 .

• on(type: IframePlayerFactory.Events, listener: Function): this

  Подписаться на событие фабрики. См. события фабрики .

• once(type: IframePlayerFactory.Events, listener: Function): this

  Подписаться на событие фабрики. Обработчик будет вызван только один раз.

• off(type: IframePlayerFactory.Events, listener: Function): this

  Отписаться от события фабрики.

События фабрики

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

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

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

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

• IframePlayerFactory.Events.Created — плеер создан. В данных события передаётся объект управления плеером .

  IframePlayerApi;
  

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

Что дальше?

• Управление плеером — методы и события экземпляра
• player-iframe-api-loader — npm-загрузчик и TypeScript-типы
• Автоподключение — API для уже вставленного iframe