Types de scénarios AliPlayerKit iOS - ApsaraVideo VOD - Centre de documentation Alibaba Cloud

Introduction

Qu'est-ce que SceneType ?

SceneType est une énumération qui spécifie le scénario métier actuel du lecteur. Lorsque vous définissez le SceneType, AliPlayerKit :

Ajuste la visibilité des emplacements, par exemple en masquant la vignette dans un scénario de diffusion en direct.
Filtre les gestes, par exemple en désactivant la recherche de progression et l'ajustement de la vitesse de lecture dans les scénarios en direct ou restreints, ou en désactivant les gestes verticaux dans les scénarios de liste de vidéos.
S'adapte aux limitations des fonctionnalités, par exemple en garantissant que les utilisateurs regardent le contenu dans son intégralité et dans l'ordre dans un scénario restreint.

En définissant simplement une valeur d'énumération, le framework gère automatiquement ces adaptations. Cela réduit considérablement l'effort nécessaire pour personnaliser le lecteur pour différents scénarios métier.

Valeur principale

Valeur

Description

Adaptation sans configuration

Après la définition d'un scénario, l'interface utilisateur et les comportements interactifs s'ajustent automatiquement. Il n'est pas nécessaire de configurer chaque emplacement et geste individuellement.

Garantie de cohérence

Toutes les instances de lecteur dans le même scénario maintiennent une interface utilisateur et un comportement interactif cohérents.

Réduction des coûts de personnalisation

Remplacez des dizaines de lignes de code relatives à la visibilité des emplacements et au filtrage des gestes par une seule ligne de code.

Évolutivité

Ajustez finement à l'aide de SlotConfig et GestureControlSlotConfig.

Fonctionnalités

Aperçu des scénarios

AliPlayerKit intègre cinq types de scénarios qui couvrent la plupart des besoins de lecture :

Scénario

Valeur d'énumération

Description

Activité concernée

Différences par rapport à la VOD

VOD

SceneTypeVOD

Scénario par défaut. Prend en charge toutes les capacités de contrôle.

VOD standard, cours, bibliothèque multimédia

—

Live

SceneTypeLive

Flux en temps réel sans durée fixe. Les opérations sur la timeline sont automatiquement désactivées.

Diffusion en direct, événements sportifs, live commerce

Désactive la recherche de progression et l'ajustement de la vitesse de lecture. Masque la vignette.

Liste de vidéos

SceneTypeVideoList

Désactive les gestes verticaux pour éviter les conflits avec le défilement de la liste.

Fils d'actualité, listes de courtes vidéos

Désactive les gestes verticaux pour le volume et la luminosité.

Lecture restreinte

SceneTypeRestricted

Empêche le saut pour garantir que les utilisateurs regardent la vidéo dans son intégralité.

Surveillance d'examens, cours de formation

Désactive la recherche de progression et l'ajustement de la vitesse de lecture. Masque la vignette.

Minimal

SceneTypeMinimal

Interface épurée. Tous les contrôles doivent être implémentés séparément.

Lecture en arrière-plan, interface utilisateur entièrement personnalisée

Masque tous les composants de contrôle et les gestes.

Définition de l'énumération

// SceneType.h
typedef NS_ENUM(NSInteger, SceneType) {
    /** VOD scenario (default) */
    SceneTypeVOD = 0,

    /** Live streaming scenario */
    SceneTypeLive = 1,

    /** Video list or short video stream scenario */
    SceneTypeVideoList = 2,

    /** Restricted playback scenario */
    SceneTypeRestricted = 3,

    /** Minimal playback page scenario */
    SceneTypeMinimal = 4,
};

Matrice des capacités des scénarios

Visibilité des emplacements

Le système d'emplacements contrôle automatiquement la visibilité des composants en fonction du type de scénario. La matrice suivante présente les règles par défaut issues de DefaultSlotFactory.defaultConfigs :

Emplacement

VOD

Live

VideoList

Restricted

Minimal

PlayerSurface

✓

GestureControl

✓

✗

LandscapeHint

✓

✗

Cover

✓

✗

✓

✗

CenterDisplay

✓

✗

PlayState

✓

LogPanel

✓

✗

TopBar

✓

✗

BottomBar

✓

✗

SettingMenu

✓

✗

OptionPanel

✓

✗

Descriptions des règles de visibilité :

PlayerSurface et PlayState : Visibles dans tous les scénarios (aucune configuration excludedScenes).
Cover : Non visible dans les scénarios Live, Restricted ou Minimal.
Autres emplacements (GestureControl, LandscapeHint, CenterDisplay, LogPanel, TopBar, BottomBar, SettingMenu, OptionPanel) : Non visibles uniquement dans le scénario Minimal.

