Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Referência da API do Aliplayer

Última atualização: Jul 03, 2026

Este tópico descreve as propriedades, métodos e eventos compatíveis com o Aliplayer.

Nota

Se você encontrar problemas ao usar o Aliplayer, consulte Perguntas frequentes sobre o Web Player ou Solução autônoma de erros de reprodução.

Propriedades

Ao inicializar o Aliplayer, defina 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 substitui 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 Reprodução com múltiplas definições. Exemplo:

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

vid

String

ID da mídia para o serviço ApsaraVideo Media Processing.

playauth

String

Credencial de reprodução. Para obter instruções sobre como adquirir uma credencial de reprodução, consulte Obter uma credencial de reprodução.

customVodServer

String

Domínio personalizado para proxy VOD (compatível com o modo de reprodução VidAuth versão 2.32.0 e posterior). É necessário implantar um serviço dedicado de proxy de requisições. Quando o domínio padrão do VOD (*.aliyuncs.com) estiver inacessível, o player alternará automaticamente para o seu serviço 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 compatíveis e descrições de parâmetros, consulte Configurações personalizadas do PlayConfig para reprodução de mídia. 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.

Observação: autoSize: true equivale a autoSize: 'height'. O ajuste automático de altura é o padrão.

videoWidth

String

Largura do vídeo. Para mais informações, consulte Definir modo de exibição.

videoHeight

String

Altura do vídeo. Para mais informações, consulte Definir modo de exibição.

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. O autoplay 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 Recursos avançados.

autoplayPolicy

Object

O player suporta uma política adaptativa para reprodução automática sem som. Esta propriedade só tem efeito quando autoplay está definido como true. Um exemplo de configuração é apresentado abaixo:

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 Personalizar a skin do player.

skinLayout

Array | Boolean

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

skinLayoutIgnore

Array

Lista de componentes da UI a serem ocultados. Consulte a Referência de parâmetros de componentes VOD para ver 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. Os valores válidos incluem:

  • click: Permite clicar 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 direito). Padrão: false.

format

String

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

  • mp4

  • hls ou m3u8

  • flv

  • mp3

Padrão: vazio.

mediaType

String

Especifica se deve retornar áudio ou vídeo. Compatível 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

Define a ordem de classificação. Compatível 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

Configura marcas d'água para capturas de tela em 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 a buffering. Padrão: 20.

waitingTimeout

Number

Tempo 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): Mostrar o botão.

  • false: Ocultar 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: Reproduzir vídeos não criptografados.

  • 1: Reproduzir vídeos com criptografia privada.

Nota

progressMarkers

Array

Um array de objetos de marcadores de progresso. Para mais informações, consulte Marcadores da barra 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 configuraçã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 configurar a sincronização de quadros no modo de transmissão ao vivo HLS, veja 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 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, veja 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, veja 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 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, veja 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 buffer para lidar com flutuações de rede, modifique o valor de liveSyncDurationCount com cautela — definir este valor muito baixo pode causar travamentos).

Nota

Este parâmetro é compatível 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 setas (esquerda/direita) controlam o avanço e retrocesso rápido. As setas (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 a extração do stream RTS falha, o player recai automaticamente para FLV ou HLS. Ele prefere FLV para menor latência. Se o navegador não suportar FLV, ele recorre ao HLS.

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

rtsFallbackType

String

Especifica o protocolo para o qual o RTS deve recair. 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 ao 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 o traceId ajuda a identificar usuários. Se omitido, o Web Player SDK gera e armazena um UUID no cache do navegador.

Nota

Compatível com a versão 2.10.0 e posteriores do Web Player SDK.

textTracks

Array

Configura 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. Compatível com a versão 2.15.7 e posteriores do Web Player SDK.

Nota
  • Compatível com a versão 2.12.0 e posteriores do Web Player SDK.

  • Legendas externas WebVTT não são compatíveis nos seguintes navegadores:

    • Internet Explorer

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

    • Outros navegadores que sequestram a tag video

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

  • Para configurações avançadas de legenda, consulte Legendas externas.

ratio

Number

Define 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 high definition 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 em porcentagem (calculadas 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 da posição, em porcentagem (calculado em relação à origem).

license

Object

Para usar recursos de valor agregado como Monitoramento de qualidade de reprodução (Legado), Solução de problemas pontuais ou Reprodução de vídeo H.265/H.266, 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 autoplay mudo quando os navegadores bloquearem a reprodução automática. Para detalhes, consulte Recursos avançados.

clickPause

Boolean

Clique 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
  • Compatível com a versão 2.20.0 e posteriores do Web Player SDK.

  • Compatível com o 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 Singapura.

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 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 duplo no lado esquerdo para retroceder, clique 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).

Métodos

Chame 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. Chame 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 compatível com iOS e 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 compatível com iOS e 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

Indica 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

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

Iniciar 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

ID do vídeo.

playauth

string

Sim

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 Reprodução MPS.

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

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

Nome do componente integrado (ex.: fullScreenButton). Consulte Configurar a propriedade skinLayout 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. Desative-os globalmente.

  • Para desativar os controles de velocidade via sobrescrita 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

Compatível com a 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 Capturas de tela de vídeo.

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 compatível com 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 o horário 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

Horário de início da transmissão ao vivo.

end

string

Sim

Horário 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 Definir modo de exibição.

getRotate()

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

Definição da função

() => number

Para mais informações, consulte Definir modo de exibição.

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 Definir modo de exibição.

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

Compatível com a 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 o 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

Horário de início.

end

string

Sim

Horário de término.

setNextWatchTime()

Define o 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

Horário de início.

end

string

Sim

Horário de término.

setStartEnd()

Atualiza dinamicamente o 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

Horário de início.

end

string

Sim

Horário de término.

setNextStartEnd()

Define o 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

Horário de início.

end

string

Sim

Horário de término.

takeSnapshot()

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

Observação: A funcionalidade de captura de tela pode não funcionar em alguns navegadores móveis onde a tag video é 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

Chame métodos do player apenas 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 eventos. 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 a extração do stream RTS é bem-sucedida. Assine-o para obter o TraceId do RTS. Na saída de log, o campo traceId do parâmetro data.paramData é o TraceId para a extração do 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 é bem-sucedida e autoplayPolicy.fallbackToMute está definido como true.

videoUnavailable

Dispara quando a reprodução de vídeo falha devido a codificação não compatível, 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.

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);