Todos os produtos
Search
Central de documentação

ApsaraVideo VOD:Recursos básicos

Última atualização: Jun 27, 2026

Use os recursos básicos do ApsaraVideo Player SDK for Flutter, incluindo controle de reprodução, configurações de exibição, ajuste de volume e velocidade, além da troca de definição. Para mais informações, consulte Recursos avançados e Referência da API.

Definir a fonte de dados (DataSource)

  • O ApsaraVideo Player SDK for Flutter oferece suporte a quatro métodos de reprodução VOD: VidAuth (recomendado), VidSts, UrlSource e reprodução criptografada.

  • Para streaming ao vivo, o ApsaraVideo Player SDK for Flutter suporta apenas o método UrlSource.

Reprodução VOD

Reprodução VOD com VidAuth (Recomendado)

Para reproduzir um vídeo VOD com VidAuth, defina vid como o ID do áudio ou vídeo e playauth como a credencial de reprodução.

  1. Após carregar um arquivo de áudio ou vídeo, obtenha seu ID no console do ApsaraVideo VOD selecionando Media Library > Audio/Video ou chamando a operação SearchMedia.

  2. Obtenha a credencial de reprodução chamando a operação GetVideoPlayAuth. Recomendamos usar um SDK para obter essa credencial e evitar a assinatura manual. Para ver um exemplo de chamada dessa operação, consulte Developer Portal.

Recomendamos que usuários do ApsaraVideo VOD utilizem este método de reprodução. O VidAuth é mais seguro e fácil de usar que o VidSts. Para uma comparação detalhada, consulte Comparação entre o método baseado em credenciais e o método baseado em STS.

void onViewPlayerCreated(viewId) async {
  // Set the rendered view for the player.
  fAliplayer.setPlayerView(viewId);
  // Note: Before you call generatePlayerConfig, you must call createVidPlayerConfigGenerator() and setPreviewTime().
  FlutterAliplayer.createVidPlayerConfigGenerator();
  FlutterAliplayer.setPreviewTime(0);
  // Set the playback source.
  FlutterAliplayer.generatePlayerConfig().then((value) {
      fAliplayer.setVidAuth(
          vid: "Your Vid",// Required. The video ID (VideoId).
          region: "Your Region",// Required. The region where ApsaraVideo VOD is activated. Default value: cn-shanghai.
          playAuth: "<yourPlayAuth>",// Required. The playback credential. You must call the GetVideoPlayAuth operation of ApsaraVideo VOD to generate the credential.
          playConfig: value);
        });    
  }
}

Reprodução VOD com VidSts

Para reproduzir um vídeo VOD com VidSts, utilize uma credencial temporária do Security Token Service (STS) em vez de uma credencial de reprodução VOD. Obtenha previamente o token STS e o par de AccessKey temporário (AccessKeyId e AccessKeySecret). Para mais informações, consulte Obter um token STS.

void onViewPlayerCreated(viewId) async {
  // Set the rendered view for the player.
  fAliplayer.setPlayerView(viewId);
  // Note: Before you call generatePlayerConfig, you must call createVidPlayerConfigGenerator() and setPreviewTime().
  FlutterAliplayer.createVidPlayerConfigGenerator();
  FlutterAliplayer.setPreviewTime(0);
  // Playback using VidSts.
  FlutterAliplayer.generatePlayerConfig().then((value) {
     fAliplayer.setVidSts(
          vid: "Your Vid",// Required. The video ID (VideoId).
          region: "Your Region",// Required. The region where ApsaraVideo VOD is activated. Default value: cn-shanghai.
          accessKeyId: "<yourAccessKeyId>",// Required. The AccessKey ID of the temporary AccessKey pair. You must call the AssumeRole operation of STS to generate the AccessKey ID.
          accessKeySecret: "<yourAccessKeySecret>",// Required. The AccessKey secret of the temporary AccessKey pair. You must call the AssumeRole operation of STS to generate the AccessKey secret.
          securityToken: "<yourSecurityToken>",// Required. The STS token. You must call the AssumeRole operation of STS to generate the token.
      	  playConfig: value);
    	});
       
}

Reprodução VOD com UrlSource

Para reproduzir um vídeo VOD com UrlSource, defina setUrl com a URL de reprodução. A URL pode ser de terceiros ou uma URL de reprodução do ApsaraVideo VOD.