Différences de comportement des gestes

L'emplacement GestureControlSlot filtre en interne les gestes dans chaque méthode de gestion en fonction du currentSceneType :

Geste

VOD

Live

VideoList

Restricted

Minimal

Clic (Afficher/Masquer la barre de contrôle)

✓

✗

Double-clic (Lecture/Pause)

✓

✗

Appui long (Avance rapide)

✓

✗

✓

✗

Glissement horizontal (Recherche de progression)

✓

✗

✓

✗

Glissement vertical gauche (Luminosité)

✓

✗

✓

✗

Glissement vertical droit (Volume)

✓

✗

✓

✗

Descriptions de la logique de filtrage :

Minimal : Toutes les méthodes de gestion des gestes (handleSingleTap:, handleDoubleTap:, handleLongPress: et handlePan:) effectuent un return immédiat dès l'entrée.
Live / Restricted : L'appui long et le glissement horizontal sont désactivés. Cette vérification est effectuée dans handleLongPress: et tryStartDragWithCurrentPoint:.
VideoList : Le glissement vertical est désactivé. La méthode tryStartDragWithCurrentPoint: effectue un return immédiat lorsqu'elle détecte SceneTypeVideoList.

Utilisation

Utilisation de base

Spécifiez le type de scénario à l'aide de la propriété AliPlayerModel.sceneType. La valeur par défaut est SceneTypeVOD, qu'il n'est pas nécessaire de définir explicitement.

Scénario VOD (par défaut, aucune configuration requise) :

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
// model.sceneType defaults to SceneTypeVOD, no setup required

[controller configure:model];

Scénario de diffusion en direct :

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://live.example.com/stream.m3u8"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeLive;
model.videoTitle = @"Live Channel";

[controller configure:model];

Scénario de liste de vidéos :

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://live.example.com/stream.m3u8"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeLive;
model.videoTitle = @"live channel";

[controller configure:model];

Description détaillée de chaque scénario

VOD - Scénario VOD (par défaut)

Scénarios : Lecture vidéo standard, cours en ligne, navigation dans la bibliothèque multimédia, etc.

Capacités :

Prend en charge les 11 emplacements par défaut
Prend en charge les 6 gestes
Prend en charge la recherche de progression, l'ajustement de la vitesse de lecture et le changement de résolution
Prend en charge le basculement en plein écran

// No need to explicitly specify SceneType, the default is VOD
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.coverUrl = @"https://example.com/cover.jpg";
model.videoTitle = @"Great Video";
model.autoPlay = YES;

[controller configure:model];

Live - Scénario de diffusion en direct

Scénarios : Diffusion en direct en temps réel, événements sportifs en direct, live commerce, etc.

Principales différences par rapport à la VOD :

Désactivé : La recherche de progression (geste horizontal) et l'ajustement de la vitesse de lecture (geste d'appui long), car les flux en direct n'ont pas de durée fixe.
Masqué : L'emplacement de vignette, car les flux en direct n'ont pas besoin de vignette.
Conservé : Les gestes de clic/double-clic, l'ajustement du volume et de la luminosité.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:liveSource];
model.sceneType = SceneTypeLive;
model.videoTitle = @"Popular Live Stream";
model.autoPlay = YES;

[controller configure:model];

VideoList - Scénario de liste de vidéos

Scénarios : Vidéos intégrées dans les fils d'actualité, listes de courtes vidéos, collections de vidéos défilantes, etc.

Principales différences par rapport à la VOD :

Désactivé : Les gestes de glissement vertical pour éviter les conflits avec le défilement de UIScrollView de la liste.
Conservé : Toutes les autres fonctionnalités, telles que la recherche de progression, l'ajustement de la vitesse de lecture et les gestes de clic/double-clic/appui long.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeVideoList;
model.autoPlay = YES;

[controller configure:model];

Restricted - Scénario de lecture restreinte

Scénarios : Vidéos de surveillance d'examens en ligne, cours de formation et de certification, scénarios de protection des droits d'auteur, etc.

Principales différences par rapport à la VOD :

Désactivé : La recherche de progression (geste horizontal) et l'ajustement de la vitesse de lecture (geste d'appui long) pour garantir que les utilisateurs regardent le contenu dans son intégralité et dans l'ordre.
Masqué : L'emplacement de vignette.
Conservé : Les gestes de clic/double-clic, l'ajustement du volume et de la luminosité.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeRestricted;
model.videoTitle = @"Security Training Course";
model.autoPlay = YES;
// Usually used with screenshot prevention
model.disableScreenshot = YES;

