Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Referência da API do Aliplayer

Última atualização: Sep 01, 2026

Este tópico descreve as propriedades, métodos e eventos suportados pelo Aliplayer.

Nota

Se você encontrar problemas ao usar o Aliplayer, consulte Web Player FAQ ou Self-troubleshooting for Playback Errors.

Propriedades

Ao inicializar o Aliplayer, é possível definir diversas propriedades. Essas configurações abrangem autorização de licença, informações da fonte de mídia, ajustes da interface do player e comportamento de reprodução.

Nome

Tipo

Descrição

id

String

ID do elemento DOM do contêiner externo do player.

source

String

Para reprodução baseada em URL, especifique o endereço do vídeo nesta propriedade.

Nota
  • A reprodução por URL tem a maior prioridade e sobrescreve outros métodos, como VidAuth e VidSts. Se você definir source, o player usará essa URL mesmo que VidAuth ou VidSts também estejam configurados. Utilize apenas um método de reprodução.

  • Esse modo suporta múltiplas definições. Especifique as URLs para cada definição usando esta propriedade. Para mais informações, consulte Multi-definition Playback. Exemplo:

    source: '{"HD":"address1","SD":"address2"}'

vid

String

ID da mídia para o service ApsaraVideo Media Processing.

playauth

String

Credencial de reprodução. Para obter instruções sobre como adquirir uma credencial de reprodução, consulte Obtain a Playback Credential.

customVodServer

String

Domínio personalizado para proxy VOD (suportado no modo de reprodução VidAuth versão 2.32.0 e posterior). Você deve deploy a dedicated request proxy service. Quando o domínio padrão do VOD (*.aliyuncs.com) estiver inacessível, o player alternará automaticamente para o seu service de proxy. Isso evita sequestro por provedores de internet e melhora a estabilidade e a taxa de sucesso da reprodução.

playConfig

JSON

Configurações personalizadas usadas na reprodução com Vid (VidAuth ou VidSts). Esses valores são repassados diretamente à API do VOD. Para campos suportados e descrições de parâmetros, consulte Custom PlayConfig Settings for Media Playback. Valor de exemplo:

{"PlayDomain":"vod.test_domain","PreviewTime":"20","MtsHlsUriToken":"yqCD7******oVjslp5Q"}

authTimeout

Number

Período de validade da URL de reprodução de vídeo obtida via Vid (VidAuth ou VidSts). Unidade: segundos. Padrão: 7200.

Garanta que este valor exceda a duração real do vídeo para evitar que a URL de reprodução expire antes do término da exibição.

height

String

Altura do player. Valores válidos:

  • 100%

  • 100px

width

String

Largura do player. Valores válidos:

  • 100%

  • 100px

autoSize

Boolean | String

Ajusta automaticamente o tamanho do player para caber no conteúdo do vídeo. Valores válidos: 'height' ou 'width'.

Por exemplo, defina width: '500px' e autoSize: 'height'. O player mantém uma largura fixa de 500px e ajusta sua altura com base na proporção do vídeo.

Ou defina height: '500px' e autoSize: 'width'. O player mantém uma altura fixa de 500px e ajusta sua largura conforme a proporção do vídeo.

Nota: autoSize: true equivale a autoSize: 'height'. O redimensionamento automático de altura é o padrão.

videoWidth

String

Largura do vídeo. Para mais informações, consulte Set Display Mode.

videoHeight

String

Altura do vídeo. Para mais informações, consulte Set Display Mode.

preload

Boolean

O player carrega automaticamente.

cover

String

Imagem de capa padrão do player. Insira uma URL de imagem válida. Esta configuração só entra em vigor quando autoplay está definido como false.

isLive

Boolean

Indica se o conteúdo é uma transmissão ao vivo. Quando ativado, os usuários não podem arrastar a barra de progresso. Padrão: false. Defina como true para streams ao vivo.

autoplay

Boolean

Ativa a reprodução automática no player. A reprodução automática falha em dispositivos móveis. Valores válidos:

  • true (padrão): Ativa a reprodução automática.

  • false: Desativa a reprodução automática.

Nota

Devido a restrições dos navegadores, a reprodução automática pode falhar no Web Player SDK. Para detalhes, consulte Advanced Features.

autoplayPolicy

Object

O player suporta uma política adaptativa para reprodução automática sem som. Esta propriedade só entra em vigor quando autoplay está definido como true. Exemplo de configuração:

autoplayPolicy: {
      fallbackToMute: true, // Fallback to muted autoplay if audible autoplay fails. Default: false.
      showUnmuteBtn: true, // Show a large unmute button when muted autoplay is active. Default: true.
    }
Nota
  • Uma reprodução automática sem som bem-sucedida aciona o evento mutedAutoplay.

  • Quando o player ativa a reprodução automática (parâmetro autoplay definido como true) e a reprodução automática adaptativa sem som (parâmetro autoplayPolicy.fallbackToMute definido como true), ele tenta primeiro a reprodução com som. Se essa tentativa falhar, o sistema recorre à reprodução sem som. Note que o sucesso da reprodução sem som não é garantido.

rePlay

Boolean

Ativa a reprodução em loop automático.

useH5Prism

Boolean

Utiliza o player HTML5.

playsinline

Boolean

Ativa a reprodução inline para HTML5. Alguns navegadores Android não oferecem suporte a este recurso.

skinRes

Url

