ApsaraVideo VOD:Flutter player with UI integration

aliplayer_widget is open source and available for download. To customize the component, you can obtain and modify the source code. You can obtain the complete source code in one of the following ways:

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

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.

Play a video

The following example shows how to embed a video player in a page. You can play a video with just a few lines of code.

import 'package:flutter/material.dart';
import 'package:aliplayer_widget/aliplayer_widget_lib.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: VideoPlayerPage(),
    );
  }
}

class VideoPlayerPage extends StatefulWidget {
  @override
  _VideoPlayerPageState createState() => _VideoPlayerPageState();
}

class _VideoPlayerPageState extends State<VideoPlayerPage> {
  late AliPlayerWidgetController _controller;

  @override
  void initState() {
    super.initState();
    // Initialize the player component controller.
    _controller = AliPlayerWidgetController(context);
    // Configure the player component data.
    final data = AliPlayerWidgetData(
      videoUrl: "https://example.com/video.mp4", // Replace this with the actual video URL.
      coverUrl: "https://example.com/cover.jpg", // Replace this with the actual thumbnail URL.
      videoTitle: "Sample Video",
    );
    _controller.configure(data); // Set autoplay.
  }

  @override
  void dispose() {
    // Destroy the player instance and release resources.
    _controller.destroy();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: AliPlayerWidget(
          _controller,
        ),
      ),
    );
  }
}

Support for more scenarios

The preceding example shows the basic usage in a VOD scenario. To learn about more complex scenarios, such as live streaming and list playback, see the aliplayer_widget_example sample project. It contains detailed code and instructions.

Compile and run the project

Sample description

The aliplayer_widget_example project covers multiple scenarios. It demonstrates the core features of AliPlayerWidget and its applications. Whether you need a basic VOD playback page, a complex live streaming page, or a short video list playback page, this sample project helps you quickly learn how to integrate and use the component. You can also customize the project as needed.

@override
void initState() {
  super.initState();
  _controller = AliPlayerWidgetController(context);
  final data = AliPlayerWidgetData(
    videoUrl: "https://example.com/sample-video.mp4",
    coverUrl: "https://example.com/sample-cover.jpg",
    videoTitle: "Sample Video Title",
  );
  _controller.configure(data);
}

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: AliPlayerWidget(_controller),
  );
}

@override
void initState() {
  super.initState();
  _controller = AliPlayerWidgetController(context);
  final data = AliPlayerWidgetData(
    videoUrl: "https://example.com/live-stream.m3u8",
    sceneType: SceneType.live,
  );
  _controller.configure(data);
}

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: Column(
      children: [
        Expanded(child: AliPlayerWidget(_controller)),
        _buildChatArea(),
        _buildMessageInput(),
      ],
    ),
  );
}

For information about how to use list playback for short videos, see Integrate the mini-drama solution for Flutter.

AliPlayerWidget

AliPlayerWidget is the core player component used to embed and play videos in a Flutter application.

Constructor

AliPlayerWidget(
  AliPlayerWidgetController controller, {
  Key? key,
  List<Widget> overlays = const [],
});

Example

AliPlayerWidget(
  _controller,
  overlays: [
    Positioned(
      right: 16,
      bottom: 80,
      child: Column(
        children: [
          IconButton(icon: Icon(Icons.favorite), onPressed: () {}),
          IconButton(icon: Icon(Icons.share), onPressed: () {}),
        ],
      ),
    ),
  ],
);

AliPlayerWidgetController

AliPlayerWidgetController is the core controller of the player component. It is used to manage the initialization, playback, and destruction logic of the player component.

Methods

Example

// Initialize the player component controller.
final controller = AliPlayerWidgetController(context);

// Set the player component data.
AliPlayerWidgetData data = AliPlayerWidgetData(
  videoUrl: "https://example.com/video.mp4",
);
controller.configure(data);

// Destroy the player.
controller.destroy();

AliPlayerWidgetData

AliPlayerWidgetData is the data model required by the player component. It contains the video URL, thumbnail, title, and other information.

Properties

Example

AliPlayerWidgetData(
  videoUrl: "https://example.com/video.mp4",
  coverUrl: "https://example.com/cover.jpg",
  videoTitle: "Sample Video",
  sceneType: SceneType.vod,
);

SceneType property

The following is an example:

_controller = AliPlayerWidgetController(context);
// Set the player component data.
final data = AliPlayerWidgetData(
  sceneType: SceneType.vod
);
_controller.configure(data);

Overlay components

You can use the overlays parameter to easily overlay custom UI components, such as Like, Comment, and Share buttons, on the player.