[controller configure:model];

Minimal - Mode minimal

Scénarios : Lecture en arrière-plan, interface utilisateur entièrement personnalisée, lecture de vignettes d'aperçu, etc.

Principales différences par rapport à la VOD :

Masqué : Presque tous les emplacements de contrôle de l'interface utilisateur. Seuls PlayerSurface et PlayState sont conservés.
Désactivé : Tous les gestes. L'emplacement GestureControl n'est pas visible dans le scénario Minimal, et ses méthodes internes de gestion des gestes effectuent toutes un return immédiat.
Cas d'utilisation : Scénarios nécessitant une interface utilisateur de contrôle de lecture entièrement personnalisée.

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

[controller configure:model];
// All controls must be implemented using the controller's API
// For example: [controller play]; [controller pause]; [controller seekTo:position];

Développement personnalisé

Réglage fin de la visibilité des emplacements

Si la visibilité prédéfinie des emplacements pour un scénario ne répond pas à vos exigences, ajustez-la finement à l'aide de SlotConfig :

// Example: Hide the TopBar in the Live scenario
SlotConfig *topBarConfig = [SlotConfig configWithSlotType:SlotTypeTopBar
                                           excludedScenes:[NSSet setWithObjects:
                                               @(SceneTypeMinimal),
                                               @(SceneTypeLive), nil]];

// Register with SlotManager (overwrites the default SlotConfig for this slot type)
[playerView.slotManager registerSlotConfig:topBarConfig];

Vous pouvez également masquer un emplacement entier directement à l'aide de hideSlot:. Cette méthode ne dépend pas du scénario :

// Unconditionally hide the TopBar (requires calling rebuildSlots to take effect)
[playerView.slotManager hideSlot:SlotTypeTopBar];

Remarque

registerSlotConfig: fournit un contrôle de visibilité au niveau du scénario, tandis que hideSlot: fournit un contrôle de visibilité au niveau de l'emplacement. Ils fonctionnent indépendamment. Un emplacement est construit uniquement s'il passe les deux vérifications.

Réglage fin du comportement des gestes

Le contrôle des gestes prend en charge deux méthodes de réglage fin :

Méthode 1 : Désactivez des gestes spécifiques à l'aide de l'API de masque binaire d'éléments SlotManager. Il s'agit de la méthode recommandée. Vous devez la configurer avant l'appel attach.

// Disable long press for fast-forward in the VOD scenario
[playerView.slotManager hideElements:GestureElementLongPress
                             forSlot:SlotTypeGestureControl];

Méthode 2 : Contrôlez les gestes directement à l'aide de GestureControlSlotConfig. Récupérez l'instance de l'emplacement après l'appel attach :

// Get the gesture control slot instance
GestureControlSlot *gestureSlot = (GestureControlSlot *)[playerView.slotManager slotViewForType:SlotTypeGestureControl];

// Modify the configuration (takes effect immediately)
GestureControlSlotConfig *config = [GestureControlSlotConfig defaultConfig];
config.longPressEnabled = NO;
config.horizontalDragEnabled = NO;
gestureSlot.config = config;

Remarque

Les deux méthodes fonctionnent indépendamment. Le masque binaire d'éléments est appliqué lors de la construction de l'emplacement (pendant la phase setupContentView). GestureControlSlotConfig prend effet dynamiquement au moment de l'exécution.

Enregistrement d'emplacements personnalisés dans le scénario Minimal

Dans le scénario Minimal, la plupart des emplacements par défaut sont exclus par la configuration du scénario. Pour restaurer un emplacement, remplacez son SlotConfig :

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;

// Override the scene configuration for BottomBar to remove the Minimal exclusion rule
[playerView.slotManager registerSlotConfig:
    [SlotConfig configWithSlotType:SlotTypeBottomBar]]; // No excludedScenes = visible in all scenarios

[controller configure:model];

Conditions de visibilité dynamiques

Utilisez le rappel visibilityCondition de SlotConfig pour implémenter un contrôle dynamique au moment de l'exécution :

SlotConfig *coverConfig = [SlotConfig configWithSlotType:SlotTypeCover
                                          excludedScenes:nil
                                     visibilityCondition:^BOOL{
    // Show the cover slot only if a cover URL exists
    return model.coverUrl != nil;
}];

[playerView.slotManager registerSlotConfig:coverConfig];

Remarque

La méthode isVisibleInScene: vérifie d'abord excludedScenes. Si une correspondance est trouvée, l'emplacement n'est pas visible. La méthode vérifie ensuite visibilityCondition. Si ce rappel renvoie NO, l'emplacement n'est pas visible. Un emplacement est visible uniquement s'il passe les deux vérifications.

