ApsaraVideo VOD:Basic features of ApsaraVideo Player SDK for iOS

Prepare a reprodução

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

[self.player prepare];

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

Inicie a reprodução

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

[self.player start];

Pause a reprodução

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

[self.player pause];

Retome a reprodução

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

[self.player start];

Busque uma posição específica

Chame seekToTime para saltar para uma posição específica. Esse método é útil quando o usuário arrasta a barra de progresso ou retoma a reprodução a partir de uma posição salva.

// 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): Busca a posição exata. É mais lenta, porém mais precisa.

• Busca imprecisa (AVP_SEEKMODE_INACCURATE): Busca o keyframe mais próximo. É mais rápida, porém menos precisa.

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

Para iniciar a reprodução a partir de 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];

Pare a reprodução

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

[self.player stop];

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

Destrua 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 respostas mais rápidas na interface do usuário.

• Não execute nenhuma operação 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.

Defina o delegate do player

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

Importante: Implemente os callbacks onError e onPlayerEvent para lidar com 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.
}

Monitore as alterações de estado do player

O callback onPlayerStatusChanged é acionado quando 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 oferece suporte a 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

Gire o vídeo no sentido horário em 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 oferece suporte a 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 o carregamento (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 carregando o 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 taxa de bits em tempo real

Obtenha a taxa de quadros de renderização, a taxa de bits de áudio e vídeo e a taxa de bits de recebimento 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]

Ajuste o volume

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

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

Silencie o vídeo

Silencie ou reative o áudio:

self.player.muted = YES;

Reprodução baseada em VidAuth ou VidSts

Ao usar VidAuth ou VidSts para reprodução VOD, o SDK recupera automaticamente as resoluçõ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];

Transmissão ao vivo baseada em UrlSource

Para obter detalhes, consulte Standard live stream playback.

Tipos de stream compatíveis

Os seguintes tipos de stream são compatíveis com a troca de faixas de áudio. O comportamento de troca varia de acordo com o tipo de stream.

Obtenha as faixas de áudio disponíveis

O callback onSubTrackReady é acionado quando as informações da faixa 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.
    }
}

Troque a faixa de áudio

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

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

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

Este método é adequado para cenários em que é possível reproduzir o problema localmente.

1. Ative os logs 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 os logs 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

   Os logs no nível de quadro geram um grande volume de logs e são usados principalmente para solucionar problemas de reprodução.

3. Colete os logs:

   Opção A: Visualize os logs no console

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

   Opção B: Grave os logs em um arquivo

   Defina o caminho completo para o seu arquivo de log dentro da 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 na sandbox do aplicativo:

   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: Defina o 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 logs para o canal de logs do seu aplicativo.

1. Ative os logs 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 logs do seu aplicativo.

Solução de problemas

Referências

• Advanced features: Conheça recursos avançados como Picture-in-Picture (PiP), time shifting e streaming de taxa de bits adaptável.

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

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