Integrate the mini drama solution - Flutter - ApsaraVideo VOD

The mini drama solution for Flutter is built on AliPlayerWidget, a UI integration component for Flutter.

Overview

AliPlayerWidget is a high-performance video playback component designed for Flutter applications and is built on the ApsaraVideo Player SDK (flutter_aliplayer). It supports various playback scenarios, including video-on-demand (VOD), live streaming, list playback, and mini dramas. This component provides a rich set of features and highly flexible UI customization capabilities to meet the needs of various applications, such as those for education, entertainment, e-commerce, and mini dramas. For more information, see Flutter player with UI integration solution.

aliplayer_widget_example is a sample project built on the aliplayer_widget Flutter library. It is designed to help developers quickly understand how to integrate and use AliPlayerWidget in their projects. This project demonstrates how to set up and use short video list playback.

Environment requirements

Item	Description
Flutter version	2.10.0 or later. We recommend that you use 3.22.2.
JDK version	We recommend that you use JDK 11. Note JDK 11 configuration method: Preferences > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK, select 11. If JDK 11 is not available, upgrade your Android Studio.
Android version	Android 6.0 or later. Gradle 7.0 or later.
iOS version	iOS 10.0 or later.
Mobile phone processor	Architecture: armeabi-v7a or arm64-v8a.
Development tool	We recommend that you use Android Studio or Visual Studio Code.

Prerequisites

You have obtained a Player SDK license for the Professional Edition, along with the corresponding authorization file and License Key. For more information about how to bind the license, see Bind License.

Demo experience

Download the demo

aliplayer_widget is open source and can be downloaded by using multiple methods. If you want to customize the component, you can use the source code dependency to obtain and modify the source code. The complete source code can be obtained through the following methods:

Download description	Download link
Pub source	Official Pub source: pub.dev China mirror source: pub.flutter-io.cn Note We recommend that developers integrate aliplayer_widget through package management tools
Pub source
GitHub	GitHub repository
Source code package	aliplayer_widget.zip

The downloaded package includes:

Core components: Complete implementation of AliPlayerWidget and AliPlayerWidgetController.
Sample project: aliplayer_widget_example provides code examples for scenarios such as VOD, live streaming, and list playback to help developers quickly integrate and use the component.
Documentation and comments: The source code includes detailed comments and development guides for custom development.

Integration methods

Manually add the dependency

Add the following dependency to your pubspec.yaml file:

dependencies:
  aliplayer_widget: ^x.y.z

Note

x.y.z represents the version of aliplayer_widget. You can view the latest stable version on the Pub.dev official page and replace x.y.z with the actual value, such as ^7.0.0.

Use a command line interface

If you want to use a command line interface to install the dependency, run the following command:

flutter pub add aliplayer_widget

The command automatically updates your pubspec.yaml file.

Regardless of either method you choose, run the following command in the terminal to install the dependency after adding it:

flutter pub get

After you perform the preceding steps, AliPlayerWidget is integrated into your project, and you can start using it.

Compilation and running

Use a command line interface

Clone the repository.
Clone the aliplayer_widget_example repository to your local storage:
```
cd aliplayer_widget_example
```
Install dependencies.
Run the following command to install the required dependency for the project:
```
flutter pub get
```
Compile the project.
Compile an Android project
If you want to compile an Android project, perform the following sub-steps:
1. Install Player SDK for Android and Gradle.
2. Run the following command to generate the APK file:
```
flutter build apk
```
3. Compile the Android project. After compilation, the APK file will be located at build/app/outputs/flutter-apk/app-release.apk.
Compile an iOS project
If you want to compile an iOS project, perform the following sub-steps:
1. Install Xcode and CocoaPods.
2. Initialize CocoaPods dependencies:
```
cd ios && pod install && cd ..
```
3. Run the following command to generate the iOS app package (IPA file):
```
flutter build ipa
```
4. Compile the Android project. After compilation, the IPA file will be located at build/ios/ipa/Runner.ipa.

Run the demo.

Run demo for Android.
```
flutter run lib/main.dart
```

Run the demo for iOS.

cd ios && pod install && cd ..//Run pod install first

flutter run lib/main.dart

Use an IDE

Use Android Studio
1. Open the project.
  Start Android Studio. Select Open an Existing Project, navigate to the cloned aliplayer_widget_example directory, and open it.
2. Install dependencies.
  In Android Studio, click the pubspec.yaml file, and then click the Pub Get button in the upper right corner to install dependencies.
3. Configure the device.
  Make sure an Android device is connected.
4. Run the app.
  Click the green Run button in the toolbar, select the target device to start the app.
Use Visual Studio Code
1. Open the project:
  Launch Visual Studio Code. Select File -> Open Folder, then navigate to the cloned aliplayer_widget_example directory and open it.