AliPlayerWidget(
  _controller,
  overlays: [
    Positioned(
      right: 16,
      bottom: 80,
      child: Column(
        children: [
          IconButton(icon: Icon(Icons.favorite), onPressed: () {}),
          IconButton(icon: Icon(Icons.comment), onPressed: () {}),
          IconButton(icon: Icon(Icons.share), onPressed: () {}),
        ],
      ),
    ),
  ],
);

Common API calls

AliPlayerWidget provides a series of external API calls that allow you to directly control the player's behavior. These API calls are exposed through AliPlayerWidgetController and support playback control, status queries, data updates, and other features. The following are some common external API calls and their scenarios:

Configuration and initialization

Playback control

Playback Property Settings

Other settings

Slot system

Overview
AliPlayerWidget provides a flexible slot system that supports fine-grained customization of the player interface. You can freely combine or replace UI components to create a branded, scenario-specific, or minimalist playback experience.

Slot types
The following core interactive area slots are built-in:

Use the default interface

If you do not configure a slot builder, the full UI is loaded by default. This is suitable for standard playback scenarios.

Widget _buildPlayWidget() {
  return AliPlayerWidget(_controller);
}

Customize specific slots

You can customize specific components as needed and keep the rest as default to reduce maintenance costs.

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: (context) => MyAppTopBar(title: 'My Video'),
    SlotType.bottomBar: (context) => MyCustomControls(),
  },
)

Customize all slots

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: (context) => CustomTop(),
    SlotType.bottomBar: (context) => CustomBottom(),
    SlotType.playControl: (context) => GestureHandler(),
    SlotType.coverImage: (context) => BrandCover(),
    SlotType.playState: (context) => ErrorOverlay(),
    SlotType.centerDisplay: (context) => VolumeIndicator(),
    SlotType.seekThumbnail: (context) => PreviewThumb(),
    SlotType.subtitle: (context) => SubtitleView(),
    SlotType.settingMenu: (context) => MySettings(),
    SlotType.overlays: (context) => [AdBanner(), Watermark()],
  },
)

Hide specific slots

Set the slot value to null to hide the corresponding area.

AliPlayerWidget(
  controller,
  slotBuilders: {
    SlotType.topBar: null,        // Hide the top bar.
    SlotType.settingMenu: null,   // Hide the settings menu.
    SlotType.centerDisplay: null, // Disable gesture feedback prompts.
  },
)

The following is a complete example:

// Hide the top and bottom bars for a cleaner interface.
AliPlayerWidget(controller, slotBuilders: {
  SlotType.topBar: null,
  SlotType.bottomBar: null,
});

// Add a custom business overlay.
AliPlayerWidget(controller, slotBuilders: {
  SlotType.overlays: (context) => MyLikeShareButtons(),
});

// Create a fully branded user interface.
AliPlayerWidget(controller, slotBuilders: {
  SlotType.topBar: (context) => MyAppTopBar(),
  SlotType.bottomBar: (context) => MyAppBottomBar(),
  SlotType.settingMenu: null, // Hide settings.
});

Multi-scenario adaptation

Supports multiple scenarios, such as VOD, live streaming, list playback, and full-screen playback.

Rich feature set

• Basic features: Provides core features such as playback control, a settings panel, thumbnail display, and definition switching to meet standard video playback requirements.

• Gesture control: Supports gesture control for brightness, volume, and playback progress. This provides an intuitive and convenient user experience.

Flexible UI customization

• Overlay support: Supports custom overlay components for high extensibility. This lets you implement complex features such as advertisements and live comments.

• Modular design: Provides built-in, reusable UI components, such as a top bar, a bottom bar, and a settings panel, to facilitate custom development.

• Full-screen adaptation: Automatically adapts to landscape and portrait mode switching to ensure an optimal display effect on different devices.

Event and status management

• Real-time status monitoring: Provides real-time data updates for playback status, video dimensions, and buffer progress to facilitate dynamic interaction.

• Event callback mechanism: Provides comprehensive event listeners for the player, including status management for playback start, pause, and completion. This helps you manage various playback scenarios.

• Logging and debugging support: Provides a detailed logging system to facilitate troubleshooting and performance optimization.

Easy to use

You can implement complex video playback features and quickly integrate them into your Flutter projects by making simple API calls.

Flexible and extensible

• The modular design supports various custom options to facilitate custom development.

• Automatically adapts to different screen sizes and resolutions to ensure a consistent user experience.

High performance and stability

• Built on the ApsaraVideo Player SDK, it provides a low-latency, high-stability video playback experience.

• The optimized architecture, lightweight components, asynchronous loading, and event-driven model ensure efficient operation and a smooth user experience.

Cross-platform support

Leverages the cross-platform capabilities of Flutter to support both Android and iOS, allowing for single-codebase development for both platforms.