URL da imagem da skin. Não recomendamos alterar este campo. Para personalizar a skin, consulte Customize the Player Skin.

skinLayout

Array | Boolean

Configure o layout dos componentes da interface. Omita esta propriedade para usar o layout padrão. Defina como false para ocultar todos os componentes da UI. Para mais informações, consulte Configure the skinLayout Property.

skinLayoutIgnore

Array

Lista de componentes da UI a serem ocultados. Consulte VOD Component Parameter Reference para os nomes dos componentes. Exemplo de configuração:

skinLayoutIgnore: [
  'bigPlayButton', // Hide the large play button.
  'controlBar.fullScreenButton' // Hide the full-screen button in the control bar (use dot notation for nested components).
]
Nota

skinLayoutIgnore tem precedência sobre skinLayout.

controlBarVisibility

String

Implementação do painel de controle. Valores válidos:

  • click: Clique em na área do player.

  • hover (padrão): Exibe quando o usuário passa o mouse sobre a área do player.

  • always: Sempre mostra a barra de controle.

  • Never: Oculta todo o painel de controle.

showBarTime

Number

Tempo em milissegundos antes que a barra de controle seja ocultada automaticamente.

enableSystemMenu

Boolean

Ativa o menu de contexto do sistema (clique em direito). Padrão: false.

format

String

Especifique o formato da URL de reprodução. Valores válidos:

  • mp4

  • hls ou m3u8

  • flv

  • mp3

Padrão: vazio.

mediaType

String

Especifique se deve retornar áudio ou vídeo. Suportado apenas ao usar reprodução baseada em vid. Padrão: video. Valores válidos:

  • video: Vídeo.

  • audio: Formatos somente de áudio, como arquivos MP4 contendo apenas áudio.

qualitySort

String

Especifique a ordem de classificação. Suportado apenas ao usar reprodução Vid + PlayAuth. Valores válidos:

  • desc: Classifica em ordem decrescente (do maior para o menor).

  • asc: Classifica em ordem crescente (do menor para o maior).

Padrão: asc.

definition

String

Define quais definições de vídeo exibir. Separe múltiplas definições com vírgulas (,). Exemplo: 'FD,LD'. Trata-se de um subconjunto das definições disponíveis para o vid especificado. Valores válidos:

  • FD (baixa definição)

  • LD (definição padrão)

  • HD (alta definição)

  • HD (ultra-alta definição)

  • OD (qualidade original)

  • 2K (2K)

  • 4K (4K)

defaultDefinition

String

Define a definição de vídeo padrão. Deve ser uma das definições disponíveis para o vid especificado. Valores válidos:

  • FD (baixa definição)

  • LD (definição padrão)

  • SD (Definição Padrão)

  • HD (ultra-alta definição)

  • OD (qualidade original)

  • 2K (2K)

  • 4K (4K)

autoPlayDelay

Number

Atraso antes do início da reprodução. Unidade: segundos.

language

String

Define o idioma para internacionalização. Padrão: zh-cn. Se omitido, o idioma do navegador será usado. Valores válidos:

  • zh-cn: Chinês

  • en-us: Inglês

languageTexts

JSON

Texto de internacionalização personalizado no formato JSON. As chaves devem corresponder ao valor da propriedade language. Exemplo: {jp:{Play:"Play"}}. Para uma lista completa de chaves, consulte Estrutura JSON.

snapshotWatermark

Object

Configure marcas d'água de captura de tela para players HTML5.

useHlsPluginForSafari

Boolean

Ativa o plugin HLS para navegadores Safari, exceto Safari 11. Valores válidos:

  • true: Ativar.

  • false (padrão): Desativar.

enableStashBufferForFlv

Boolean

Ativa o cache de reprodução para FLV em players HTML5. Aplica-se apenas a transmissões ao vivo. Valores válidos:

  • true (padrão): Ativar.

  • false: Desativar.

stashInitialSizeForFlv

Number

Tamanho inicial do cache para FLV em players HTML5. Aplica-se apenas a transmissões ao vivo. Padrão: 32 KB.

Um valor menor melhora a velocidade de inicialização. No entanto, se for muito pequeno, a reprodução pode travar após um curto período.

loadDataTimeout

Number

Tempo em segundos antes de solicitar ao usuário que mude para uma definição inferior devido ao buffer. Padrão: 20.

waitingTimeout

Number

Tempo limite máximo de buffering. Uma mensagem de erro aparecerá se esse tempo for excedido. Unidade: segundos. Padrão: 60.

diagnosisButtonVisible

Boolean

Mostra o botão de diagnóstico. Valores válidos:

  • true (padrão): Mostra o botão.

  • false: Oculta o botão.

disableSeek

Boolean

Desativa a busca pela barra de progresso. Valores válidos:

  • true: Desativar.

  • false (padrão): Não desativa.

encryptType

Number

Ativa a criptografia de vídeo da Alibaba Cloud (criptografia privada). Padrão: 0. Valores válidos:

  • 0: Reproduz vídeos não criptografados.

  • 1: Reproduz vídeos com criptografia privada.

Nota

progressMarkers

Array

Um array de objetos de marcadores de progresso.

vodRetry

Number

Número de tentativas para falhas de reprodução VOD. Padrão: 3.

liveRetry

Number

Número de tentativas para falhas de reprodução ao vivo. Padrão: 5.

hlsFrameChasing

Boolean