Obtenha uma URL de reprodução da Alibaba Cloud chamando a operação GetPlayInfo. Recomendamos usar um SDK para obter a URL de reprodução e evitar a assinatura manual. Para ver um exemplo, consulte Developer Portal.

void onViewPlayerCreated(viewId) async {
  // Set the rendered view for the player.
  fAliplayer.setPlayerView(viewId);
  // Set the playback source.
  switch (_playMode) {
      // Playback using UrlSource.
    case ModeType.URL:
      this.fAliplayer.setUrl("Playback URL"); // Required. The playback URL. The URL can be a third-party VOD URL or a playback URL from ApsaraVideo VOD.
      break;
    default:
  }
}

Reprodução VOD criptografada

O ApsaraVideo VOD oferece suporte a criptografia HLS, criptografia proprietária da Alibaba Cloud e criptografia DRM. Para mais informações sobre reprodução criptografada, consulte Reproduzir vídeos criptografados no Flutter.

Reprodução de streaming ao vivo

Para mais informações, consulte ApsaraVideo Player for Flutter.

Nota
  • O UrlSource utiliza uma URL para reprodução. Já o VidSts e o VidAuth usam um ID de vídeo (VID).

  • Para mais detalhes sobre como definir a região, consulte Regiões do VOD.

Controlar a reprodução

O ApsaraVideo Player SDK for Flutter suporta operações comuns, como iniciar, pausar e buscar um ponto específico no tempo.

Reprodução automática

Use o método setAutoPlay para ativar a reprodução automática. Por padrão, esse recurso vem desativado. Exemplo:

fAliplayer.setAutoPlay(true);

Preparar para reprodução

Chame o método prepare para começar a ler e analisar os dados para reprodução. Se a reprodução automática estiver ativada, o vídeo será iniciado assim que a análise dos dados for concluída. Exemplo:

fAliplayer.prepare();

Iniciar a reprodução

Use o método play para iniciar a reprodução. Exemplo:

 fAliplayer.play();

Iniciar a reprodução a partir de um momento específico

Use o método seek para saltar para um momento específico. Isso é útil para arrastar a barra de progresso ou retomar a reprodução de uma posição salva. Exemplo:

// position is the specified time in milliseconds. Valid values for seekMode: FlutterAvpdef.ACCURATE (accurate seek) and FlutterAvpdef.INACCURATE (inaccurate seek).
fAliplayer.seek(position,seekMode);

Para iniciar a reprodução a partir de uma posição específica, chame este método antes de chamar prepare. Exemplo:

// Set the start time in milliseconds for the next player preparation. This setting is valid only for the immediately following prepare call.
// After prepare is called, this value is automatically reset to zero. If this method is not called again before the next prepare, playback starts normally.
// You can set seekMode to accurate or inaccurate mode.
fAliplayer.setStartTime(time, seekMode);

Pausar a reprodução

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

fAliplayer.pause();

Retomar a reprodução

Use o método play para retomar a reprodução. Exemplo:

fAliplayer.play();

Parar a reprodução

Use o método stop para parar a reprodução. Exemplo:

fAliplayer.stop();

Destruir o player

Destrua a instância do player de forma síncrona ou assíncrona. Exemplo:

// Synchronous destruction. The stop method is automatically called internally.
fAliplayer.destroy();
// Asynchronous destruction. The stop method is automatically called internally.
fAliplayer.releaseAsync();
Nota

A destruição síncrona só retorna após a liberação de todos os recursos do player. Para melhorar a responsividade da UI, prefira a destruição assíncrona. Observe os seguintes pontos:

  1. Não execute outras operações no objeto do player durante a destruição assíncrona.

  2. Não é necessário parar o player manualmente antes de chamar o método de destruição assíncrona, pois ele já inclui um procedimento de parada assíncrono.

Monitorar o status do player

O ApsaraVideo Player SDK for Flutter permite configurar listeners no player para monitorar seu status.

Configurar listeners do player

É possível definir vários listeners para o player.

  1. Para reprodução manual, configure o listener OnPrepared. Isso é necessário porque você precisa chamar o método play dentro do callback OnPrepared para iniciar a reprodução.

  2. Os listeners OnTrackReady e OnError são importantes. Recomendamos configurá-los.

O exemplo a seguir mostra alguns dos listeners disponíveis:

