Get started with the Flutter player SDK

Play a video in your Flutter app using the ApsaraVideo Player SDK. Follow these steps to create a player, set up a video view, configure a playback source, and release resources.

Prerequisites

Integrate the Flutter player SDK into your project. For instructions, see Integrate the Flutter player SDK.

Procedure

Step 1: Create a player

FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer();
fAliplayer.setTraceID("traceId");

The setTraceID parameter controls instrumentation log reporting, which powers playback quality monitoring, single-point tracking, and video playback statistics.

`setTraceID` value	Instrumentation log reporting	Available features
Not set (default)	Enabled	Playback quality monitoring, video playback statistics
A unique identifier such as a user ID, IMEI, or IDFA	Enabled	Playback quality monitoring, single-point tracking, video playback statistics
`DisableAnalytics`	Disabled	None

To use single-point tracking, pass a unique identifier for the user or device, such as your business user ID, an International Mobile Equipment Identity (IMEI), or an identifier for advertisers (IDFA).

Step 2: Set up the video view

Create an AliPlayerView widget and attach the player after the view is created.

// 1. Create the player view widget
AliPlayerView aliPlayerView = AliPlayerView(
  onCreated: onViewPlayerCreated,
  x: 0,
  y: 0,
  width: width,
  height: height,
  aliPlayerViewType: AliPlayerViewTypeForAndroid.surfaceview);

// 2. Attach the player to the view
void onViewPlayerCreated(viewId) async {
  fAliplayer.setPlayerView(viewId);
}

Step 3: Set the playback source

The SDK supports three playback source types. Choose one based on your use case.

VidAuth (recommended)

Use VidAuth for secure playback with a short-lived playback credential. Call the GetVideoPlayAuth operation of ApsaraVideo VOD to get the playAuth value.

fAliplayer.setVidAuth(
  vid: "<your-video-id>",       // Required. The video ID (VideoId).
  playAuth: "<your-play-auth>", // Required. The playback credential from GetVideoPlayAuth.
  region: "<your-region>",      // Required. The region of ApsaraVideo VOD. Default: cn-shanghai.
);

VidSts

Use VidSts for playback with temporary Security Token Service (STS) credentials. Call the AssumeRole operation of STS to get the required values.

fAliplayer.setVidSts(
  vid: "<your-video-id>",              // Required. The video ID (VideoId).
  accessKeyId: "<your-access-key-id>",         // Required. The AccessKey ID from the temporary AccessKey pair.
  accessKeySecret: "<your-access-key-secret>", // Required. The AccessKey secret from the temporary AccessKey pair.
  securityToken: "<your-security-token>",      // Required. The STS token.
  region: "<your-region>",             // Required. The region of ApsaraVideo VOD. Default: cn-shanghai.
);

UrlSource

Use UrlSource for direct URL-based playback.

fAliplayer.setUrl("<your-video-url>");

For more playback source details, see Basic features.

Step 4: Start playback

fAliplayer.prepare();
fAliplayer.play();

Step 5: Release the player

When playback ends, stop the player, release resources, and clear the reference to prevent memory leaks.

fAliplayer.stop();
fAliplayer.release();
fAliplayer = null; // Prevents memory leaks

Always call release() and set the player to null when it is no longer needed. Otherwise, memory leaks occur.

Complete example

The following example combines all steps into a complete playback flow.

// Step 1: Create a player
FlutterAliplayer fAliplayer = FlutterAliPlayerFactory.createAliPlayer();
fAliplayer.setTraceID("traceId");

// Step 2: Set up the video view
AliPlayerView aliPlayerView = AliPlayerView(
  onCreated: (viewId) async {
    fAliplayer.setPlayerView(viewId);
  },
  x: 0,
  y: 0,
  width: width,
  height: height,
  aliPlayerViewType: AliPlayerViewTypeForAndroid.surfaceview);

// Step 3: Set the playback source (VidAuth)
fAliplayer.setVidAuth(
  vid: "<your-video-id>",
  playAuth: "<your-play-auth>",
  region: "<your-region>",
);

// Step 4: Start playback
fAliplayer.prepare();
fAliplayer.play();

// Step 5: Release the player when done
fAliplayer.stop();
fAliplayer.release();
fAliplayer = null;

References

For playback control, event listeners, and other player capabilities, see Basic features.