Ativa o frame chasing para transmissões ao vivo HLS. Valores válidos:

  • true: Ativar frame chasing.

  • false (padrão): Desativar frame chasing.

Nota

Apenas versões do Web Player SDK anteriores à 2.21.0 suportam a definição deste parâmetro. Para a versão 2.21.0 e posteriores, para ativar a sincronização de quadros no modo de transmissão ao vivo HLS, consulte a propriedade hlsOption.maxLiveSyncPlaybackRate.

chasingFirstParagraph

Number

Duração do primeiro segmento de frame-chasing. Unidade: segundos. Padrão: 20.

Nota

Você só pode definir este parâmetro em versões do Web Player SDK anteriores à 2.21.0. Para a versão 2.21.0 e posteriores, para definir a sincronização de quadros no modo de transmissão ao vivo HLS, consulte a propriedade hlsOption.maxLiveSyncPlaybackRate.

chasingSecondParagraph

Number

Duração do segundo segmento de frame-chasing. Unidade: segundos. Padrão: 40.

Nota

Apenas versões do Web Player SDK anteriores à 2.21.0 suportam a definição deste parâmetro. Para versões 2.21.0 e posteriores, para definir a sincronização de quadros no modo de transmissão ao vivo HLS, consulte a propriedade hlsOption.maxLiveSyncPlaybackRate.

chasingFirstSpeed

Number

Velocidade de reprodução para o primeiro segmento de frame-chasing. Padrão: 1,1×.

Nota

Apenas versões do Web Player SDK anteriores à 2.21.0 suportam a configuração deste parâmetro. Para versões 2.21.0 e posteriores, para configurar a sincronização de quadros no modo de transmissão ao vivo HLS, consulte a propriedade hlsOption.maxLiveSyncPlaybackRate.

chasingSecondSpeed

Number

Velocidade de reprodução para o segundo segmento de frame-chasing. Padrão: 1,2×.

Nota

Apenas versões do Web Player SDK inferiores à 2.21.0 suportam a definição deste parâmetro. Para versões 2.21.0 e posteriores, para configurar a sincronização de quadros no modo de transmissão ao vivo HLS, consulte a propriedade hlsOption.maxLiveSyncPlaybackRate.

hlsOption.maxLiveSyncPlaybackRate

Number

Define a velocidade de reprodução para frame chasing em transmissões ao vivo HLS. Padrão: 1 (sem frame chasing).

  • Exemplo de configuração:

    hlsOption: {
      maxLiveSyncPlaybackRate: 1.5, // Set the frame-chasing playback speed.
      liveSyncDurationCount: 3 // Set the number of segments that trigger frame chasing.
    }
  • Significado do exemplo: Quando a latência da transmissão ao vivo excede a duração de 3 segmentos, o player reproduz a uma velocidade de 1,5× para alcançar o atraso de 3 segmentos (como o player precisa de um buffer para lidar com flutuações de rede, modifique o valor de liveSyncDurationCount com cautela — definir esse valor muito baixo pode causar travamentos).

Nota

Este parâmetro é suportado apenas nas versões 2.21.0 e posteriores do Web Player SDK.

flvFrameChasing

Boolean

Ativa o frame chasing para transmissões ao vivo FLV. Valores válidos:

  • true: Ativar frame chasing.

  • false: Desativar frame chasing.

Padrão: false.

keyShortCuts

Boolean

Ativa atalhos de teclado. Valores válidos:

  • true: Ativar atalhos de teclado.

  • false: Desativar atalhos de teclado.

Padrão: false.

Nota

As teclas de seta (esquerda/direita) controlam avanço e retrocesso rápido. As teclas de seta (cima/baixo) controlam o volume. A barra de espaço alterna entre reproduzir/pausar.

keyFastForwardStep

Number

Intervalo de tempo para avanço e retrocesso rápido. Unidade: segundos. Padrão: 10.

rtsFallback

Boolean

Quando o navegador não suporta RTS ou o pull de stream RTS falha, o player recorre automaticamente a FLV ou HLS. Ele prefere FLV para menor latência. Se o navegador não suportar FLV, ele recorre a HLS.

Este recurso está ativado por padrão. Para desativá-lo, defina este parâmetro como false.

rtsFallbackType

String

Especifique o protocolo para fallback a partir do RTS. Valores válidos: HLS ou FLV. Por padrão, o player seleciona automaticamente, preferindo FLV para menor latência. Se o navegador não suportar FLV, ele recorre a HLS.

rtsFallbackSource

String

Recomendamos usar a estratégia de fallback padrão do player. No entanto, se quiser especificar uma URL de stream fixa para fallback, utilize este parâmetro.

traceId

String

Seu identificador de usuário exclusivo. Passe este valor para pontos de instrumentação públicos para rastrear o relatório de logs. Por padrão, o Web Player SDK ativa o relatório de logs. Passar traceId ajuda a identificar usuários. Se omitido, o Web Player SDK gera e armazena um UUID no cache do navegador.

Nota

Suportado na versão 2.10.0 e posteriores do Web Player SDK.

textTracks

Array

Configure legendas externas WebVTT. Exemplo:

textTracks: [
  { kind: 'subtitles', label: 'Chinese', src: 'caption-url', srclang: 'zh-CN', default: true },
  { kind: 'subtitles', label: 'English (US)', src: 'caption-url', srclang: 'en-US' }
],