2. Install dependencies:
  Open the terminal by pressing Ctrl + ~ and run the following command to install dependencies:
```
flutter pub get
```
3. Configure device:
  Make sure an Android or iOS physical device is connected. Use the device selector in the bottom left corner in Visual Studio Code to select the target device.
4. Run the app.
  Press F5 or click the Run and Debug icon in the left activity bar, select the Flutter configuration, and start the debugging session.
Use Xcode (iOS only)
1. Open the project.
  Navigate to the ios directory, double-click the Runner.xcworkspace file to open the project in Xcode.
2. Install the CocoaPods dependency.
  If the CocoaPods dependency is not installed, run the following command in the terminal:
```
cd ios && pod install && cd ..
```
3. Configure signing.
  In Xcode, select the Runner project, go to the Signing & Capabilities tab, and configure a valid developer account and signing certificate.
4. Run the app.
  Click the run button ▶️ in the Xcode toolbar, select the target device to start the app.

Usage

Short video list playback page (ShortVideoPage)

The core of short video playback is to embed multiple AliPlayerWidget instances in a list to enable list playback for multiple videos. The following sample code provides an example:

@override
void initState() {
  super.initState();
  _pageController = PageController();
  _loadVideoInfoList();
  _pageController.addListener(_onPageChanged);
}

Widget build(BuildContext context) {
  return Scaffold(
    body: PageView.builder(
      controller: _pageController,
      itemCount: videoInfoList.length,
      itemBuilder: (context, index) {
        final videoInfo = videoInfoList[index];
        return ShortVideoItem(videoInfo: videoInfo);
      },
    ),
  );
}

Result: The page displays a video list. Each list item contains a separate player instance. You can swipe to switch between videos.

Note

For more optimization solutions for mini-drama scenarios, see the aliplayer_widget_example sample project.

Core features

This component uses the ApsaraVideo Player SDK and is implemented with multiple player instances (AliPlayer), preloading (MediaLoader), and pre-rendering. It leverages core capabilities, such as preloading, pre-rendering, HTTPDNS, and encrypted playback, to improve playback latency, stability, and security for a better viewing experience.

Preloading

The sliding window policy dynamically starts and stops video preloading tasks. The underlying SDK layer intelligently adjusts task priorities based on the network status to ensure that more network resources are allocated to the video that is currently playing or is about to be played. This improves the instant playback rate, reduces playback stuttering, and allows for smooth playback even when you swipe quickly through videos. For more information, see Preloading.

Pre-rendering

Pre-rendering renders the first frame of the next video in the background. This reduces black screens and ensures smoother playback. Apsara Video SDK and ApsaraVideo Player SDK have supported forced pre-rendering since version 6.16.0. For more information, see Pre-rendering.

HTTPDNS

HTTPDNS provides a faster and more stable Domain Name System (DNS) resolution service. By replacing traditional DNS resolution, HTTPDNS reduces DNS resolution time and improves the loading speed and stability of video playback, which enhances the user's viewing experience. HTTPDNS is enabled by default in Apsara Video SDK and ApsaraVideo Player SDK versions 6.12.0 and later. For more information, see HTTPDNS.

Video encryption

Videos in mini drama scenarios are typically MP4 files that are 1 to 3 minutes long. To provide security for these videos, Apsara Video SDK and ApsaraVideo Player SDK have supported private encryption for MP4 playback since version 6.8.0. For more information, see Alibaba Cloud video encryption (private encryption).

A privately encrypted MP4 video must meet the following conditions for playback:

When passing a privately encrypted MP4 video to the player, the application must append etavirp_nuyila=1 to the video URL. For example, if the original video URL is https://example.aliyundoc.com/test.mp4, the URL passed to the player must be https://example.aliyundoc.com/test.mp4?etavirp_nuyila=1.
The UID of the application's license must be the same as the UID used to privately encrypt the MP4 file.

You can use the following methods to verify that a video is privately encrypted:

The video's meta information must contain the AliyunPrivateKeyUri tag.
The video cannot be played directly using ffplay.

H.265 adaptive playback

If hardware decoding of an H.265 stream fails, the player automatically switches to the backup H.264 stream if one is configured. If no backup H.264 stream is configured, the player switches to software decoding for the H.265 stream. For more information, see H.265 adaptive playback.

Adaptive ABR

The player SDK supports adaptive bitrate streaming for HLS and DASH video streams. You can call the player's selectTrack method to switch the currently playing stream. This lets you implement network-adaptive video quality switching. For more information, see Network-adaptive switching.

FAQ

For more frequently asked questions and troubleshooting tips for the ApsaraVideo Player SDK, see Player FAQ.