Integrate the mini drama solution - Flutter - ApsaraVideo VOD

Overview

AliPlayerWidget is a high-performance video playback component designed for Flutter applications, built on top of the ApsaraVideo Player SDK (flutter_aliplayer). It supports various playback scenarios, including video on demand (VOD), live streaming, list playback, and mini-dramas. Its rich feature set and flexible UI customization make it ideal for diverse applications such as education, entertainment, e-commerce, and mini-dramas. For more information, see Flutter Player UI Integration Solution.

The aliplayer_widget_example is a sample project built with the aliplayer_widget Flutter library. It helps developers quickly understand how to integrate and use AliPlayerWidget in a real-world project. This project demonstrates how to set up and use short video list playback.

Environment requirements

Category	Description
Flutter version	2.10.0 or later. We recommend that you use 3.22.2.
JDK version	Use JDK 11. Note To set the JDK version to 11, go to Preferences > Build, Execution, Deployment > Build Tools > Gradle > Gradle JDK and select 11. If version 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 chip	Architecture: armeabi-v7a or arm64-v8a.
Development tool	Use Android Studio or Visual Studio Code.

Prerequisites

You have obtained a Player SDK license and its license key. For instructions on how to bind the license to your application, see Bind a license.

In the ApsaraVideo VOD console, go to SDK Management > My Authorizations in the left navigation pane. On the License Management tab, copy the license key and click Download Certificate to download the license file.

Try the demo

Download the demo

aliplayer_widget is open source. You can obtain the complete source code in one of the following ways and modify it to customize the component:

Download method	Download link
Pub source	Official Pub source: pub.dev China mirror source: pub.flutter-io.cn Note We recommend that you integrate aliplayer_widget using a package management tool.
Pub source
GitHub	GitHub repository
Source code package	aliplayer_widget.zip

The downloaded package includes:

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

Integration

Add the dependency manually

Add the following dependency to your pubspec.yaml file:

dependencies:
  aliplayer_widget: ^x.y.z

Note

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

Use the command-line tool

If you prefer to use the command line, run the following command to add the dependency:

flutter pub add aliplayer_widget

This command automatically updates your pubspec.yaml file.

After you add the dependency, run the following command in the terminal to install it:

flutter pub get

After you complete these steps, AliPlayerWidget is integrated into your project. You can now start using it.

Compile and run the project

Run from the command line

Clone the repository.

First, clone the aliplayer_widget_example repository to your local machine:
```
cd aliplayer_widget_example
```
Install dependencies.

Run the following command to install the required dependencies for the project:
```
flutter pub get
```
Compile the project.
Compile the Android project

To compile the Android project, perform the following steps:
1. Make sure you have installed the Android SDK and Gradle.
2. Run the following command to generate the APK file:
```
flutter build apk
```
3. After the compilation is complete, the APK file is located at build/app/outputs/flutter-apk/app-release.apk.
Compile the iOS project

To compile the iOS project, perform the following steps:
1. Make sure you have installed Xcode and CocoaPods.
2. Initialize the CocoaPods dependencies:
```
cd ios && pod install && cd ..
```
3. Run the following command to generate the iOS application package (IPA) file:
```
flutter build ipa
```
4. After the compilation is complete, the IPA file is located at build/ios/ipa/Runner.ipa.

Run the sample.

Run the Android sample.
```
flutter run lib/main.dart
```

Run the iOS sample.

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

flutter run lib/main.dart

Run from an IDE

Use Android Studio
1. Open the project.
  
  Start Android Studio. Select Open an Existing Project, and then open the cloned aliplayer_widget_example directory.
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 the dependencies.
3. Configure the device.
  
  Make sure an Android physical device is connected.
4. Run the application.
  
  Click the green run button (Run) in the toolbar and select the target device to start the application.
Use VS Code
1. Open the project.
  
  Start VS Code. Select File -> Open Folder and open the cloned aliplayer_widget_example directory.
2. Install dependencies.
  
  Open the terminal (Ctrl + ~) and run the following command to install the dependencies:
```
flutter pub get
```
3. Configure the device.
  
  Make sure an Android or iOS physical device is connected. Use the device selector in the bottom-left corner of VS Code to select the target device.
4. Run the application.
  
  Press F5 or click the Run and Debug icon in the Activity Bar on the left. Select the Flutter configuration and start the debugging session.
Use Xcode (iOS only)
1. Open the project.
  
  Navigate to the ios directory and double-click the Runner.xcworkspace file to open the project in Xcode.
2. Install the CocoaPods dependencies.
  
  If the CocoaPods dependencies are not installed, run the following command in the terminal:
```
cd ios && pod install && cd ..
```
3. Configure the signature.
  
  In Xcode, select the Runner project, go to the Signing & Capabilities tab, and configure a valid developer account and signing certificate.
4. Run the application.
  
  Click the run button (▶️) in the Xcode toolbar and select the target device to start the application.

Usage

Short video list playback (ShortVideoPage)

This section demonstrates how to achieve list playback by embedding multiple AliPlayerWidget instances in a list. The following is a sample:

@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 current page displays a video list where each list item contains a separate player instance. Users can swipe to switch between videos and use gestures for navigation.

Note

For more optimization solutions tailored to the mini-drama scenario, refer to the specific implementation in the aliplayer_widget_example sample project.

Core features

This component uses the ApsaraVideo Player SDK to implement multiple player instances (AliPlayer) combined with preloading (MediaLoader) and pre-rendering. It combines core features like preloading, pre-rendering, HTTPDNS, and encrypted playback to improve playback latency, stability, and security.

Preloading

The sliding window strategy dynamically starts and stops video preloading tasks. The underlying SDK intelligently adjusts task priorities based on network conditions to prioritize network resources for the currently playing and upcoming videos, which significantly improves the first-frame loading speed and reduces playback stuttering. You can enjoy a smooth playback experience even when you quickly swipe through videos. For more information, see Preloading.

Pre-rendering

Pre-rendering renders the first frame of subsequent videos in the background to reduce black screens and make playback smoother. ApsaraVideo SDK for MediaBox and the Player SDK have supported the forced pre-rendering feature since version 6.16.0. For more information, see Pre-rendering.

HTTPDNS

HTTPDNS provides a faster and more stable DNS resolution service. It replaces traditional DNS resolution to reduce DNS resolution time, improve the loading speed and stability of video playback, and enhance the user viewing experience. You do not need to manually enable HTTPDNS for the Audio and Video Client SDK and the Player SDK for versions 6.12.0 and later. For more information, see HTTPDNS.

Video encryption

Videos in mini-drama scenarios are typically MP4 files of 1 to 3 minutes. Since version 6.8.0, ApsaraVideo SDK for MediaBox and ApsaraVideo Player SDK support private encryption for MP4 files, which secures mini-drama video content. For more information, see Alibaba Cloud video encryption (private encryption).

Playing privately encrypted MP4 videos requires the following:

When passing the URL of a privately encrypted MP4 video to the player, your application must append the query parameter etavirp_nuyila=1. 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 associated with the application's license must match the UID used to generate the privately encrypted MP4 file.

You can verify the configuration of a privately encrypted video by checking its URL for the following:

The video's metadata should contain the AliyunPrivateKeyUri tag.
The video cannot be played directly with ffplay.

H.265 adaptive playback

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

Adaptive bitrate streaming (ABR)

ApsaraVideo Player SDK supports multi-bitrate adaptive HLS and DASH video streams. You can implement network-adaptive switching by calling the player's selectTrack method to switch between bitrates. For more information, see Network-adaptive switching.

FAQ

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