Descrições dos campos:

  • kind: Tipo de legenda. Valores válidos: subtitles ou captions.

  • label: Nome da legenda exibido na UI.

  • srclang: Idioma da legenda.

  • src: URL da legenda. O acesso cross-origin deve ser permitido.

  • default: Defina como true para exibir esta legenda por padrão. Suportado na versão 2.15.7 e posteriores do Web Player SDK.

Nota
  • Suportado na versão 2.12.0 e posteriores do Web Player SDK.

  • Legendas externas WebVTT não são suportadas nos seguintes navegadores:

    • Internet Explorer

    • QQ Browser para Android, navegadores de sistema OPPO/OnePlus

    • Outros navegadores que sequestram a tag de vídeo

  • Para descrições detalhadas dos atributos de legenda, consulte a especificação HTML.

  • Para configurações avançadas de legenda, consulte External Captions.

ratio

Number

Configure o player para escalar com uma proporção fixa. Por exemplo, dada uma proporção de vídeo de 16:9, defina os parâmetros do player como width: "100%", ratio: 16/9. Isso mantém a proporção do player consistente com o conteúdo do vídeo e permite que ele escale proporcionalmente conforme a página é redimensionada.

extLanguageTexts

Object

O Web Player SDK inclui textos de UI integrados em chinês e inglês. Use esta propriedade para personalizar textos de elementos específicos da UI. Por exemplo, para alterar a exibição de HD de alta definição para 1080p:

extLanguageTexts: {
    'zh-cn': {
      'HD': '1080p'
    }
}

speedLevels

Array

Personalize a lista de velocidades de reprodução. Cada objeto contém uma chave (valor da velocidade) e texto (rótulo da UI). Se omitido, a lista padrão é usada. Exemplo:

speedLevels: [
  {"key": 0.25, "text": "0.25"},
  {"key": 0.5, "text": "0.5"},
  {"key": 1, "text": "Normal"},
  {"key": 1.25, "text": "1.25"},
  {"key": 1.5, "text": "1.5"},
  {"key": 2,"text": "2"}
]

logo

Array

Configure imagens de logotipo personalizadas. Exemplo:

    logo: [{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.png'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.png'
    }]

Descrições dos campos:

  • src: URL da imagem do logotipo.

  • origin: Ponto de referência para posicionamento. Valores válidos:

    • box: Contêiner do player

    • content: Conteúdo do vídeo

  • width/height: Dimensões do logotipo como porcentagem (calculada em relação à origem). Se apenas uma dimensão for especificada, a outra escala proporcionalmente.

  • position: Posição relativa dentro da origem. Valores válidos:

    • top-left: Canto superior esquerdo

    • top-right: Canto superior direito

    • bottom-left: Canto inferior esquerdo

    • bottom-right: Canto inferior direito

  • offsetX/offsetY: Deslocamento a partir da posição, como porcentagem (calculado em relação à origem).

license

Object

Para usar recursos de valor agregado como Playback Quality Monitoring (Legacy), Single-point Troubleshooting ou H.265/H.266 Video Playback, primeiro envie o Formulário de Solicitação de Serviços de Valor Agregado do Web Player SDK para obter uma licença. Em seguida, integre a licença da seguinte forma:

// domain is the domain you entered when applying for the license.
// key is the license key.
license: {
    domain: "example.com",
    key: "example-key"
  }

mute

Boolean

Ativa a reprodução sem som. Configure este parâmetro para permitir reprodução automática sem som quando os navegadores bloquearem a reprodução automática. Para detalhes, consulte Advanced Features.

clickPause

Boolean

Clique em na área do vídeo para pausar ou retomar a reprodução.

  • true: Ativar.

  • false: Desativar.

Padrão: true em desktop, false em dispositivos móveis. Não use junto com dbClickSkip para evitar conflitos de interação.

disablePip

Boolean

Oculta o botão nativo de Picture-in-Picture (PiP) do navegador.

Nota
  • Suportado na versão 2.20.0 e posteriores do Web Player SDK.

  • Suportado no Firefox versão 116 e posteriores.

env

String

Por padrão, os dados de telemetria do player são enviados para o data center da china. Se você tiver requisitos de conformidade para dados fora da china, defina env: 'SEA' para enviar dados ao data center de Singapore.

watchStartTime

Number

Use isoladamente para definir o horário de início da reprodução.

Use em conjunto com watchEndTime para ativar a reprodução por intervalo de tempo. Os usuários só poderão reproduzir e buscar dentro do intervalo especificado.

Unidade: segundos

watchEndTime

Number

Use em conjunto com watchStartTime para ativar a reprodução por intervalo de tempo. Os usuários só poderão reproduzir e buscar dentro do intervalo especificado.

Se este valor for menor que watchStartTime, watchStartTime será ignorado.

Unidade: segundos

start

Number

Use em conjunto com end para extrair um segmento do vídeo. Por exemplo, se o vídeo original tem 60 segundos e você define start: 10 e end: 30, o player exibirá um vídeo de 20 segundos começando a partir do décimo segundo do vídeo original.

end

Number

Use em conjunto com start para extrair um segmento do vídeo. Por exemplo, se o vídeo original tem 60 segundos e você define start: 10 e end: 30, o player exibirá um vídeo de 20 segundos começando a partir do décimo segundo do vídeo original.

dbClickFullscreen

Boolean

