ApsaraVideo VOD:Scene types

Introduction

What is SceneType?

SceneType is an enumeration that specifies the current business scenario for the player. When you set the SceneType, AliPlayerKit automatically:

• Adjusts slot visibility, such as hiding the thumbnail in a live streaming scenario.

• Filters gestures, such as disabling progress seeking and playback speed adjustment in live or restricted scenarios, or disabling vertical gestures in video list scenarios.

• Adapts to feature limitations, such as ensuring users watch content completely and in order in a restricted scenario.

By simply setting an enumeration value, the framework automatically handles these adaptations. This greatly reduces the effort required to customize the player for different business scenarios.

Core value

Features

Scenario overview

AliPlayerKit has five built-in scene types that cover most playback requirements:

Enumeration definition

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

Scenario capability matrix

Slot visibility

The slot system automatically controls component visibility based on the scene type. The following matrix shows the default rules from DefaultSlotFactory.defaultConfigs:

Visibility rule descriptions:

• PlayerSurface and PlayState: Visible in all scenarios (no excludedScenes configuration).

• Cover: Not visible in the Live, Restricted, or Minimal scenarios.

• Other slots (GestureControl, LandscapeHint, CenterDisplay, LogPanel, TopBar, BottomBar, SettingMenu, OptionPanel): Not visible only in the Minimal scenario.

Gesture behavior differences

The GestureControlSlot internally filters gestures in each handling method based on the currentSceneType:

Filter logic descriptions:

• Minimal: All gesture handling methods (handleSingleTap:, handleDoubleTap:, handleLongPress:, and handlePan:) return immediately at the entry point.

• Live / Restricted: Long press and horizontal drag are disabled. This is checked in handleLongPress: and tryStartDragWithCurrentPoint:.

• VideoList: Vertical drag is disabled. The tryStartDragWithCurrentPoint: method returns immediately when it detects SceneTypeVideoList.

Usage

Basic usage

You can specify the scene type using the AliPlayerModel.sceneType property. The default is SceneTypeVOD, which you do not need to set explicitly.

VOD scenario (default, no setup required):

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

Live streaming scenario:

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

Video list scenario:

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

Detailed description of each scenario

VOD - VOD scenario (default)

Scenarios: Standard video playback, online courses, Media Library browsing, and more.

Capabilities:

• Supports all 11 default slots

• Supports all 6 gestures

• Supports progress seeking, playback speed adjustment, and resolution switching

• Supports full screen switching

// 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 - Live streaming scenario

Scenarios: Real-time live streaming, live sports events, E-commerce live streaming, and more.

Key differences from VOD:

• Disabled: Progress seeking (horizontal gesture) and playback speed adjustment (long press gesture) because live streams do not have a fixed duration.

• Hidden: Thumbnail slot because live streams do not need a thumbnail.

• Retained: Click/double-click gestures, volume/brightness adjustment.

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

[controller configure:model];

VideoList - Video list scenario

Scenarios: Embedded videos in feeds, short video lists, scrollable video collections, and more.

Key differences from VOD:

• Disabled: Vertical drag gestures to avoid conflicts with the list's UIScrollView scrolling.

• Retained: All other features, such as progress seeking, playback speed adjustment, and click/double-click/long press gestures.

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

[controller configure:model];

Restricted - Restricted playback scenario

Scenarios: Online exam monitoring videos, training and certification courses, copyright protection scenarios, and more.

Key differences from VOD:

• Disabled: Progress seeking (horizontal gesture) and playback speed adjustment (long press gesture) to ensure users watch the content completely and in order.

• Hidden: Thumbnail slot.

• Retained: Click/double-click gestures, volume/brightness adjustment.

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 - Minimal mode

Scenarios: Background playback, fully custom UI, preview thumbnail playback, and more.

Key differences from VOD:

• Hidden: Almost all UI control slots. Only PlayerSurface and PlayState are retained.

• Disabled: All gestures. The GestureControl slot is not visible in the Minimal scenario, and its internal gesture handling methods all return immediately.

• Use cases: Scenarios that require a fully custom playback control UI.

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

Custom development

Fine-tuning slot visibility

If the preset slot visibility for a scenario does not meet your requirements, you can fine-tune it using 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];

You can also hide an entire slot directly using hideSlot:. This method does not depend on the scenario:

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

Fine-tuning gesture behavior

Gesture control supports two methods for fine-tuning:

Method 1: Disable specific gestures using the SlotManager element bitmask API. This is the recommended method. You must configure it before the attach call.

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

Method 2: Control gestures directly using GestureControlSlotConfig. You must retrieve the slot instance after the attach call:

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

Registering custom slots in the Minimal scenario

In the Minimal scenario, most default slots are excluded by the scene configuration. To restore a slot, you can override its 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];

Dynamic visibility conditions

You can use the SlotConfig visibilityCondition callback to implement dynamic control at runtime:

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

Scene selection guide

Decision flow

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)

Scene selection summary table

API quick reference

SceneType enumeration

SlotConfig

GestureControlSlotConfig

SlotManager scenario-related APIs

Related files

For more information, see the API Reference.

Best practices

Notes

FAQ

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

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