Guide de sélection des scénarios

Flux de décision

Do you need a player control UI?
├── No → SceneTypeMinimal
└── Yes → Is it a live stream?
         ├── Yes → SceneTypeLive
         └── No → Is the player embedded in a scrollable list?
                   ├── Yes → SceneTypeVideoList
                   └── No → Do you need to prevent users from skipping?
                             ├── Yes → SceneTypeRestricted
                             └── No → SceneTypeVOD (default)

Tableau récapitulatif de sélection des scénarios

Besoin métier

Scénario recommandé

Raisons principales

Lecture vidéo standard

SceneTypeVOD

Scénario par défaut, prise en charge complète des fonctionnalités

Flux en direct / Événement sportif en temps réel

SceneTypeLive

Désactive automatiquement les opérations de progression non applicables

Vidéo intégrée dans UIScrollView

SceneTypeVideoList

Évite automatiquement les conflits de gestes verticaux

Formation / Examen / Protection des droits d'auteur

SceneTypeRestricted

Désactive automatiquement le saut et l'ajustement de la vitesse de lecture

Interface utilisateur entièrement personnalisée

SceneTypeMinimal

Toile vierge sans interférence d'interface utilisateur intégrée

Lecture en arrière-plan / Picture-in-Picture (PiP)

SceneTypeMinimal

Aucun composant de contrôle d'interface utilisateur nécessaire

Référence rapide de l'API

Énumération SceneType

Valeur d'énumération

Valeur entière

Description

SceneTypeVOD

0

Scénario VOD (par défaut)

SceneTypeLive

1

Scénario de diffusion en direct

SceneTypeVideoList

2

Scénario de liste de vidéos/flux de courtes vidéos

SceneTypeRestricted

3

Scénario de lecture restreinte

SceneTypeMinimal

4

Scénario de page de lecture minimale

SlotConfig

Méthode / Propriété

Description

configWithSlotType:

Crée une configuration sans scènes exclues (visible dans tous les scénarios)

configWithSlotType:excludedScenes:

Crée une configuration avec des scènes exclues spécifiées

configWithSlotType:excludedScenes:visibilityCondition:

Crée une configuration avec des scènes exclues et une condition dynamique

slotType

Type d'emplacement (readonly)

excludedScenes

Ensemble des scènes exclues, NSSet<NSNumber *> (readonly, nullable)

visibilityCondition

Bloc de condition de visibilité dynamique (readonly, nullable)

isVisibleInScene:

Vérifie si l'emplacement est visible dans un scénario spécifié

GestureControlSlotConfig

Propriété

Type

Valeur par défaut

Description

singleTapEnabled

BOOL

YES

Active ou désactive le geste de clic

doubleTapEnabled

BOOL

YES

Active ou désactive le geste de double-clic

longPressEnabled

BOOL

YES

Active ou désactive le geste d'appui long

horizontalDragEnabled

BOOL

YES

Active ou désactive le geste de glissement horizontal

leftVerticalDragEnabled

BOOL

YES

Active ou désactive le geste de glissement vertical gauche

rightVerticalDragEnabled

BOOL

YES

Active ou désactive le geste de glissement vertical droit

+defaultConfig

Méthode de classe

—

Crée une configuration par défaut avec tous les gestes activés

API liées aux scénarios de SlotManager

Méthode

Description

registerSlotConfig:

Enregistre une configuration de visibilité de scénario pour un type d'emplacement (remplace la configuration par défaut)

unregisterSlotConfigForType:

Supprime la configuration de scénario pour un type d'emplacement spécifié (devient visible par défaut après suppression)

slotConfigForType:

Obtient la configuration de visibilité de scénario pour un type d'emplacement spécifié

hideSlot:

