ApsaraVideo VOD:Fonctionnalités de base du SDK ApsaraVideo Player pour iOS

Préparer la lecture

Appelez la méthode prepare pour préparer la vidéo à la lecture.

[self.player prepare];

Le rappel onPlayerEvent avec AVPEventPrepareDone est invoqué lorsque la préparation est terminée.

Démarrer la lecture

Appelez la méthode start pour commencer à lire la vidéo :

[self.player start];

Mettre la lecture en pause

Appelez la méthode pause pour mettre la vidéo en pause :

[self.player pause];

Reprendre la lecture

Appelez la méthode start pour reprendre la lecture après une pause :

[self.player start];

Accéder à une position spécifique

Appelez seekToTime pour accéder à une position spécifique. Cette méthode est utile lorsque les utilisateurs font glisser la barre de progression ou reprennent la lecture à partir d'une position enregistrée.

// 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];

Modes de recherche :

• Recherche précise (AVP_SEEKMODE_ACCURATE) : Accède à la position exacte. Plus lent, mais plus précis.

• Recherche imprécise (AVP_SEEKMODE_INACCURATE) : Accède à l'image clé la plus proche. Plus rapide, mais moins précis.

Démarrer la lecture à partir d'une position spécifique

Pour démarrer la lecture à partir d'une position spécifique (plutôt que de rechercher pendant la lecture), appelez setStartTime avant d'appeler 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];

Arrêter la lecture

Appelez la méthode stop pour arrêter la lecture :

[self.player stop];

Dissocier la vue du lecteur

Après avoir arrêté la lecture et avant de détruire l'instance du lecteur, dissociez la vue du lecteur pour libérer les ressources de rendu et éviter les fuites de mémoire.

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

Détruire le lecteur

Vous pouvez détruire le lecteur de manière synchrone ou asynchrone pour libérer les ressources.

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

Recommandations :

• Utilisez destroyAsync si vous avez besoin de temps de réponse rapides.

• N'effectuez aucune opération sur l'objet lecteur pendant la destruction asynchrone.

• Il n'est pas nécessaire d'appeler stop avant destroyAsync car le processus de destruction inclut une opération d'arrêt asynchrone.

Définir le délégué du lecteur

Implémentez le protocole AVPDelegate dans votre contrôleur de vue pour recevoir les rappels du lecteur.

Important : Implémentez les rappels onError et onPlayerEvent pour gérer les erreurs et surveiller les changements d'état de la lecture.

@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.
}

Écouter les changements d'état du lecteur

Le rappel onPlayerStatusChanged est invoqué lorsque l'état du lecteur change :

- (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;
    }
}

Modes de mise à l'échelle

Le SDK prend en charge trois modes de mise à l'échelle :

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

Rotation

Faites pivoter la vidéo dans le sens horaire selon un angle spécifié :

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

Mise en miroir

Appelez setMirrorMode pour mettre la vidéo en miroir. Le SDK prend en charge la mise en miroir horizontale et verticale :

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

Progression de la lecture

La position de lecture actuelle est renvoyée dans le rappel onCurrentPositionUpdate :

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

Durée totale

Récupérez la durée totale de la vidéo après son chargement (par exemple, après l'événement 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;
  }
}

Durée de lecture réelle

Récupérez la durée de lecture réelle en temps réel. Cette valeur exclut le temps pendant lequel la lecture est en pause ou en cours de mise en mémoire tampon.

 NSString *duration = [player getPlayedDuration];

Progression de la mise en mémoire tampon

La progression actuelle de la mise en mémoire tampon est renvoyée dans le rappel onBufferedPositionUpdate :

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

Métriques de rendu et de débit en temps réel

Obtenez le taux de rafraîchissement du rendu, le débit audio et vidéo, ainsi que le débit descendant du réseau en temps réel.

// 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]

Ajuster le volume

Appelez volume pour modifier le volume. Valeurs valides : de 0 à 2, où 1 correspond au volume d'origine. Les valeurs supérieures à 1 amplifient l'audio et peuvent introduire du bruit. Nous vous recommandons de maintenir le volume à 1 ou en dessous.

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

Couper le son de la vidéo

Coupez ou rétablissez le son :

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;

Lecture basée sur VidAuth ou VidSts

Si vous utilisez VidAuth ou VidSts pour la lecture VOD, le SDK récupère automatiquement les définitions vidéo depuis ApsaraVideo VOD. Aucune configuration supplémentaire n'est requise.

- (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];

Diffusion en direct basée sur UrlSource

Pour plus de détails, consultez la rubrique Lecture standard de flux en direct.

self.player.loop = YES;

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

Types de flux pris en charge

Les types de flux suivants prennent en charge le changement de piste audio. Le comportement de basculement varie selon le type de flux.

Obtenir les pistes audio disponibles

Le rappel onSubTrackReady est invoqué lorsque les informations sur les pistes audio sont disponibles :

  // 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.
    }
}

Changer de piste audio

Appelez la méthode selectTrack pour basculer vers une autre piste audio :

[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éthode 1 : Afficher les journaux dans la console de l'outil de développement

Cette méthode convient aux scénarios où vous pouvez reproduire le problème localement.

1. Activez la journalisation et définissez le niveau de journalisation :

   // 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. Activez la journalisation au niveau des images (facultatif) :

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

   Remarque

   La journalisation au niveau des images génère un grand volume de journaux et est principalement utilisée pour le dépannage des problèmes de lecture.

3. Collectez les journaux :

   Option A : Afficher les journaux dans la console

   Après avoir reproduit le problème, récupérez les journaux depuis la console de votre outil de développement, tel que XCode.

   Option B : Écrire les journaux dans un fichier

   Définissez le chemin complet de votre fichier journal dans le sandbox de l'application.

   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"];

   Redirigez les journaux vers un fichier personnalisé dans le sandbox de l'application :

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

   Après avoir reproduit le problème, récupérez le fichier .log depuis le répertoire personnalisé.

Méthode 2 : Définir LogCallback pour recevoir les journaux par programmation

Utilisez cette méthode lorsque vous ne pouvez pas reproduire le problème de manière fiable sur votre appareil. Le rappel exporte les journaux vers le canal de journalisation de votre application.

1. Activez la journalisation et définissez le niveau de journalisation.

   // 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. Collectez les journaux :

   Après avoir reproduit le problème, les journaux sont automatiquement transférés vers le système de journalisation de votre application.

Dépannage

Références

• Fonctionnalités avancées : Découvrez des fonctionnalités avancées telles que Picture-in-Picture (PiP), le décalage temporel et la diffusion adaptative.

• API : Explorez la référence API complète du SDK ApsaraVideo Player pour iOS.

• Codes d'erreur mobiles : Consultez cette rubrique pour le dépannage.