ApsaraVideo VOD:Basic features of ApsaraVideo Player SDK for iOS

Preparar a reprodução

Chame o método prepare para preparar o vídeo para reprodução.

[self.player prepare];

O callback onPlayerEvent com o evento AVPEventPrepareDone é invocado quando a preparação é concluída.

Iniciar a reprodução

Chame o método start para começar a reproduzir o vídeo:

[self.player start];

Pausar a reprodução

Chame o método pause para pausar o vídeo:

[self.player pause];

Retomar a reprodução

Chame o método start para retomar a reprodução após uma pausa:

[self.player start];

Buscar uma posição específica

Use seekToTime para saltar para uma posição específica. Este método é útil quando o usuário arrasta a barra de progresso ou retoma a reprodução de um ponto salvo.

// Seek to a specific position (in milliseconds)
// Accurate seek
[self.player seekToTime:position seekMode:AVP_SEEKMODE_ACCURATE];
// Inaccurate seek
[self.player seekToTime:position seekMode:AVP_SEEKMODE_INACCURATE];

Modos de busca:

• Busca precisa (AVP_SEEKMODE_ACCURATE): Salta para a posição exata. É mais lenta, porém mais precisa.

• Busca aproximada (AVP_SEEKMODE_INACCURATE): Salta para o keyframe mais próximo. É mais rápida, mas menos precisa.

Iniciar a reprodução a partir de uma posição específica

Para começar a reproduzir o vídeo já em uma posição específica (em vez de buscar durante a reprodução), chame setStartTime antes de chamar prepare:

// Set the start time for the next prepare call (in milliseconds).
// This setting is only valid for the immediately following prepare call. The start time is automatically cleared after prepare is called.
// seekMode: accurate seek (AVP_SEEKMODE_ACCURATE) or inaccurate seek (AVP_SEEKMODE_INACCURATE).
[self.player setStartTime:time seekMode:seekMode];

Parar a reprodução

Chame o método stop para interromper a reprodução:

[self.player stop];

Desvincular a visualização do player

Após parar a reprodução e antes de destruir a instância do player, desvincule a visualização do player para liberar recursos de renderização e evitar vazamentos de memória.

// Unbind the player view
self.player.playerView = nil;

Destruir o player

Destrua o player de forma síncrona ou assíncrona para liberar recursos.

// Synchronous destroy. Blocks until player resources are released. Automatically calls stop.
[self.player destroy];
// Asynchronous destroy. Returns immediately. Automatically calls stop.
[self.player destroyAsync];

Recomendações:

• Use destroyAsync se precisar de tempos de resposta rápidos na interface.

• Não realize operações no objeto do player durante a destruição assíncrona.

• Não é necessário chamar stop antes de destroyAsync, pois o processo de destruição inclui uma operação de parada assíncrona.

Definir o delegate do player

Implemente o protocolo AVPDelegate no seu view controller para receber os callbacks do player.

Importante: Implemente os callbacks onError e onPlayerEvent para tratar erros e monitorar alterações no estado da reprodução.

@interface SimplePlayerViewController ()<AVPDelegate>
@end
- (void)viewDidLoad {
    self.player = [[AliPlayer alloc] init];
    self.player.playerView = self.avpPlayerView.playerView;
    self.player.delegate = self;
    //...
}
/**
 @brief Delegate callback for player errors.
 @param player The player instance.
 @param errorModel Contains the error details.
 */
- (void)onError:(AliPlayer*)player errorModel:(AVPErrorModel *)errorModel {
    // Handle the error (e.g., show an alert) and stop playback.
}
/**
 @brief Delegate callback for player events.
 @param player The player instance.
 @param eventType The type of the event. See AVPEventType.
 */
-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType{
    switch(eventType){
        case AVPEventPrepareDone:{
            // Triggered when the media has been prepared and is ready to play.
        }
            break;
        case AVPEventAutoPlayStart:
            // Triggered when autoplay begins.
            break;
        case AVPEventFirstRenderedStart:
            // Triggered when the first frame is rendered.
            break;
        case AVPEventCompletion:
            // Triggered when playback completes.
            break;
        case AVPEventLoadingStart:
            // Triggered when buffering starts.
            break;
        case AVPEventLoadingEnd:
            // Triggered when buffering finishes.
            break;
        case AVPEventSeekEnd:
            // Triggered when a seek operation completes.
            break;
        case AVPEventLoopingStart:
            // Triggered when a new loop begins.
            break;
        default:
            break;
    }
}
/**
 @brief Callback for the current playback position.
 @param player The player instance.
 @param position The current playback position in milliseconds.
 */
- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Update the progress bar.
}
/**
 @brief Callback for the current buffered position.
 @param player The player instance.
 @param position The current buffered position in milliseconds.
 */
- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Update the buffer progress indicator.
}
/**
 @brief Callback for when track information is ready.
 @param player The player instance.
 @param info An array of AVPTrackInfo objects for the available streams.
 */
- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // Retrieve information for available bitrates/tracks.
}
/**
 @brief Callback for when a subtitle should be displayed.
 @param player The player instance.
 @param index The index of the subtitle entry.
 @param subtitle The subtitle text to be displayed.
 */
- (void)onSubtitleShow:(AliPlayer*)player index:(int)index subtitle:(NSString *)subtitle {
    // Get and display the subtitle text.
}
/**
 @brief Callback for when a subtitle should be hidden.
 @param player The player instance.
 @param index The index of the subtitle entry that was shown.
 */
- (void)onSubtitleHide:(AliPlayer*)player index:(int)index {
    // Hide the subtitle.
}
/**
 @brief Callback for a screen capture request.
 @param player The player instance.
 @param image The captured screenshot as a UIImage.
 */
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // Preview or save the captured image.
}
/**
 @brief Callback for when a track change is complete.
 @param player The player instance.
 @param info The AVPTrackInfo object for the new, active track.
 */
- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
    // Notification that the bitrate/track has changed.
}

Monitorar mudanças de estado do player

O callback onPlayerStatusChanged é invocado sempre que o estado do player muda:

- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
    switch (newStatus) {
    case AVPStatusIdle:{
           // Player is idle
        }
 break;
        case AVPStatusInitialzed:{
           // Player is initialized
        }
 break;
        case AVPStatusPrepared:{
           // Player prepared
        }
 break;
        case AVPStatusStarted:{
           // Playback started
        }
 break;
case AVPStatusPaused:{
           // Playback paused
        }
 break;
case AVPStatusStopped:{
           // Playback stopped
        }
 break;
case AVPStatusCompletion:{
           // Playback completed
        }
 break;
case AVPStatusError:{
           // Player error occurred
        }
 break;
        default:
            break;
    }
}

Modos de dimensionamento

O SDK suporta três modos de dimensionamento:

// Scale to fit the view while maintaining the aspect ratio (letterboxing).
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFIT;
// Scale to fill the view while maintaining the aspect ratio (cropping).
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFILL;
// Stretch to fill the view. The aspect ratio is not maintained. Image distortion may occur.
self.player.scalingMode = AVP_SCALINGMODE_SCALETOFILL;

Rotação

Rotacione o vídeo no sentido horário por um ângulo especificado:

// No rotation
self.player.rotateMode = AVP_ROTATE_0;
// Rotate 90 degrees clockwise
self.player.rotateMode = AVP_ROTATE_90;
// Rotate 180 degrees clockwise
self.player.rotateMode = AVP_ROTATE_180;
// Rotate 270 degrees clockwise
self.player.rotateMode = AVP_ROTATE_270;

Espelhamento

Chame setMirrorMode para espelhar o vídeo. O SDK suporta espelhamento horizontal e vertical:

// No mirroring
self.player.mirrorMode = AVP_MIRRORMODE_NONE;
// Horizontal mirroring
self.player.mirrorMode = AVP_MIRRORMODE_HORIZONTAL;
// Vertical mirroring
self.player.mirrorMode = AVP_MIRRORMODE_VERTICAL;

Progresso da reprodução

A posição atual da reprodução é retornada no callback onCurrentPositionUpdate:

- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
// position is in milliseconds
NSString *position = [NSString stringWithFormat:@"%lld, position"];
}

Duração total

Recupere a duração total do vídeo após ele ser carregado (por exemplo, após o evento AVPEventPrepareDone):

