Scene types-ApsaraVideo VOD(VOD)-阿里云帮助中心

The scene type (SceneType) is an abstraction in AliPlayerKit for playback scenarios. By specifying a scene type, the player automatically adapts its UI behavior, gesture controls, and slot visibility.

Configuration

final controller = AliPlayerWidgetController();

controller.configure(
  AliPlayerWidgetData(
    videoSource: videoSource,
    sceneType: SceneType.live, // Set the playback scene based on your business needs.
  ),
);

Note

At runtime, you can use isSceneType / isNotSceneType (in lib/utils/scene_util.dart) to quickly determine the current scene and execute different logic.

Scene capability matrix

Scene	Use cases	UI and gestures	Slot policy	Recommendation
`SceneType.vod`	Standard VOD, courses, media libraries	Supports all controls, including playback, progress scrubbing, playback speed, and gestures.	All slots are available.	Default and recommended.
`SceneType.live`	Live streaming, sports events	Disables timeline operations. Only Refresh, gesture controls, and the Settings Menu are available.	`coverImage` and `seekThumbnail` are hidden.	Use for real-time streams.
`SceneType.listPlayer`	Feeds, short-form video feeds	Disables vertical gestures to avoid conflicts with list scrolling. Basic controls are retained.	Same slots as VOD.	Use when nested in a list.
`SceneType.restricted`	Exam proctoring, training sessions, anti-skip scenarios	Disables timeline capabilities like progress scrubbing, fast forward/rewind, and playback speed. Other controls are retained.	`coverImage` and `seekThumbnail` are hidden.	Enable when you must prevent skipping.
`SceneType.minimal`	Background playback, fully custom UI, decorative videos	Renders only the player surface. All controls, subtitles, and gestures are hidden or disabled.	Only `playerSurface` / `overlays` are visible	Use as a canvas or with a custom external UI.

Scene details

SceneType.vod

Features: Provides full video controls, all gestures, and all slots.
Typical Use Cases: VOD courses, movies and TV shows, and training videos.
Notes: This is the default value, offering a full feature set without extra configuration.

SceneType.live

Features: Disables timeline-related controls, such as progress scrubbing, seek thumbnails, and playback speed. However, Play/Pause, Refresh, Volume/Brightness gestures, full screen, and the Settings Menu remain available.
Typical Use Cases: Live channels, live events, and monitoring streams.
Note: SlotType.coverImage and SlotType.seekThumbnail are automatically removed.

SceneType.listPlayer

Features: Similar to VOD, but removes vertical gestures (for Volume/Brightness) to avoid conflicts with parent list gestures.
Typical Use Cases: Feeds, short-form video lists, and card-style players.
Note: If you need gesture interaction, you can switch to SceneType.vod in full-screen mode and then switch back.

SceneType.restricted

Features: Strictly disables all timeline operations, such as progress scrubbing, fast-forwarding, and changing playback speed. Only sequential playback is allowed.
Typical Use Cases: Exams, training, controlled presentations, and licensed content to prevent skipping.
Note: SlotType.coverImage and SlotType.seekThumbnail are automatically disabled. You can use a custom slot to display a countdown or prompt text.

SceneType.minimal

Features: Renders only the video surface. It does not load any UI slots, including subtitles, center prompts, or the control bar. All gestures and controls are disabled.
Typical Use Cases: Background videos, desktop motion effects, a fully custom external UI, or a picture-in-picture core.
Note: To overlay custom components, you can use SlotType.overlays or wrap them in a custom UI.

Slot and scene interaction

Slot type	Hidden in
`SlotType.coverImage`	`live`, `restricted`, `minimal`
`SlotType.playControl` / `topBar` / `bottomBar` / `centerDisplay` / `settingMenu` / `subtitle`	`minimal`
`SlotType.seekThumbnail`	`live`, `restricted`, `minimal`
`SlotType.playerSurface` / `playState` / `overlays`	Always available

If you need to display certain UI elements in specific scenarios, you can customize slotBuilders to force rendering, or switch to different builders based on sceneType in your business logic.

Best practices

Runtime switching: You can call controller.configure again with a new AliPlayerWidgetData.sceneType to reuse the same player across different pages.
State synchronization: When the external UI needs to be aware of the current scene, you can save sceneType in state management (such as Provider or Riverpod) to avoid repeated queries.
Testing Strategy: Focus on verifying whether the slots are correctly hidden in special scenarios (restricted, minimal), and whether the gesture conflicts in listPlayer are resolved.

By properly using sceneType, you can uniformly control the player's UI and interactive behaviors in different business scenarios without manually writing many conditional branches.