// Preparation is successful.
fAliplayer.setOnPrepard((playerId) {});
// The first frame is displayed.
fAliplayer.setOnRenderingStart((playerId) {});
// The video width and height change.
fAliplayer.setOnVideoSizeChanged((width, height,playerId) {});
// The player status changes.
fAliplayer.setOnStateChanged((newState,playerId) {});
// Loading status.
fAliplayer.setOnLoadingStatusListener(
    loadingBegin: (playerId) {},
    loadingProgress: (percent, netSpeed,playerId) {},
    loadingEnd: (playerId) {});
// Seeking is complete.
fAliplayer.setOnSeekComplete((playerId) {});
// Callback for player event information, including buffer and current playback progress. The information is determined by infoCode, which corresponds to FlutterAvpdef.infoCode.
fAliplayer.setOnInfo((infoCode, extraValue, extraMsg,playerId) {});
// Playback is complete.
fAliplayer.setOnCompletion((playerId) {});
// The stream is ready.
fAliplayer.setOnTrackReady((playerId) {});
// Snapshot result.
fAliplayer.setOnSnapShot((path,playerId) {});
// Error result.
fAliplayer.setOnError((errorCode, errorExtra, errorMsg,playerId) {});
// The stream is switched.
fAliplayer.setOnTrackChanged((value,playerId) {});

Monitorar o status da reprodução

Monitore as alterações no status do player. O callback onStateChanged fornece o status atual. Exemplo:

fAliplayer.setOnStateChanged((newState, playerId) {
  // newState is the playback status.
  switch (newState) {
    case FlutterAvpdef.AVPStatus_AVPStatusIdle: // Idle
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusInitialzed: // Initialization is complete.
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusPrepared: // Preparation is complete.
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusStarted: // Playing.
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusPaused: // Paused.
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusStopped: // Stopped.
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusCompletion: // Playback is complete.
      break;
    case FlutterAvpdef.AVPStatus_AVPStatusError: // An error occurred.
      break;
    default:
  }
});

Definir o modo de exibição

O ApsaraVideo Player SDK for Flutter suporta configurações de exibição como preenchimento, rotação e espelhamento.

Preenchimento

O SDK oferece três modos de preenchimento: aspect fit, aspect fill e scale to fill. Use o método setScalingMode para definir o modo de preenchimento. Exemplo:

// Set the mode to aspect fit. The video is scaled down proportionally to fit within the view without distortion.
fAliplayer.setScalingMode(ScaleMode.SCALE_ASPECT_FIT);
// Set the mode to aspect fill. The video is scaled up proportionally to fill the view without distortion.
fAliplayer.setScalingMode(ScaleMode.SCALE_ASPECT_FILL);
// Set the mode to scale to fill. The video may be distorted if its aspect ratio does not match the view's aspect ratio.
fAliplayer.setScalingMode(ScaleMode.SCALE_TO_FILL);

Rotação

Use o método setRotateMode para girar o vídeo em um ângulo especificado. Também é possível recuperar o ângulo de rotação após defini-lo. Exemplo:

// Rotate the video 0 degrees clockwise.
fAliplayer.setRotateMode(RotateMode.ROTATE_0);
// Rotate the video 90 degrees clockwise.
fAliplayer.setRotateMode(RotateMode.ROTATE_90);
// Rotate the video 180 degrees clockwise.
fAliplayer.setRotateMode(RotateMode.ROTATE_180);
// Rotate the video 270 degrees clockwise.
fAliplayer.setRotateMode(RotateMode.ROTATE_270);
// Get the rotation angle.
fAliplayer.getRotateMode();

Espelhamento

O SDK suporta espelhamento horizontal, vertical ou nenhum espelhamento. Use o método setMirrorMode para configurar o espelhamento. Exemplo:

// Set no mirroring.
fAliplayer.setMirrorMode(MirrorMode.MIRROR_MODE_NONE);
// Set horizontal mirroring.
fAliplayer.setMirrorMode(MirrorMode.MIRROR_MODE_HORIZONTAL);
// Set vertical mirroring.
fAliplayer.setMirrorMode(MirrorMode.MIRROR_MODE_VERTICAL);

Obter informações de reprodução

Recupere o progresso atual da reprodução e a duração do vídeo usando o ApsaraVideo Player SDK for Flutter.

Obter o progresso atual da reprodução

Obtenha o tempo atual de reprodução em milissegundos pelo callback onInfo. Exemplo:

fAliplayer.setOnInfo((infoCode,extraValue,extraMsg,playerId){
 if(infoCode==FlutterAvpdef.CURRENTPOSITION){
 // extraValue is the current playback progress.
}
});