-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
  switch (eventType) {
    case AVPEventPrepareDone: {
      if (self.player.duration >= 0) {
       NSString *duration  = self.player.duration;
      }
    }
      break;
    default:
      break;
  }
}

Duração real da reprodução

Recupere a duração real da reprodução em tempo real. Este valor exclui o tempo em que a reprodução está pausada ou em buffer.

 NSString *duration = [player getPlayedDuration];

Progresso do buffer

O progresso atual do buffer é retornado no callback onBufferedPositionUpdate:

- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    NSString *bufferPosition = position;
}

Métricas de renderização e bitrate em tempo real

Obtenha a taxa de quadros de renderização, bitrate de áudio e vídeo e bitrate de download da rede em tempo real.

// Video rendering frame rate. Returns a float value.
[self.player getOption:AVP_OPTION_RENDER_FPS]
// Video bitrate. Returns a float value in bit/s.
[self.player getOption:AVP_OPTION_VIDEO_BITRATE]
// Audio bitrate. Returns a float value in bit/s.
[self.player getOption:AVP_OPTION_AUDIO_BITRATE]
// Network downstream bitrate. Returns a float value in bit/s.
[self.player getOption:AVP_OPTION_DOWNLOAD_BITRATE]

Ajustar o volume

Use volume para alterar o volume. Valores válidos: de 0 a 2, onde 1 representa o volume original. Valores maiores que 1 amplificam o áudio e podem introduzir ruído. Recomendamos manter o volume igual ou inferior a 1.

// Set the volume. Valid values: 0 to 2.
self.player.volume = 1.0f;
// Get the current volume.
self.player.volume

Silenciar o vídeo

Ative ou desative o som do áudio:

self.player.muted = YES;

// We recommend using multiples of 0.5 (e.g., 0.5, 1.0, 1.5, 2.0)
self.player.rate = 1.0f;

Reprodução baseada em VidAuth ou VidSts

Ao usar VidAuth ou VidSts para reprodução VOD, o SDK recupera automaticamente as definições de vídeo do ApsaraVideo VOD. Nenhuma configuração adicional é necessária.

- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    for (int i=0; i<info.count; i++) {
        AVPTrackInfo* track = [info objectAtIndex:i];
        switch (track.trackType) {
            case AVPTRACK_TYPE_VIDEO: {
                int trackBitrate = track.trackBitrate;
            }
                break;
        }
    }
}

[self.player selectTrack:index];

- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
 // Definition switched.
}

AVPConfig *config = [self.player getConfig];
config.selectTrackBufferMode = 1;
[self.player setConfig:config];

Streaming ao vivo baseado em UrlSource

Para mais detalhes, consulte Standard live stream playback.

self.player.loop = YES;

- (void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventLoopingStart:
            break;
    }
}

Tipos de stream suportados

Os seguintes tipos de stream suportam a troca de faixas de áudio. O comportamento da troca varia conforme o tipo de stream.

Obter faixas de áudio disponíveis

O callback onSubTrackReady é invocado quando as informações das faixas de áudio estão disponíveis:

  // onSubTrackReady. Typically triggered before the AVPEventPrepareDone event.
- (void)onSubTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // Call getSubMediaInfo after this callback is triggered. Calling it before this callback returns an empty result.
    AVPMediaInfo* subMediaInfo = [player getSubMediaInfo];
    // Iterate through available audio tracks
    for (int i=0; i<subMediaInfo.tracks.count; i++) {
    	AVPTrackInfo* track = [mediaInfo.tracks objectAtIndex:i];
        // Find the target audio track from the track list.
    }
}

Alternar a faixa de áudio

Chame o método selectTrack para mudar para uma faixa de áudio diferente:

[self.player selectTrack:myTrack.trackIndex accurate:YES]

/**
 A flag indicating whether the current track has thumbnails. If false, thumbnail previews will not be displayed during seeking.
 */
@property (nonatomic,assign)BOOL trackHasThumbnai;

/**
 The custom UIImageView used to display the thumbnail preview image.
 */
@property (nonatomic,strong)UIImageView *thumbnaiView;

/**
  onPrepare
 */
- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
  if(newStatus == AVPStatusPrepared){
       [self.player setThumbnailUrl:[URL];// When the player is prepared, set the thumbnail URL.
       self.trackHasThumbnai = YES;
  }
}
/**
 Callback triggered when the progress slider's value changes.
 @param playerView The player view instance.
 @param value The new progress value.
 */
- (void)AVPPlayerView:(AVPPlayerView *)playerView progressSliderValueChanged:(CGFloat)value {
    if (self.trackHasThumbnai) {
        [self.player getThumbnail:self.player.duration*value];
    }
}

/**
 @brief: Callback triggered upon successful retrieval of a thumbnail.
 @param positionMs: The requested time position for the thumbnail, in milliseconds.
 @param fromPos: The start time of the segment this thumbnail represents, in milliseconds.
 @param toPos: The end time of the segment this thumbnail represents, in milliseconds.
 @param image: The retrieved thumbnail image (`UIImage` on iOS, `NSImage` on macOS).
 */
- (void)onGetThumbnailSuc:(int64_t)positionMs fromPos:(int64_t)fromPos toPos:(int64_t)toPos image:(id)image {
    self.thumbnaiView.hidden = NO;
    [self.thumbnaiView setImage:(UIImage *)image];
}

/**
 @brief: Callback triggered when thumbnail retrieval fails.
 @param positionMs: The time position for which the thumbnail request failed, in milliseconds.
 */
- (void)onGetThumbnailFailed:(int64_t)positionMs {
    self.thumbnaiView.hidden = YES;
}

Método 1: Visualizar logs no console da ferramenta de desenvolvimento

Este método é adequado para cenários onde você consegue reproduzir o problema localmente.

1. Ative o log e defina o nível de log:

   // Enable SDK logging
   [AliPlayer setEnableLog:YES];
   // Set the log level (default: LOG_LEVEL_INFO). Use LOG_LEVEL_TRACE for detailed troubleshooting.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:nil];

2. Ative o log no nível de quadro (opcional):

   // Enable frame-level logging for detailed troubleshooting
   // 0 = disabled, 1 = enabled
   [AliPlayer setLogOption:FRAME_LEVEL_LOGGING_ENABLED value:value];

   Nota

   O log no nível de quadro gera um grande volume de dados e é usado principalmente para solucionar problemas de reprodução.

3. Colete os logs:

   Opção A: Visualizar logs no console

   Após reproduzir o problema, recupere os logs do console da sua ferramenta de desenvolvimento, como o XCode.

   Opção B: Gravar logs em um arquivo

   Defina o caminho completo para o seu arquivo de log dentro do sandbox do aplicativo.

   NSArray *paths =NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,NSUserDomainMask, YES);
   NSString *documentDirectory = [paths objectAtIndex:0];
   // Define your custom log file path. For example, create a file named 'xxxx.log'.
   NSString *logFilePath = [documentDirectory stringByAppendingPathComponent:@"xxxx.log"];

   Redirecione os logs para um arquivo personalizado no sandbox do app:

   freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stdout);
   freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stderr);

   Após reproduzir o problema, recupere o arquivo .log do diretório personalizado.

Método 2: Definir LogCallback para receber logs programaticamente

Use este método quando não for possível reproduzir o problema de forma confiável no seu dispositivo. O callback exporta os logs para o canal de log da sua aplicação.

1. Ative o log e defina o nível de log.

   // Enable SDK logging
   [AliPlayer setEnableLog:YES];
   // Set the log level. Default value: LOG_LEVEL_INFO. For troubleshooting, set it to LOG_LEVEL_TRACE.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:^(AVPLogLevel logLevel, NSString *strLog) {
    NSLog(@"strLog:%@", strLog);
   }];

2. Colete os logs:

   Após reproduzir o problema, os logs são encaminhados automaticamente para o sistema de log do seu app.

Solução de problemas

Referências

• Advanced features: Conheça recursos avançados como Picture-in-Picture (PiP), time shifting e streaming de bitrate adaptativo.

• API: Explore a referência completa da API do ApsaraVideo Player SDK para iOS.

• Mobile error codes: Consulte este tópico para solução de problemas.