Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Recursos básicos

Última atualização: Jun 27, 2026

Ao usar o ApsaraVideo Player SDK for Web, as configurações dos recursos comuns podem variar conforme o player, o método de reprodução ou o ambiente do navegador. Este tópico descreve como configurar os recursos básicos do ApsaraVideo Player SDK for Web.

Configurações comuns

Para reproduzir vídeos Flash Video (FLV) e HTTP Live Streaming (HLS) com o player web, configure o compartilhamento de recursos de origem cruzada (CORS). Para mais informações, consulte Configurar acesso de origem cruzada.

  • Se você não configurar o CORS ao usar o player web, a seguinte mensagem de erro será exibida durante a reprodução:

    No 'Access-Control-Allow-Origin' header is present on the requested resource.

Nota

Após iniciar a reprodução em tela cheia, configure a entrada para definir o posicionamento absoluto e ativar o teclado virtual.

Métodos de chamada

Os recursos básicos do ApsaraVideo Player SDK for Web são ativados por atributos ou métodos.

Nota

Para mais informações, consulte Referência da API do Aliplayer.

O exemplo a seguir demonstra como chamar os métodos:

Chame o método abaixo no callback da função usada para criar um player. Exemplo:

var player = new Aliplayer({},function(player) {
    player.setSpeed(2);
 });

Gerenciar a reprodução de mídia

O ApsaraVideo Player SDK for Web permite reproduzir vídeos a partir de um ponto específico e pausar a reprodução.

Reproduzir um vídeo a partir de um ponto específico

Use o método seek para iniciar a reprodução em um momento determinado. Exemplo:

// time specifies the specified point in time. Unit: seconds. 
player.seek(time)

Pausar a reprodução

Use o método pause para interromper temporariamente a reprodução. Exemplo:

player.pause()
Nota

Para exibir o botão grande de reprodução, defina este parâmetro como true. Exemplo: player.pause(true).

Destruir o player

Use o método dispose para destruir uma instância do player. Exemplo:

player.dispose()

Especificar o modo de exibição

Nota
  • Navegadores de PC e iOS oferecem suporte às configurações de exibição.

  • Chrome e Firefox para Android também oferecem suporte a essas configurações.

  • O WeChat e a maioria dos demais navegadores usam o player nativo para reprodução; portanto, não há suporte às configurações de exibição.

Especificar o ângulo de rotação

Use a operação setRotate para girar a imagem conforme o ângulo desejado. Também é possível consultar o ângulo atual. Exemplo:

// Specify the rotation angle. A positive value of Angle specifies a clockwise rotation. A negative value of Angle specifies an anticlockwise rotation. For example, player.setRotate(180) specifies a clockwise rotation of 180 degrees. 
player.setRotate(<Angle>)
// Obtain the rotation angle. 
player.getRotate()

Especificar o modo de espelhamento

Chame setImage para configurar o modo de espelhamento. Modos suportados: espelhamento horizontal e vertical. Exemplo:

// Horizontal mirroring.
player.setImage('horizon')
// Vertical mirroring.
player.setImage('vertical')

O ApsaraVideo Player SDK for Web disponibiliza os atributos videoHeight e videoWidth para definir a altura e a largura do vídeo. Geralmente, essas dimensões são menores que as do contêiner para evitar que o vídeo transborde do elemento pai durante rotações e espelhamentos. Exemplo:

 width: '100', // The width of the container.
 height: '100%', // The height of the container.
 videoHeight:"200px", // The height of the video.

Obter informações de reprodução

Com o ApsaraVideo Player SDK for Web, é possível obter o progresso atual e a duração total da reprodução.

Obter o progresso da reprodução

Use getCurrentTime para recuperar o progresso atual. Exemplo:

// The returned time is measured in seconds. 
player.getCurrentTime()

Obter a duração da reprodução

Consulte a duração total de um vídeo. Essa informação só fica disponível após o carregamento do conteúdo. Por exemplo, faça a consulta após o evento de reprodução ser disparado. Chame getDuration para obter a duração total. O vídeo precisa estar carregado ou em reprodução para que o valor seja retornado. Exemplo:

player.getDuration()

Obter o status da reprodução

Use getStatus para verificar o estado atual da reprodução. Valores de retorno:

  • init: Inicializando.

  • ready: Pronto.

  • loading: Carregando.

  • play: Reproduzindo.

  • pause: Pausado.

  • playing: Em reprodução.

  • waiting: Bufferizando.

  • error: Erro.

  • ended: Finalizado.

Exemplo:

player.getStatus()

Especificar o volume

Ajuste o nível de áudio ou silencie o vídeo conforme necessário.

Nota

Como a propriedade video.volume é somente leitura no iOS e em alguns sistemas Android, os métodos getVolume e setVolume fornecidos pelo ApsaraVideo Player SDK for Web não funcionam nessas plataformas.