Ativa o clique em duplo para entrar em tela cheia. Ativado por padrão em desktop.

longPressFastForward

Boolean

Ativa o avanço rápido ao pressionar longamente (apenas dispositivos móveis). Valores válidos:

  • true (padrão): Ativar.

  • false: Desativar.

dbClickSkip

Boolean

Clique em duplo no lado esquerdo para retroceder, clique em duplo no lado direito para avançar rapidamente (apenas dispositivos móveis). Valores válidos:

  • true (padrão): Ativar.

  • false: Desativar.

Não use junto com clickPause para evitar conflitos de interação.

enableMockFullscreen

Boolean

Ativa a pseudo-tela cheia baseada em CSS. Por padrão, o player chama a API de tela cheia do navegador. No iOS e em alguns navegadores Android, o player do sistema assume a tela cheia, causando problemas de UI. Ative este parâmetro para evitar essa sobreposição. Padrão: false.

watermark

Object

Configure marcas d'água dinâmicas. Exemplo:

watermark: {
  enable: true,
  text: 'Copyright ©2026',
  mode: 'BULLET'
}

Descrições dos campos:

  • enable: Ativa a marca d'água dinâmica.

  • text: Texto a ser exibido como marca d'água.

  • mode: Modo da marca d'água. Valores válidos:

    • BULLET: Letreiro (padrão).

    • GHOST: Piscar aleatório.

  • direction: Direção do movimento. Valores válidos:

    • RTL: Da direita para a esquerda (padrão).

    • LTR: Da esquerda para a direita.

    • STATIC: Estacionário (válido apenas para o modo GHOST).

  • speed: Velocidade do movimento. Intervalo: 0~100. Valores maiores significam movimento mais rápido. Padrão: 50 para BULLET, 30 para GHOST.

  • interval: Tempo em milissegundos entre o desaparecimento e o reaparecimento da marca d'água. Padrão: 3000.

  • duration: Duração da exibição para cada aparição da marca d'água (apenas modo GHOST). Padrão: 5000 (milissegundos).

  • opacity: Transparência do texto da marca d'água. Intervalo: 0~1. Padrão: 0,5.

  • fontSize: Tamanho da fonte do texto da marca d'água. Valor CSS font-size. Padrão: 14px.

  • fontColor: Cor do texto da marca d'água. Qualquer valor de cor CSS válido. Padrão: #FFFFFF.

  • top: Distância do topo do contêiner até a área da marca d'água. Suporta valores em pixels (ex.: 50) ou porcentagens (ex.: '20%').

  • bottom: Distância da parte inferior do contêiner até a área da marca d'água. Suporta valores em pixels ou porcentagens.

  • left: Distância da esquerda do contêiner até a área da marca d'água. Suporta valores em pixels ou porcentagens (apenas modo GHOST).

  • right: Distância da direita do contêiner até a área da marca d'água. Suporta valores em pixels ou porcentagens (apenas modo GHOST).

memoryPlay

Object

Para ativar a retomada de reprodução, adicione a opção memoryPlay à configuração do player. Exemplo:

// Resume playback configuration
    memoryPlay: {
        enable: true, // Enable resume playback.
        autoSeek: false // Automatically jump to the remembered position.
    }

Descrições dos campos:

  • enable: Ativa a retomada de reprodução. Valores válidos:

    • false (padrão): Desativa a retomada de reprodução.

    • true: Ativa a retomada de reprodução.

  • autoSeek: Salta automaticamente para a posição memorizada. Valores válidos:

    • false (padrão): Mostra um prompt perguntando ao usuário se deseja saltar (recomendado).

    • true: Salta para a posição memorizada e mostra um prompt após o carregamento do vídeo.

getTimeFunction/saveTimeFunction são usados para cenários que exigem controle personalizado do progresso de reprodução (como sincronização entre vários dispositivos). Se omitido, o player armazena o progresso no localStorage por padrão.

  • getTimeFunction: Recupera o tempo memorizado de um local de armazenamento personalizado. Assinatura da função: (videoKey) => number|Promise<number>.

  • saveTimeFunction: Salva o tempo atual de reprodução. Assinatura da função: (videoKey, currentTime) => void.

menuMode

String

Define onde exibir os controles de velocidade de reprodução, definição, legenda e faixa de áudio. Valores válidos:

  • fold (padrão): Coloca no submenu Configurações.

  • expand: Exibe na barra de controle (menu principal).

refreshUrl

(expiredUrl: string) => Promise<string>

A expiração da URL é atualizada automaticamente. Quando a URL assinada do CDN expira durante a reprodução (o cabeçalho de resposta HTTP 403 contém o timestamp expirado), o callback do service é chamado automaticamente para obter a nova URL e retomar a reprodução, com até 3 tentativas. Recebe o endereço de reprodução atualmente expirado e retorna a Promise resolvida com um novo endereço disponível. Se não configurado, a função não é ativada. Exemplo:

new Aliplayer({
  source: 'YOUR_SOURCE_URL',
  refreshUrl: async (expiredUrl) => {
      // await fetch new url ...
      return 'NEW_URL'
  }
});

Métodos

É possível chamar estes métodos após a ocorrência do evento ready ou no callback ready ao criar o player. Exemplos:

// Method 1:
var player = new Aliplayer({}, function (player) {
  player.play();
});

// Method 2:
var player = new Aliplayer({});
function handleReady(player) {
  player.play();
};
player.on('ready', handleReady);