Obter a duração do vídeo

Obtenha a duração total do vídeo após o carregamento, por exemplo, após o evento AVPEventPrepareDone. Exemplo:

fAliplayer.getMediaInfo().then((value){
 _videoDuration=value['duration'];
});

Definir o volume

As configurações de volume incluem ajuste de nível e silenciamento.

Ajuste de volume

Ajuste o volume usando o método setVolume. O intervalo suportado é de 0 a 2. Valores maiores que 1 não são recomendados, pois podem causar ruído. Exemplo:

// The value of volume is a real number from 0 to 2.
fAliPlayer.setVolume(1);
// Get the volume information.
fAliPlayer.getVolume();

Configurações de mudo

Use o método setMute para silenciar o player. Exemplo:

fAliplayer.setMute(true);

Alterar a velocidade de reprodução

O ApsaraVideo Player SDK for Flutter permite alterar a velocidade de reprodução. Use o método setSpeed para reproduzir de 0,5x a 5x a velocidade normal. O tom do áudio permanece inalterado. Exemplo:

// Set the playback speed. Speeds from 0.5x to 5x are supported. The speed is usually set in multiples of 0.5, such as 0.5x, 1x, and 1.5x.
fAliplayer.setSpeed(1.0);

Configurações de multidefinição

Se você usar um método baseado em VID (VidAuth ou VidSts) para reprodução, nenhuma configuração extra será necessária. O SDK recupera a lista de definições do ApsaraVideo VOD automaticamente. É possível recuperar e trocar as definições. Essa configuração não é suportada para reprodução via UrlSource.

Recuperar a definição

Após o carregamento do vídeo, recupere sua definição.

fAliplayer.setOnPrepared((playerId) {
  fAliplayer.getMediaInfo().then((value){
        AVPMediaInfoinfo info=AVPMediaInfo.fromJson(value);
        info.tracks.forEach((element){
          if(element.trackType==3){
            // Definition
            String definition=element.trackDefinition;
            // Stream index
            int index=element.trackIndex;
          }
        });
      });    
});

Trocar a definição

Use o método selectTrack para trocar a definição. Passe o índice do TrackInfo correspondente.

fAliplayer.selectTrack(trackIdx);

Notificação de troca de definição

Este callback é acionado após uma troca de definição bem-sucedida.

fAliplayer.setOnTrackChanged((value,playerId){
 // A callback indicates that the switch is successful. A method for a failed switch is not yet available.
});

Reprodução em loop

O ApsaraVideo Player SDK for Flutter oferece reprodução em loop. Chame setLoop para ativar esse recurso. Quando o vídeo terminar, ele reiniciará automaticamente do começo. Exemplo:

fAliplayer.setLoop(true);

O callback de início do loop envia notificações por meio de onInfo. Exemplo:

fAliplayer.setOnInfo((infoCode, extraValue, extraMsg, playerId) {
 if(infoCode == FlutterAvpdef.LOOPINGSTART){
 // Loop playback start notification
 }
});

Obter logs de reprodução

O ApsaraVideo Player SDK for Flutter permite obter logs de reprodução. Chame enableConsoleLog para ativar a impressão de logs. Exemplo:

// Enable log printing.
FlutterAliplayer.enableConsoleLog(true);
// Set the log level. The default level is AF_LOG_LEVEL_INFO. To troubleshoot issues, you can set it to AF_LOG_LEVEL_TRACE.
FlutterAliplayer.setLogLevel(FlutterAvpdef.AF_LOG_LEVEL_INFO);

O ApsaraVideo Player SDK for Flutter também permite obter logs no nível de quadro. Chame setLogOption para configurar a impressão de logs nesse nível. Exemplo:

/// Set the log level. To troubleshoot issues, set the log level to AF_LOG_LEVEL_TRACE.
FlutterAliplayer.setLogLevel(LogLevel.AF_LOG_LEVEL_INFO);
/// Enable or disable logs.
FlutterAliplayer.enableConsoleLog(true);
/// Log callback information.
FlutterAliplayer.setLogInfoCallBack((level, msg) {
   print("[LOG][LEVEL][$level] $msg");
});
/// Enable the frame log callback. This is typically enabled for troubleshooting.
/// Option value: 0 means disabled, 1 means enabled.
FlutterAliplayer.setLogOption(value);
Nota

O recurso de log no nível de quadro é usado principalmente para solução de problemas.