Ajustar o volume

Use a operação setVolume para modificar o volume. Também é possível consultar o nível atual. Exemplo:

// Set the volume to a real number from 0 to 1. 
player.setVolume(0)
// Obtain the current volume. 
player.getVolume()

Configurar o modo mudo

Use o método mute para silenciar o áudio durante a reprodução. Exemplo:

// Mute the video.
player.mute();
// Unmute the video.
player.unMute();

Especificar a velocidade de reprodução

Se você usar a interface de usuário (UI) padrão do ApsaraVideo Player SDK for Web, aproveite o recurso integrado para alterar a velocidade enquanto assiste ao vídeo. Para interfaces personalizadas, chame a operação setSpeed para fazer esse ajuste.

Nota

Para saber como desativar as configurações de velocidade, consulte a seção setSpeed no tópico Referência da API do Aliplayer.

Exemplo:

// Specify the playback speed. The following sample code provides an example on how to set the playback speed to twice the current speed. 
player.setSpeed(2)

Reprodução com múltiplas definições

Configure as URLs de streams em diferentes resoluções para habilitar a reprodução com múltiplas definições.

  • Na reprodução via VID e PlayAuth, nenhuma configuração adicional é necessária. O ApsaraVideo Player SDK for Web obtém automaticamente a lista de definições do ApsaraVideo VOD. Clique em Settings na página de reprodução para visualizar as opções disponíveis.

    Nota

    Nesse cenário (VID e PlayAuth), use o atributo format para escolher entre os formatos MP4 ou MP3 no player HTML5. Por padrão, arquivos MP4 são selecionados.

  • Para reprodução baseada em URL, configure pares chave-valor no atributo source indicando as URLs das streams em cada definição. Esses pares devem estar no formato JSON. Após aplicar as configurações, clique em Settings na página de reprodução para ver a lista de definições.

Nota

Para alterar a forma como a lista de definições é apresentada, use o componente de definição. Para exemplos de código, consulte Funções.

No modo de reprodução por URL, os seguintes pares chave-valor são suportados no atributo source:

   "OD": "<Original quality URL>"
   "FD": "<Low definition URL>"
   "LD":"<Standard definition URL>"
   "SD": "<High definition URL>"
   "HD": "<Ultra-high definition URL>"
   "2K": "<2K URL>"
   "4K": "<4K URL>"

Veja abaixo um exemplo de configuração de definições no modo de reprodução por URL:

// The following example shows how to configure the high definition and ultra-high definition URLs. 
source:'{"HD":"http://******/player/hdexample.mp4","SD":"http://******/player/sdexample.mp4"}'

O ApsaraVideo Player SDK for Web também permite usar o atributo qualitySort para ordenar as definições de forma crescente ou decrescente.

  • O valor desc organiza a lista da maior para a menor definição.

  • O valor asc ordena da menor para a maior definição.

Nota
  • O player memoriza a definição escolhida. Na próxima reprodução, ele aplicará automaticamente a última seleção. Caso nenhuma definição tenha sido especificada anteriormente, uma versão de baixa qualidade será utilizada.

  • Se houver falha na reprodução da definição selecionada, o player mudará automaticamente para a próxima definição inferior e exibirá uma mensagem. Apenas o player HTML5 suporta essa troca automática.

Ativar reprodução em loop

É possível configurar o loop definindo o atributo rePlay ou escutando o evento ended no ApsaraVideo Player SDK for Web.

Exemplo de código para definir o atributo rePlay

rePlay:true

Exemplo de código para escutar o evento ended

player.on('ended',function(){
   player.replay()
})

Operações por gestos em dispositivos móveis

O Player SDK for Web foi otimizado para telas pequenas de dispositivos móveis, facilitando o arrasto da barra de progresso. Dois recursos exclusivos estão disponíveis: manter pressionado para acelerar e toque duplo para avançar ou retroceder rapidamente.

Manter pressionado para acelerar

Por padrão, o recurso de aceleração por pressão está ativado em dispositivos móveis. Ao tocar e segurar qualquer área do player (exceto a barra de progresso) por mais de 0,5 segundo, o vídeo é reproduzido em velocidade acelerada. Ao soltar, a velocidade original é restaurada.

Para desativar essa funcionalidade, configure o parâmetro longPressFastForward: false. Para mais detalhes, consulte Referência da API do Aliplayer.

Toque duplo para avançar ou retroceder

O recurso de avanço/retrocesso por toque duplo vem habilitado por padrão em dispositivos móveis. Um toque duplo no terço esquerdo da tela faz o vídeo retroceder 10 segundos. Já no terço direito, o vídeo avança 10 segundos.

Desative esse comportamento configurando o parâmetro dbClickSkip: false. Para mais informações, veja Referência da API do Aliplayer.

Relatório de falhas

Referências