Métodos disponíveis para uma instância do Aliplayer:

play()

Inicia a reprodução.

Definição da Função

() => Player

pause()

Pausa a reprodução.

(showPlayButton?: boolean) => Player

Parâmetros

Nome

Tipo

Obrigatório

Descrição

showPlayButton

Boolean

Não

Mostra o botão de reprodução.

replay()

Reinicia a reprodução.

Definição da Função

() => Player

seek()

Salta para um tempo específico.

Definição da Função

(time: number) => Player 

Parâmetros

Nome

Tipo

Obrigatório

Descrição

time

number

Sim

Tempo para o qual saltar. Unidade: segundos.

dispose()

Destrói o player.

Definição da Função

() => void

getCurrentTime()

Obtém o tempo atual de reprodução. A unidade é segundos.

Definição da Função

() => number

getDuration()

Obtém a duração total do vídeo. A unidade é segundos. Você pode chamar este método após o carregamento do vídeo ou após o evento play.

Definição da Função

() => number

getVolume()

Obtém o volume atual. Retorna um número real entre 0 e 1. Não suportado no iOS e em alguns dispositivos Android.

Definição da Função

() => number | undefined

setVolume()

Define o volume.

Definição da Função

(volume: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

volume

number

Sim

Volume como um número real entre 0 e 1. Não suportado no iOS e em alguns dispositivos Android.

mute()

Silencia a reprodução.

Definição da Função

(quiet?: boolean) => Player

Parâmetros

Nome

Tipo

Obrigatório

Descrição

quiet

boolean

Não

Oculta o texto de status mudo/com som no canto inferior esquerdo.

unMute()

Reativa o som da reprodução.

Definição da Função

(quiet?: boolean) => Player

Parâmetros

Nome

Tipo

Obrigatório

Descrição

quiet

boolean

Não

Se deve ocultar o prompt de texto no canto inferior esquerdo ao reativar o som.

getPlayTime()

Obtém o tempo real de reprodução (excluindo o tempo pausado). Para reprodução com velocidade variável, isso retorna o tempo decorrido efetivo. A unidade é segundos.

Definição da Função

() => number

loadByUrl()

Troca para outro vídeo. Suporta troca apenas entre vídeos do mesmo formato, como MP4, HLS ou FLV. Para trocar entre formatos diferentes, destrua o player e crie uma nova instância.

Definição da função

(url: string, seconds?: number, autoPlay?: boolean) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

url

string

Sim

A URL do vídeo para o qual trocar.

seconds

number

Não

Tempo de início da reprodução após a troca.

autoPlay

boolean

Não

Inicia a reprodução automaticamente após a troca.

replayByVidAndPlayAuth()

Troca para outro vídeo VOD. Suporta troca apenas entre vídeos do mesmo formato.

Definição da Função

(vid: string, playauth: string) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

vid

string

Sim

O ID do vídeo.

playauth

string

Sim

A credencial de reprodução.

replayByVidAndAuthInfo()

Troca para outro vídeo MPS. Suporta troca apenas entre vídeos do mesmo formato.

Definição da Função

(vid: string, accId: string, accSecret: string, stsToken: string, authInfo: string, domainRegion: string) => void

Para mais informações sobre os detalhes dos parâmetros, consulte MPS Playback.

replayByMediaAuth()

Troca para outro vídeo do Universal Media Service. Suporta troca apenas entre vídeos do mesmo formato.

Definição da função

(mediaAuth: string) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

mediaAuth

string

Sim

A credencial de reprodução.

getBuildInComponent()

Obtém um componente de UI integrado (como um botão de tela cheia ou barra de progresso).

Definição da Função

(name: string) => BuildInComponent;

Parâmetros

Nome

Tipo

Obrigatório

Descrição

name

string

Sim

O nome do componente integrado (ex.: fullScreenButton). Consulte Configure the skinLayout Property para obter uma lista de nomes de componentes. Cada componente suporta os métodos hide e show.

setPlayerSize()

Define o tamanho do player.

Definição da função

(width: string, height: string) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

width

string

Sim

Define o tamanho do player. Valores válidos:

  • 400px

  • 60%

height

string

Sim

setSpeed()

Define manualmente a velocidade de reprodução. Isso pode não funcionar em dispositivos móveis (como WeChat no Android). Os controles de velocidade estão ativados por padrão.

Definição da Função

(speed: number) => void

Parâmetros

Nome

Tipo de parâmetro

Obrigatório

Descrição

speed

number

Sim

Suporta velocidades de reprodução de 0,5× a 2×.

Nota

Para desativar os controles de velocidade:

  • Não é possível desativar ou personalizar os controles de velocidade individualmente. Você deve desativá-los globalmente.

  • Para desativar os controles de velocidade via substituição CSS:

    .prism-setting-speed {
       display: none !important;
     }

setTraceId()

Passa instrumentação comum para rastreamento de logs.

Definição da função

(traceId: string) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

traceId

string

Sim

Um identificador exclusivo.

Nota

Suportado na versão 2.10.0 e posteriores do Web Player SDK.

setSanpshotProperties()

Configura as definições de captura de tela.

Definição da Função

(width: number, height: number, rate: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

width

number

Sim

Unidades de largura e altura: pixels. Intervalo de qualidade da captura: 0–1 (padrão: 1). Para mais detalhes, consulte Video Screenshots.

height

number

Sim

rate

number

Sim

fullscreenService.requestFullScreen()

Entra em tela cheia.

Definição da Função

() => Player

fullscreenService.cancelFullScreen()

Sai da tela cheia. Não suportado no iOS.

Definição da função

() => Player

fullscreenService.getIsFullScreen()

Obtém o estado de tela cheia.

Definição da Função

() => boolean

getStatus()

Obtém o estado do player. Retorna uma string. Como:

  • init: Inicializando.

  • ready: Pronto.

  • loading: Carregando.

  • play: Reproduzindo.

  • pause: Pausado.

  • playing: Reproduzindo.

  • waiting: Buffering.

  • error: Erro.

  • ended: Finalizado.

Definição da Função

() => string

liveShiftSerivce.setLiveTimeRange()

Define a hora de início e término para transmissão ao vivo. Use isto para ativar o time shifting.

Definição da Função

(start: string, end: string) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

start

string

Sim

Hora de início da transmissão ao vivo.

end

string

Sim

Hora de término da transmissão ao vivo.

Exemplo

player.liveShiftSerivce.setLiveTimeRange('2025/03/21 12:43:00', '2025/03/21 23:31:00')

setRotate()

Define o ângulo de rotação do player.

Definição da Função

(rotate: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

rotate

number

Sim

Valores positivos giram no sentido horário. Valores negativos giram no sentido anti-horário. Exemplo: setRotate(90). Para mais informações, consulte Set Display Mode.

getRotate()

Obtém o ângulo de rotação do player.

Definição da Função

() => number

Para mais informações, consulte Set Display Mode.

setImage()

Aplica espelhamento.

Definição da Função

(type: string) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

type

string

Sim

Valores válidos:

  • horizon: Espelhamento horizontal.

  • Vertical: Refere-se a uma orientação vertical.

Exemplo: setImage('horizon'). Para mais informações, consulte Set Display Mode.

setCover()

Define a imagem de capa.

Definição da Função

(coverUrl: string) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

coverUrl

string

Sim

URL da miniatura.

setProgressMarkers()

Define marcadores de progresso.

Definição da função

(markers: Array<{ time: number, text: string }>) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

markers

Array<markers>

Sim

markers: Array de objetos de marcador (obrigatório).

marker.time: Tempo do marcador (obrigatório).

marker.text: Rótulo de texto para o marcador (obrigatório).

Consulte o parâmetro progressMarkers para detalhes.

setPreviewTime()

Define a duração da prévia.

Definição da Função

(time: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

time

number

Sim

Unidade: segundos. Para mais informações, consulte Prévia.

getPreviewTime()

Obtém a duração da prévia.

Definição da função

() => number

isPreview()

Verifica se o modo de prévia está ativo.

Definição da Função

() => boolean

getCurrentPDT()

Obtém o ProgramDateTime atual para streams de vídeo HLS.

Definição da Função

() => number | undefined

setTextTracks()

Define um array de legendas WebVTT.

Definição da função

(textTracks: Array<{ kind: string, label: string, src: string, srclang: string }>) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

textTracks

Array<object>

Sim

Exemplo:

player.setTextTracks([ { kind: 'subtitles', label: 'Chinese', src: 'caption-url', srclang: 'zh-CN' },{ kind: 'subtitles', label: 'English (US)', src: 'caption-url', srclang: 'en-US' }])
Nota

Suportado na versão 2.12.0 e posteriores do Web Player SDK.

setLogo()

Define imagens de logotipo personalizadas.

Definição da função

(logoList: Array<{ width: number, position: string, origin: string, src: string }>) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

logoList

Array<object>

Sim

Exemplo:

player.setLogo([{
      width: 30,
      position: 'bottom-right',
      origin: 'content',
      src: 'a.jpg'
    },
    {
      width: 20,
      position: 'bottom-right',
      offsetY: -20,
      origin: 'content',
      src: 'b.jpg'
    }])

Para descrições dos campos, consulte a propriedade: logo.

setWatchTime()

Atualiza dinamicamente watchStartTime/watchEndTime do vídeo atual.

Definição da função

(start: number, end: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

start

string

Sim

Hora de início.

end

string

Sim

Hora de término.

setNextWatchTime()

Define watchStartTime/watchEndTime do próximo vídeo. Se você usar loadByUrl ou replayByVidAndPlayAuth para trocar de vídeos, e o próximo vídeo tiver um intervalo de tempo diferente do atual, chame setNextWatchTime primeiro.

Definição da função

(start: number, end: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

start

string

Sim

Hora de início.

end

string

Sim

Hora de término.

setStartEnd()

Atualiza dinamicamente start/end do vídeo atual.

Definição da Função

(start: number, end: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

start

string

Sim

Hora de início.

end

string

Sim

Hora de término.

setNextStartEnd()

Define start/end do próximo vídeo. Se você usar loadByUrl ou replayByVidAndPlayAuth para trocar de vídeos, e o próximo vídeo tiver um intervalo de segmento diferente do atual, chame setNextStartEnd primeiro.

Definição da Função

(start: number, end: number) => void

Parâmetros

Nome

Tipo

Obrigatório

Descrição

start

string

Sim

Hora de início.

end

string

Sim

Hora de término.

takeSnapshot()

Captura uma tela. A string base64 retornada pode ser usada diretamente como valor img.src. Você pode usar setSnapshotProperties para configurar a qualidade da captura e snapshotWatermark para adicionar uma marca d'água.

Nota: A funcionalidade de captura de tela pode não funcionar em alguns navegadores móveis onde a tag de vídeo é sequestrada (como UC Browser ou QQ Browser).

Definição da Função

() => { time: number, base64: string, binary: string, error: Error | null }

Valor de retorno

Nome

Tipo

Descrição

time

string

Tempo da captura de tela.

base64

string

Conteúdo da captura de tela codificado em Base64.

binary

string

Representação em string binária do conteúdo da captura de tela.

error

Error

Detalhes de qualquer erro de captura de tela.

showControlBar()

Mostra a barra de controle.

Definição da Função

() => void

hideControlBar()

Oculta a barra de controle.

Definição da Função

() => void

Eventos

Eventos do Player

Nome

Descrição

ready

A UI do player termina a renderização. Acione a lógica de inicialização da UI após este evento para evitar que seja sobrescrita pela inicialização padrão.

Nota

Você só pode chamar métodos do player após a ocorrência deste evento.

play

Dispara quando a reprodução é retomada após uma pausa.

pause

Dispara quando a reprodução é pausada.

canplay

Dispara quando o áudio ou vídeo pode começar a ser reproduzido. Este evento pode disparar várias vezes. Apenas players HTML5.

playing

Dispara repetidamente durante a reprodução.

ended

Dispara quando o vídeo atual termina a reprodução.

liveStreamStop

Dispara quando uma transmissão ao vivo é interrompida. Para streams HLS ao vivo, isso ocorre após cinco tentativas falhas de reconexão. Notifica a camada de aplicação que o stream parou ou precisa ser recarregado.

Nota

Se uma transmissão ao vivo HLS falhar ou desconectar, o player tentará reconectar automaticamente cinco vezes. Não implemente lógica adicional de nova tentativa na camada de aplicação.

onM3u8Retry

Dispara uma vez a cada tentativa de reconexão do player após uma interrupção de stream HLS ao vivo.

hideBar

Dispara quando a barra de controle é ocultada automaticamente.

showBar

A barra de controle é exibida automaticamente (evento).

waiting

Dispara durante o buffering de dados.

timeupdate

Dispara quando a posição de reprodução muda. Chame getCurrentTime() para obter o tempo atual de reprodução.

snapshoted

Dispara quando uma captura de tela é concluída.

requestFullScreen

Dispara ao entrar em tela cheia.

cancelFullScreen

Dispara ao sair da tela cheia. Não dispara no iOS.

error

Dispara quando ocorre um erro.

startSeek

O parâmetro retorna o tempo de criação do ponto de arraste no início de uma operação de arraste.

completeSeek

Ao concluir a operação de arraste, os parâmetros indicam o timestamp do ponto de arraste.

resolutionChange

Dispara quando a fonte da transmissão ao vivo muda de resolução.

seiFrame

Dispara ao receber mensagens SEI via HLS ou FLV.

rtsFallback

Dispara quando ocorre fallback de RTS. O parâmetro reason indica o motivo do fallback. O parâmetro fallbackUrl contém a URL de fallback.

settingSelected

Dispara quando uma configuração (ex.: velocidade de reprodução, definição, legenda) é selecionada.

Nota

Como o plugin de velocidade open-source não sincroniza com o player, usá-lo requer código personalizado e recompilação. Defina seu próprio listener de evento. Para usar o evento settingSelected do player, remova este plugin.

/**
     * Fires when a setting is selected, e.g., switching to 1.25× speed:
     * {name: 'Speed', type: 'speed', text: '1.25×', key: 1.25}
     */

rtsTraceId

Este evento é acionado quando o pull de stream RTS é bem-sucedido, e você pode assinar para obter o TraceId do RTS. Na saída de log, o campo traceId do parâmetro data.paramData é o TraceId para o pull de stream, e o campo source é o endereço de reprodução do stream RTS atual.

player.on('rtsTraceId', function(data) {
      console.log('[EVENT]rtsTraceId', data.paramData);
    })

autoplay

Dispara quando a reprodução automática tem sucesso ou falha. O parâmetro de callback event.paramData é true em caso de sucesso e false em caso de falha. Em caso de falha, a interação do usuário é necessária para iniciar a reprodução.

mutedAutoplay

Dispara quando a reprodução automática sem som tem sucesso e autoplayPolicy.fallbackToMute está definido como true.

videoUnavailable

Dispara quando a reprodução de vídeo falha devido a codificação não suportada, causando uma tela preta. Por exemplo, reproduzir vídeo H.265 em um navegador que não suporta H.265 resulta em uma tela preta apenas com áudio.

urlExpired

Acionado após a detecção de expiração da URL e antes da chamada do callback refreshUrl. Parâmetro de callback: { url: expiredUrl }.

urlRefreshed

Acionado após o carregamento bem-sucedido da nova URL (canplay), indicando que a reprodução foi retomada. Parâmetro de callback:{ url: newUrl }.

Assinatura de Eventos

  • Assine eventos usando o método on da instância do player. Por exemplo:

    function handleReady() {};
    player.on('ready', handleReady);
    // Some events fire frequently. Use player.one to listen once.
    player.one('canplay', () => {});
  • Cancele a assinatura de eventos usando o método off da instância do player. Por exemplo:

    player.off('ready',handleReady);