# Criação de um player


[player-api]: /player-docs/embedding/iframe-api-control-player/

Você cria um player pela factory recebida em `onKinescopeIframeAPIReady` ou por [@kinescope/player-iframe-api-loader](https://docs-br.kinescope.com/player-docs/libraries/player-iframe-api-loader/). Esta página descreve as propriedades e os métodos da factory.

## Exemplo rápido

```js
playerFactory
  .create('player', {
    url: 'https://kinescope.io/VIDEO_ID',
    size: { width: '100%', height: 400 },
  })
  .then((player) => {
    // player é o objeto de controle. Consulte "Controle do player".
  })
```

## Propriedades

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

  A [enumeração de eventos do player](#event-data).

## Métodos

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

  Cria um player. Se o elemento com o ID `elementId` não for um `<iframe>`, a API o substituirá por um `<iframe>`. Se você passar um `<iframe>` existente, o player será incorporado a ele. O segundo argumento contém as [opções do player](#create-options). O método retorna uma `Promise` com o [objeto de controle do player][player-api].

  Se já existir um player com esse ID, o método retornará a instância existente.

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

Após criar o player, não remova o elemento com o ID `elementId` nem altere manualmente a URL do `<iframe>`. Use [`destroy`][player-api] para removê-lo.

  Para recriar o player, espere a conclusão de [`destroy`][player-api]. O elemento com o ID `elementId` será removido do DOM. Crie outro elemento com o mesmo ID e chame `create`.



  <a name="CreateOptions"></a>
  **Opções do player** {#create-options}

  ```ts
  interface CreateOptions {
    /** URL do vídeo */
    url: string;

    /** Configurações de tamanho */
    size?: {
      /** Largura do player. */
      width?: number | string;
      /** Altura do player. */
      height?: number | string;
    };

    /** Configurações de comportamento */
    behavior?: {
      /**
       * - `none`, `false` - não pré-carrega o vídeo. Carrega apenas a capa para economizar recursos da página. Padrão em dispositivos móveis.
       * - `metadata`, `true` - pré-carrega os dados necessários do vídeo. Padrão, exceto em dispositivos móveis.
       * - `auto` - permite que o navegador e o driver de vídeo escolham o comportamento de pré-carregamento.
       */
      preload?: boolean | 'none' | 'metadata' | 'auto';
      /** Memoriza o tempo de reprodução, as configurações de legendas e outras preferências. Padrão: `true`. */
      localStorage?:
        | boolean
        | {
            /**
             * - `item` - memoriza as configurações separadamente para cada vídeo.
             * - true | `global` - memoriza as configurações globalmente para todos os vídeos.
             * - false - não memoriza as configurações.
             * Padrão: `global`.
             */
            quality?: 'item' | 'global' | boolean;
            /** Memoriza o tempo de reprodução. */
            time?: boolean;
            /** Memoriza o idioma das legendas. Funciona como `quality`. */
            textTrack?: 'item' | 'global' | boolean;
          };
      /** Controla o player pelo teclado. Padrão: `true`. */
      keyboard?: boolean;
      /**
       * Especifica uma alternativa quando o navegador não aceita o modo de tela cheia para elementos.
       * - `video` - usa o modo de tela cheia para o elemento de vídeo. Usado no iOS.
       * - `pseudo` - estende o player sobre todos os outros elementos na janela do navegador.
       * Padrão: `video`.
       */
      fullscreenFallback?: 'video' | 'pseudo';
      /** Reproduz o vídeo em dispositivos móveis sem entrar automaticamente em tela cheia. Padrão: `true`. */
      playsInline?: boolean;
      /** Repete o vídeo. */
      loop?: boolean;
      /**
       * Inicia o player automaticamente.
       * Se a reprodução com som falhar, o player tentará iniciar sem som.
       *
       * `viewable` - inicia automaticamente quando o player entra na área visível.
       * Use quando o player estiver mais abaixo na página e exigir rolagem.
       */
      autoPlay?: boolean | 'viewable';
      /** Pausa se for `true` ou reinicia se for `reset` quando outro player da página inicia a reprodução. Padrão: `true`. */
      autoPause?: boolean | 'reset';
      /**
       * @experimental
       *
       * `visible` - pausa a reprodução quando o player está fora da área visível. */
      playback?: 'visible';
      /** Desativa o som do player. */
      muted?: boolean;
      /** Velocidade de reprodução. `1` é a velocidade normal. */
      playbackRate?: number;
      /**
       * Ativa as legendas quando o vídeo é carregado.
       * - `true` - seleciona o idioma do navegador, depois o idioma do player e, por fim, a primeira faixa.
       * - `string` - ativa a faixa no idioma especificado. */
      textTrack?: boolean | string;
      /** Configurações da playlist. */
      playlist?: {
        /** Troca automaticamente os vídeos da playlist. Padrão: `true`. */
        autoSwitch?: boolean;
        /** Repete toda a playlist. Padrão: `false`. */
        loop?: boolean;
      };
    };

    /** Configurações da interface */
    ui?: {
      /** Idioma do player. O padrão é o idioma do navegador ou inglês. */
      language?: 'ru' | 'en';
      /** Exibe os controles do player. Padrão: `true`. */
      controls?: boolean;
      /** Exibe o botão grande de reprodução no centro. Padrão: `true`. */
      mainPlayButton?: boolean;
      /** Exibe o botão de velocidade de reprodução. */
      playbackRateButton?: boolean;
      /** Marca d'água. */
      watermark?: {
        /** Texto */
        text: string;
        /**
         * - `stripes` - exibe em linhas;
         * - `random` - exibe em posições aleatórias;
         * Padrão: `random`.
         */
        mode?: 'stripes' | 'random';
        /** Fator de escala do texto baseado no tamanho do player. Padrão: `0.25`. */
        scale?: number;
        /** Duração da exibição e ocultação em milissegundos. Se omitido, o texto permanece visível. */
        displayTimeout?: number | {visible: number; hidden: number};
      };
    };

    /** Configurações do tema. */
    theme?: {
      subtitles?: {
        /** Tamanho-base da fonte em em. */
        textScale?: number;
        textAlign?: 'left' | 'center';
        textLength?: 'auto' | number;
      };
      watermark: {
        default: {
          /** Cor da marca d'água no formato de cor CSS. */
          color: string;
        };
      };
      colors: {
        /** Cor do player no formato de cor CSS. Por exemplo: #4caf50. */
        primary: string;
      };
    };

    /** Configurações do player. */
    settings?: {
      /** Identificador personalizado enviado com as métricas. */
      externalId?: string;
    };

    /**
     * Configurações específicas do vídeo: títulos, legendas, DRM e outras opções.
     * A interface `PlaylistItemOptions` é descrita no método `setPlaylistItemOptions` do player.
     */
    playlist: PlaylistItemOptions[];
  }
  ```

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

A interface `PlaylistItemOptions` para títulos, legendas, capítulos, CTA, DRM e publicidade é descrita em [Controle do player — setPlaylistItemOptions](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/#setPlaylistItemOptions).



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

  Assina um [evento](#event-data) da factory. Consulte [Eventos da factory](#player-factory-events).

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

  Assina um [evento](#event-data) da factory. O [handler](#player-factory-events) é executado apenas uma vez.

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

  Cancela a assinatura de um [evento](#event-data) da factory.

## Eventos da factory {#player-factory-events}

Cada handler recebe um [objeto de evento](#event-object) com seus [dados](#event-data).

### Objeto de evento {#event-object}

```ts
{
  /** Tipo de evento */
  type: IframePlayerFactory.Events;
  /** Dados do evento. A estrutura depende do tipo de evento e pode estar ausente. */
  data: Data;
  /** Factory. */
  target: IframePlayerFactory;
}
```

### Enumeração de eventos {#event-data}

- **`IframePlayerFactory.Events.Created`** <a name="Events.Created"></a> — o player foi criado. Os dados do evento contêm o [objeto de controle do player][player-api].

  ```ts
  IframePlayerApi;
  ```

## Recomendações

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

Não armazene o objeto do player em uma variável global. Qualquer pessoa pode acessá-lo pelo console do navegador.



## Próximos passos

- [Controle do player](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/) — métodos e eventos da instância
- [player-iframe-api-loader](https://docs-br.kinescope.com/player-docs/libraries/player-iframe-api-loader/) — loader npm e tipos TypeScript
- [Conexão automática](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-auto-connect/) — API para um iframe existente