Masque un emplacement spécifié (niveau de l'emplacement, indépendant de la configuration du scénario)

showSlot:

Affiche un emplacement précédemment masqué

hideElements:forSlot:

Masque des éléments au sein d'un emplacement ou désactive des gestes à l'aide d'un masque binaire

showElements:forSlot:

Affiche des éléments au sein d'un emplacement ou active des gestes à l'aide d'un masque binaire

slotViewForType:

Obtient l'instance de vue d'un emplacement monté

rebuildSlots

Reconstruit tous les emplacements (doit être appelé après une modification de la configuration du scénario)

Fichiers connexes

Fichier

Description

PlayerKit/Source/Data/SceneType.h

Définition de l'énumération SceneType

PlayerKit/Source/AliPlayerModel.h

Point d'entrée pour la définition du type de scénario (propriété sceneType)

PlayerKit/Source/Slot/SlotConfig.h

Configuration de la visibilité des emplacements

PlayerKit/Source/Slot/DefaultSlotFactory.h

Fournisseur d'emplacements par défaut et règles de visibilité des scénarios

PlayerKit/Source/Slot/SlotManager.h

Point d'entrée de gestion unifiée du système d'emplacements

PlayerKit/Source/Slot/SlotElements.h

Définitions des masques binaires d'éléments de geste

PlayerKit/Source/UI/Slots/GestureControlSlot.h

Emplacement de contrôle des gestes et définition de GestureControlSlotConfig

PlayerKit/Source/Slot/BaseSlot.h

Classe de base des emplacements (méthode currentSceneType)

Pour plus d'informations, consultez la Référence de l'API.

Bonnes pratiques

Remarques

Élément

Description

Déterminer lors de la création

Spécifiez SceneType lors de la création de AliPlayerModel. Ne le changez pas dynamiquement pendant la lecture.

Privilégier le scénario de liste

Utilisez toujours SceneTypeVideoList lorsque vous intégrez le lecteur dans un UIScrollView ou UICollectionView.

Minimal nécessite un contrôle manuel

Après avoir sélectionné Minimal, le développeur doit implémenter tous les contrôles de lecture à l'aide de l'API AliPlayerController.

Réglage fin composable

Si le comportement prédéfini ne répond pas entièrement à vos besoins, ajustez-le finement à l'aide de SlotConfig et SlotManager.

Live et Restricted ont un comportement similaire

Leurs règles de filtrage des gestes sont identiques (désactivation de la recherche de progression et de l'ajustement de la vitesse de lecture). Les différences résident uniquement dans la visibilité de la vignette (masquée dans les deux cas) et la sémantique métier.

FAQ

La principale différence réside dans le geste vertical. SceneTypeVideoList désactive les gestes verticaux pour le volume et la luminosité afin d'éviter les conflits avec le geste de défilement du conteneur de liste. Les autres fonctionnalités sont identiques à celles de la VOD.

Comment implémenter des contrôles personnalisés dans le scénario Minimal ?

Contrôlez le comportement de lecture directement à l'aide de l'API AliPlayerController. Vous pouvez également enregistrer des emplacements personnalisés pour remplacer l'interface utilisateur :

AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];
model.sceneType = SceneTypeMinimal;
[controller configure:model];

// Control directly through the controller API
[controller play];
[controller pause];
[controller seekTo:30000]; // Seek to 30 seconds

Comment restaurer la recherche de progression dans un scénario Live ?

Si votre scénario de diffusion en direct prend en charge le décalage temporel, restaurez le geste désactivé à l'aide de l'API de contrôle des éléments de SlotManager :

// Restore the horizontal drag gesture (progress seeking)
[playerView.slotManager showElements:GestureElementHorizontalDrag
                             forSlot:SlotTypeGestureControl];

Remarque

Cette méthode restaure uniquement la visibilité au niveau des éléments. La logique de filtrage des scénarios à l'intérieur de GestureControlSlot est codée en dur et ne peut pas être contournée à l'aide de showElements:. Pour personnaliser entièrement le comportement des gestes, utilisez GestureControlSlotConfig ou remplacez GestureControlSlot.

Introduction

Qu'est-ce que SceneType ?

Valeur principale

Fonctionnalités

Aperçu des scénarios

Définition de l'énumération

Matrice des capacités des scénarios

Visibilité des emplacements

Différences de comportement des gestes

Utilisation

Utilisation de base

Description détaillée de chaque scénario

VOD - Scénario VOD (par défaut)

Live - Scénario de diffusion en direct

VideoList - Scénario de liste de vidéos

Restricted - Scénario de lecture restreinte

Minimal - Mode minimal

Développement personnalisé

Réglage fin de la visibilité des emplacements

Réglage fin du comportement des gestes

Enregistrement d'emplacements personnalisés dans le scénario Minimal

Conditions de visibilité dynamiques

Guide de sélection des scénarios

Flux de décision

Tableau récapitulatif de sélection des scénarios

Référence rapide de l'API

Énumération SceneType

SlotConfig

GestureControlSlotConfig

API liées aux scénarios de SlotManager

Fichiers connexes

Bonnes pratiques

Remarques

FAQ

Quelle est la différence entre VOD et VideoList ?

Comment implémenter des contrôles personnalisés dans le scénario Minimal ?

Comment restaurer la recherche de progression dans un scénario Live ?