byteark_player_flutter 1.2.0 copy "byteark_player_flutter: ^1.2.0" to clipboard
byteark_player_flutter: ^1.2.0 copied to clipboard

Published 18 days ago • Latest: 2.0.1
SDKFlutter
PlatformAndroidiOS
→

Metadata

ByteArkPlayerFlutter is a Flutter plugin for the ByteArk Player, designed to enable seamless video playback and advanced player management within your Flutter applications.

More...

ByteArk Player Plugin #

Pub Version

The ByteArk Player plugin is a powerful and flexible video player package designed for seamless integration into Flutter applications. This plugin provides a smooth video playback experience, supports various media formats, and is highly customizable to suit your application's requirements. Whether you're developing a media app, an educational platform, or any project requiring video playback, ByteArk Player makes it simple to get started.

Disclaimer: This is the non-commercial version of ByteArk Player. Commercial use and/or business support requires a license. Please contact sales@byteark.com to get more information about our solutions.

Android iOS
Support SDK 21+ (compileSdk 35, AGP 8+) iOS 14.0+, Xcode 17+

The screenshot

Contents #

Installation #

Use this package to integrate the ByteArk Player plugin into your project. Follow the instructions across Flutter, Android, and iOS platforms. #

Prerequisites #

Before integrating, request the following credentials from the ByteArk team (sales@byteark.com):

  • Android and iOS license keys — passed to ByteArkPlayerLicenseKey(android: ..., iOS: ...). Without valid keys the SDK silently refuses to render the player.
  • GitLab Maven private tokens — required on Android to pull the ByteArk Player and ByteArk Lighthouse Maven repos. Stored in android/local.properties (see the Android Configuration section below).
  • SSH access to ByteArk's iOS spec repositories on GitHub — required so CocoaPods can fetch byteark-player-sdk-ios-specs and lighthouse-sdk-native-ios-specs.
  • Lighthouse projectId (optional) — only needed if you enable Lighthouse analytics via ByteArkLighthouseSetting.

Flutter Integration #

  1. Add the dependency

    1. Add the ByteArk Player plugin to your project by running this command in your terminal

      $ flutter pub add byteark_player_flutter

    This command automatically updates your pubspec.yaml file to include the ByteArk Player package and runs the flutter pub get command.


    Alternatively, you can manually add the following line in your pubspec.yaml file under dependencies

    dependencies:
  byteark_player_flutter: ^1.2.0 # Use the latest version from pub.dev.

    If you manually edited your pubspec.yaml file, you can run this command to fetch the new dependency

    $ flutter pub get

  2. Import and use ByteArk Player widget

    1. Now, you can start using the ByteArk Player plugin in your Dart code by importing it at the top of your file

      import 'package:byteark_player_flutter/presentation/byteark_player.dart';
// ...
ByteArkPlayer(playerConfig: playerConfig)

iOS Configuration #

⚠️ Xcode 17+ required. The vendor SDK (ByteArkPlayerSDK ~> 0.4.0) ships as a Swift 6.3 build, which Xcode 16 cannot type-check. If you must stay on Xcode 16, pin byteark_player_flutter: 1.1.6 in your pubspec.yaml.

To integrate ByteArk Player into your Flutter iOS project using CocoaPods, follow these steps

  1. Cocoapods will install SDK directly from Github private repository using ssh key, if you haven't set an ssh key to your Github account please follow Adding a new SSH key to your GitHub account document on Github website.

  2. Open Podfile

    1. Navigate to your iOS project directory and open the Podfile, Add the following code into the file.
# Set platform to iOS 14
platform :ios, '14.0'
# ...
# Specify the sources for CocoaPods to fetch the required dependencies:
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/byteark/byteark-player-sdk-ios-specs.git'
source 'https://github.com/byteark/lighthouse-sdk-native-ios-specs.git'

  1. Install the Pods

    1. Open a terminal window and navigate to the ios directory of your Flutter project, Run the following command to install the CocoaPods dependencies and update the repository

      pod install --repo-update

  2. Open the Workspace

    1. After running pod install --repo-update, CocoaPods will create an Xcode workspace file (.xcworkspace), Open this workspace in Xcode

  3. Build and Run

    1. After making the above changes, build and run your project on an iOS simulator or physical device to verify the integration.

Android Configuration #

⚠️ Toolchain floors. Host app must use AGP ≥ 8.6, Gradle ≥ 8.14, Kotlin ≥ 1.9, compileSdk ≥ 35, and JDK 17 for both sourceCompatibility and kotlinOptions.jvmTarget. Older toolchains will fail at Gradle sync.

To integrate ByteArk Player into your Flutter Android project, follow these steps

  1. Modify the AndroidManifest.xml

    1. Navigate to android/app/src/main/AndroidManifest.xml and apply the following changes

      1. Add required permissions for network access, foreground services, and boot reception. Add these lines inside the <manifest>

        <uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

      2. Set a theme for android:resource using the @style/Theme.AppCompat attribute inside the <activity>, This allows you to apply a theme compatible with FlutterFragmentActivity, such as @style/Theme.AppCompat or any other AppCompat-based or MaterialComponents theme.

        <meta-data
       android:name="io.flutter.embedding.android.NormalTheme"
       android:resource="@style/Theme.AppCompat"/>

      3. Add ByteArk Player Service inside the <application> to enable media browsing and service functionality

        <!-- ByteArk -->
<service android:name="com.byteark.bytearkplayercore.handler.exoplayer.service.ByteArkPlayerService"
      android:enabled="true"
      android:exported="true">
      <intent-filter>
           <action android:name="androidx.media3.session.MediaLibraryService"/>
           <action android:name="android.media.browse.MediaBrowserService" />
      </intent-filter>
</service>

      4. Add Nielsen inside the <application> to enable Nielsen service functionality

        <!--Nielsen-->
<meta-data
      android:name="com.google.android.gms.ads.APPLICATION_ID"
      android:value="ca-app-pub-3940256099942544~3347511713"/>

        ⚠️ The ID above (ca-app-pub-3940256099942544~3347511713) is Google's public sample AdMob app ID for demos. Replace it with your own AdMob app ID before shipping; apps released with the sample ID risk being flagged by Google Play.

  2. Navigate to android/app/src/main/kotlin/com/example/your_project_name/MainActivity.kt and update the main activity

    1. Extend FlutterFragmentActivity() to ensure proper integration

      import io.flutter.embedding.android.FlutterFragmentActivity
      
class MainActivity: FlutterFragmentActivity()

  3. Configure Local Properties

    1. In the android/local.properties file, set up your GitLab private tokens for ByteArk Player and ByteArk LightHouse.

    2. Add the following lines, replacing [YOUR_PRIVATE_TOKEN] with the token provided by the ByteArk team

      gitLabByteArkPlayerPrivateToken=[YOUR_PRIVATE_TOKEN]
gitLabByteArkLighthousePrivateToken=[YOUR_PRIVATE_TOKEN]

  4. Build and Run

    1. After making the above changes, build and run your project on an Android emulator or physical device to verify the integration.

Usage #

Here's a basic example of how to use ByteArk Player widget to play a video in your Flutter app

Breaking change in 1.2.0: the widget no longer exposes play(), pause(), dispose(), etc. Drive playback through a ByteArkPlayerController that you create yourself and pass to the widget. See the example below.

💡 Looking for runnable demos? The repo ships with a sample app under example/ containing screens for the basic player, the controller API, listener events, ads, multi-DRM, playlist, vertical video, seek, progress tracking, subtitle sizing, and Lighthouse analytics. Run it with cd example && flutter run after providing license keys in the example screens.

import 'package:byteark_player_flutter/data/byteark_player_config.dart';
import 'package:byteark_player_flutter/data/byteark_player_item.dart';
import 'package:byteark_player_flutter/data/byteark_player_license_key.dart';
import 'package:byteark_player_flutter/domain/byteark_player_listener.dart';
import 'package:byteark_player_flutter/domain/method_channel/byteark_player_controller.dart';
import 'package:byteark_player_flutter/presentation/byteark_player.dart';
import 'package:flutter/material.dart';

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

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late final ByteArkPlayerController _controller;
  late final ByteArkPlayerConfig _config;

  @override
  void initState() {
    super.initState();

    // Step 1: Create a controller that owns the player session, with an
    // optional listener for player and ad events.
    _controller = ByteArkPlayerController(
      listener: ByteArkPlayerListener(
        onPlayerReady: () => debugPrint('Player is ready.'),
        onAdsStart: (data) => debugPrint('Ad started: ${data.toMap()}'),
      ),
    );

    // Step 2: Define the video source.
    final item = ByteArkPlayerItem(
      url:
          'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
    );

    // Step 3: Configure the player.
    _config = ByteArkPlayerConfig(
      adsSettings: ByteArkAdsSettings(
        adTagUrl:
            'https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=',
      ),
      licenseKey: ByteArkPlayerLicenseKey(
        android: 'ANDROID_KEY', // Replace with your Android license key.
        iOS: 'IOS_KEY',         // Replace with your iOS license key.
      ),
      playerItem: item,
    );
  }

  @override
  void dispose() {
    // Step 4: Always dispose the controller you created.
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'ByteArk Player Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: const Text('ByteArk Player Demo'),
          centerTitle: true,
        ),
        body: Column(
          children: [
            // Step 5: Embed the player, passing the controller you created.
            AspectRatio(
              aspectRatio: 16 / 9,
              child: ByteArkPlayer(
                playerConfig: _config,
                controller: _controller,
              ),
            ),
            const SizedBox(height: 16),
            // Step 6: Drive playback through the controller.
            ElevatedButton(
              onPressed: _controller.pause,
              child: const Text('Pause'),
            ),
          ],
        ),
      ),
    );
  }
}

Player Configuration #

ByteArkPlayerItem #

The ByteArkPlayerItem class represents a media item to be played in the ByteArk Player. It contains essential metadata and properties necessary for configuring and displaying the media content.

class ByteArkPlayerItem {
  final String? mediaId; // A unique identifier for the media item.
  final String? posterImage; // URL of the poster image for the media item.
  final String? title; // Title of the media item.
  final String? subtitle; // Subtitle or description of the media item.
  final String? url; // URL for the media content (e.g., video or audio).
  final String? shareUrl; // URL for sharing the media item.
  final ByteArkDrm? drm; // Digital Rights Management settings for the media item.
  final ByteArkPlayerLighthouseMetaData? lighthouseMetaData; // Lighthouse metadata for tracking.
}
Property Name Type Description
mediaId String? A unique identifier for the media item, used for tracking and referencing.
posterImage String? URL of the poster image associated with the media item, used for display in the player UI.
title String? The title of the media item, which may be displayed in the player interface.
subtitle String? A subtitle or description of the media item, providing additional context to the user.
url (required) String? URL for the media content (e.g., video or live), where the player fetches the media for playback.
shareUrl String? A URL specifically for sharing the media item, allowing users to easily share content with others.
drm ByteArkDrm? Contains Digital Rights Management settings for the media item, ensuring proper content protection.
lighthouseMetaData ByteArkPlayerLighthouseMetaData? Contains Lighthouse metadata for tracking user behavior and media consumption.

ByteArkPlayerConfig #

The ByteArkPlayerConfig class is used to configure various settings and features of the ByteArk Player. Each property can be set to customize the player's behavior and appearance.

class ByteArkPlayerConfig {
  final ByteArkPlayerLicenseKey licenseKey; // The license key of the player contains both the Android and iOS keys.
  final bool? autoPlay; // Automatically start playback when the player is ready.
  final bool? control; // Show playback controls (play, pause, etc.) on the UI.
  final bool? seekButtons; // Show seek buttons for navigating the media.
  final int? seekTime; // Duration in seconds to seek forward or backward.
  final ByteArkPlayerItem? playerItem; // The media item to be played.
  final bool? fullScreenButton; // Show a button to toggle fullscreen mode.
  final bool? settingButton; // Show a settings button for player options.
  final ByteArkLighthouseSetting? lighthouseSetting; // Lighthouse tracking settings for media.
  final ByteArkAdsSettings? adsSettings; // Ads settings for handling advertisement features.
  final bool? secureSurface; // Enable a secure surface for playback (e.g., for DRM).
  final ByteArkPlayerSubtitleSize? subtitleSize; // Specifies the subtitle size.
  final bool? subtitleBackgroundEnabled; // Indicates whether the subtitle background should be enabled.
  final int? subtitlePaddingBottomPercentage; // Specifies the bottom padding for subtitles as a percentage.
}
Property Name Type Description
licenseKey (required) ByteArkPlayerLicenseKey The license key of the player contains both the Android and iOS keys.
autoPlay bool? Automatically starts playback when the player is ready. Defaults to true.
control bool? Indicates whether playback controls (play, pause, etc.) should be shown on the UI. Defaults to true.
seekButtons bool? Controls the visibility of seek buttons for navigating through the media. Defaults to true.
seekTime int? Sets the duration in seconds for seeking forward or backward. Defaults to 30.
playerItem (required) ByteArkPlayerItem? Specifies the media item to be played.
fullScreenButton bool? Indicates if a button for toggling fullscreen mode should be shown. Defaults to true.
settingButton bool? Controls the visibility of a settings button for player options. Defaults to true.
lighthouseSetting ByteArkLighthouseSetting? Contains settings for Lighthouse tracking related to media consumption.
adsSettings ByteArkAdsSettings? Contains general ad settings for the player.
secureSurface bool? Set this to true to prevent screenshot capture or video recording of a video player. Defaults to false.
subtitleSize ByteArkPlayerSubtitleSize? Defines the subtitle size, default to medium.
subtitleBackgroundEnabled bool? Specifies whether a background should be displayed behind subtitles. Defaults to true.
subtitlePaddingBottomPercentage int? (1-100) Specifies the bottom padding for subtitles as a percentage. Defaults to 10.

ByteArkPlayerLicenseKey #

The license keys required by the native SDKs. Both fields are required; pass an empty string only if you have no key for that platform (the SDK will refuse to play).

Property Type Description
android (required) String License key issued for the Android SDK.
iOS (required) String License key issued for the iOS SDK. 
final licenseKey = ByteArkPlayerLicenseKey(
  android: 'YOUR_ANDROID_LICENSE_KEY',
  iOS: 'YOUR_IOS_LICENSE_KEY',
);

ByteArkAdsSettings #

Configures IMA-based ad insertion alongside playback.

Property Type Description
adTagUrl (required) String? VAST/VMAP tag URL that returns the ad payload.
enableDefaultCompanionSlot bool? Enables the default companion ad slot.
defaultCompanionSize Pair<int, int>? Width/height of the default companion slot. 
final adsSettings = ByteArkAdsSettings(
  adTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?...',
);

ByteArkDrm #

Container for platform-specific DRM configuration. Use widevineDrm on Android, fairPlayDrm on iOS — set only the one you need.

Property Type Description
widevineDrm WidevineDrm? Android (Widevine) configuration.
fairPlayDrm FairPlayDrm? iOS (FairPlay) configuration.

WidevineDrm (Android) #

Property Type Description
licenseUrl (required) String? URL of the Widevine license server.
licenseRequestHeaders Map<String, String>? Extra HTTP headers (e.g. Authorization) sent with the license request.

FairPlayDrm (iOS) #

Property Type Description
licenseUrl (required) String? URL of the FairPlay license server.
licenseRequestHeaders Map<String, String>? Extra HTTP headers sent with the license request.
certificateUrl (required) String? URL of the FairPlay application certificate.

The deprecated cerfificateUrl parameter (legacy misspelling) is still accepted for one release and forwards to certificateUrl. Migrate when convenient.

final drm = ByteArkDrm(
  widevineDrm: WidevineDrm(
    licenseUrl: 'https://example.com/widevine/license',
    licenseRequestHeaders: {'Authorization': 'Bearer <token>'},
  ),
  fairPlayDrm: FairPlayDrm(
    licenseUrl: 'https://example.com/fairplay/license',
    certificateUrl: 'https://example.com/fairplay/certificate',
    licenseRequestHeaders: {'Authorization': 'Bearer <token>'},
  ),
);

ByteArkPlayerMediaTrack #

A track descriptor used by getAudios / getSubtitles / getResolutions and accepted by their corresponding set* methods.

Property Type Description
id String? Native track identifier.
name String? Display name (e.g. English, 720p).
language String? BCP-47 / ISO 639 language code where applicable.

Pass null to controller.setSubtitle(null) to disable subtitles.

ByteArkPlayerSubtitleSize #

Enum controlling subtitle text size, expressed as a percentage of the video height. Default is medium.

Value Size
minimum 1%
extraTiny 2%
tiny 3%
extraSmall 4%
small 5%
medium 6%
large 7%
extraLarge 8%
maximum 9%

ByteArkLighthouseSetting #

The ByteArkLighthouseSetting class is used to configure Lighthouse analytics tracking in the ByteArk Player.

Property Type Description
projectId String Required: The unique identifier for your Lighthouse project.
debug bool? Optional: Enables debug mode for Lighthouse tracking. Defaults to false.

Example usage:

final playerConfig = ByteArkPlayerConfig(
    licenseKey: ByteArkPlayerLicenseKey(android: "ANDROID_LICENSE_KEY", iOS: "IOS_LICENSE_KEY"),
    playerItem: playerItem,
    lighthouseSetting: ByteArkLighthouseSetting(
        projectId: "YOUR_PROJECT_ID",  // Required
        debug: true  // Optional
    )
);

ByteArkPlayerLighthouseMetaData #

The ByteArkPlayerLighthouseMetaData class provides detailed metadata for Lighthouse tracking.

Field Description
userId User's unique identifier
age User's age
country User's country
city User's city or province
lat User's latitude
long User's longitude
gender User's gender
nationality User's nationality
subscriptionPlan User's subscription plan
accountCreationDate User's account creation date
videoTitle Title of the video
seriesId ID of the series
seriesTitle Title of the series
season Season number
episode Episode number
subEpisode Sub-episode identifier
duration Video duration
publishedDate Video publication date
genres Video genres
rating Video rating
d1 to d10 Custom metadata fields

Example usage:

final playerItem = ByteArkPlayerItem(
    url: "YOUR_VIDEO_URL",
    lighthouseMetaData: ByteArkPlayerLighthouseMetaData(
        userId: 'user_123',
        videoTitle: 'The Great Adventure',
        // Add other metadata fields as needed
    )
);

Player APIs #

The SDK provided methods and variables that can access from ByteArkPlayer instance to control playback behavior or get information from media content.

ByteArkPlayerController #

The ByteArkPlayerController class provides an interface for controlling media playback in the ByteArk Player, This class interacts with the underlying platform-specific implementation to perform media control operations.

Function Name Description
setListener(ByteArkPlayerListener? listener) Replaces (or clears) the listener that receives player and ad events.
play() Starts or resumes media playback.
pause() Pauses the current media playback.
togglePlayback() Toggles between playing and pausing the media.
seekForward() Seeks the media forward by a preset interval.
seekBackward() Seeks the media backward by a preset interval.
seekTo(int position) Seeks to a specific position. position is in seconds.
switchMediaSource(ByteArkPlayerConfig config) Switches the current media source to a new one. config contains the configuration for the new media source.
toggleFullScreen() Toggles between fullscreen and normal display modes.
dispose() Releases resources used by the player and performs cleanup. Always call this on a controller you created.
currentPosition() Retrieves the current playback position in seconds. Returns null if unavailable.
getCurrentAudio() Gets the current audio track.
getAudios() Gets the list of available audio tracks.
setAudio(ByteArkPlayerMediaTrack track) Sets the current audio track.
getCurrentSubtitle() Gets the current subtitle.
getSubtitles() Gets the list of available subtitles.
setSubtitle(ByteArkPlayerMediaTrack? track) Sets the subtitle track. Pass null to disable subtitles.
getCurrentResolution() Gets the current resolution.
getResolutions() Gets the list of available resolutions.
setResolution(ByteArkPlayerMediaTrack track) Sets the video resolution.
getAvailablePlaybackSpeeds() Gets the available playback speeds.
getCurrentPlaybackSpeed() Gets the current playback speed.
setPlaybackSpeed(double speed) Sets the playback speed.
getCurrentTime() Current playback time in seconds. Returns 0 if the native side has no value yet.
getDuration() Total media duration in seconds. Returns 0 if the native side has no value yet.

Example usage #

late ByteArkPlayerItem _item;
late ByteArkPlayerConfig _config;
late ByteArkPlayerController _controller;

@override
void initState() {
  super.initState();

  // Step 1: Define the video source.
  _item = ByteArkPlayerItem(
    url: 'https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8',
  );

  // Step 2: Configure the player.
  _config = ByteArkPlayerConfig(
    licenseKey: ByteArkPlayerLicenseKey(
      android: 'ANDROID_KEY',
      iOS: 'IOS_KEY',
    ),
    playerItem: _item,
  );

  // Step 3: Create the controller. Pass it to a ByteArkPlayer widget below.
  _controller = ByteArkPlayerController();
}

// Step 4: Mount the widget with the controller attached.
ByteArkPlayer(playerConfig: _config, controller: _controller);

// Step 5: Add player controls that drive the controller.
ElevatedButton(
  onPressed: _controller.play,
  child: const Text('Play'),
);

@override
void dispose() {
  // Step 6: Always dispose the controller you created.
  _controller.dispose();
  super.dispose();
}

ByteArkPlayerEventChannel #

This section sets up an event listener to handle various events emitted by the ByteArk Player. The listener subscribes to a stream (ByteArkPlayerEventChannel.stream) and reacts to different events, which correspond to changes in the player's state, such as playback actions, fullscreen changes, or errors. Each event is identified by an enum value from ByteArkPlayerEventTypes

Event Description
onPlayerReady Triggered when the player is ready for interaction.
onPlayerLoadingMetadata Triggered when the player starts loading media metadata.
onPlaybackFirstPlay Triggered when the media starts playing for the first time.
onPlaybackPlay Triggered when the media playback resumes.
onPlaybackPause Triggered when the media playback is paused.
onPlaybackSeeking Triggered when seeking in the media begins.
onPlaybackSeeked Triggered when the seek operation completes.
onPlaybackEnded Triggered when the media playback reaches the end.
onPlaybackTimeupdate Triggered at regular intervals to update the current playback time.
onPlaybackBuffering Triggered when the media enters a buffering state.
onPlaybackBuffered Triggered when buffering completes.
onPlaybackError Triggered when a playback error occurs.
onPlayerEnterFullscreen Triggered when the player enters fullscreen mode.
onPlayerExitFullscreen Triggered when the player exits fullscreen mode.
onPlayerEnterPictureInPictureMode Triggered when the player enters Picture-in-Picture mode.
onPlayerExitPictureInPictureMode Triggered when the player exits Picture-in-Picture mode.
onPlaybackResolutionChanged Triggered when the playback resolution changes.
onPlaybackPlaylistItemChanged Triggered when the playlist advances to a new item.
onAdsRequest An ad request.
onAdsBreakStart An ad break starts (multiple ads may play in sequence).
onAdsBreakEnd An ad break ends.
onAdsStart (return ByteArkPlayerAdsData) An ad starts playing.
onAdsImpressed (return ByteArkPlayerAdsData) An impression is recorded for the ad.
onAdsCompleted (return ByteArkPlayerAdsData) An ad finishes playing.
onAdsFirstQuartile (return ByteArkPlayerAdsData) The first 25% of the ad has been played.
onAdsMidPoint (return ByteArkPlayerAdsData) 50% of the ad has been played.
onAdsThirdQuartile (return ByteArkPlayerAdsData) 75% of the ad has been played.
onAdsClicked (return ByteArkPlayerAdsData) The user clicks on the ad.
onAdsSkipped (return ByteArkPlayerAdsData) The user skips the ad.
onAllAdsCompleted All ads in the ad break have finished playing.
onAdsError (return ByteArkPlayerAdsErrorData) An error occurs in the ad manager.

Example usage #

  // Step 1: Declare a controller.
  late ByteArkPlayerController _controller;

  @override
  void initState() {
    super.initState();

    // Step 2: Create a listener and bind it to the controller. You can also
    // assign or replace the listener later via _controller.setListener(...).
    _controller = ByteArkPlayerController(
      listener: ByteArkPlayerListener(
        onPlayerReady: () => debugPrint('Player is ready.'),
        onAdsStart: (data) => debugPrint('Ad started: ${data.toMap()}'),
      ),
    );
  }

  // Step 3: Pass the controller to the widget when you build it.
  ByteArkPlayer(playerConfig: _config, controller: _controller);

Multiple players #

The plugin supports more than one ByteArkPlayer instance on screen at the same time. Each ByteArkPlayerController carries its own playerId; the controller filters incoming events so each listener fires only for the player it was attached to.

The rules:

  • Create one controller per widget. Never share a controller between two ByteArkPlayer widgets, and never omit controller: for two widgets that need to be independent.
  • Each controller owns its dispose(). When a screen tears down, dispose every controller you created. Skipping one leaks the native session.
  • The event channel is broadcast. All controllers subscribe to the same underlying native stream, then filter by playerId. Performance is fine for the small handful of concurrent players a typical screen needs.
final controllerA = ByteArkPlayerController(listener: listenerForA);
final controllerB = ByteArkPlayerController(listener: listenerForB);

// In build():
Column(
  children: [
    ByteArkPlayer(playerConfig: configA, controller: controllerA),
    ByteArkPlayer(playerConfig: configB, controller: controllerB),
  ],
);

// In dispose():
controllerA.dispose();
controllerB.dispose();

Migrating from 1.1.x #

In 1.2.0, playback control moved off the widget and onto a ByteArkPlayerController. The widget no longer exposes play(), pause(), seekTo(), dispose(), etc. The mechanical change in your host app is:

+ import 'package:byteark_player_flutter/domain/method_channel/byteark_player_controller.dart';

- late ByteArkPlayer _player;
+ late ByteArkPlayerController _controller;

  @override
  void initState() {
    super.initState();
-   _player = ByteArkPlayer(playerConfig: _config, listener: _listener);
+   _controller = ByteArkPlayerController(listener: _listener);
  }

  @override
  void dispose() {
-   _player.dispose();
+   _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ByteArkPlayer(
      playerConfig: _config,
+     controller: _controller,
    );
  }

Every _player.method(...) call on the widget becomes _controller.method(...) on the controller. The full method surface (play, pause, togglePlayback, seekForward, seekBackward, seekTo, switchMediaSource, toggleFullScreen, getAudios, setAudio, getCurrentTime, getDuration, …) is unchanged — only the call target moved.

Other things to know when upgrading:

  • Xcode 17+ is required because of the bumped vendor SDK. Hosts on Xcode 16 should pin to 1.1.6.
  • Android toolchain floors raised: AGP 8.3, Kotlin 1.9, compileSdk 35, JVM 17. Update your host app's build.gradle accordingly.
  • The previously-misspelled FairPlayDrm.cerfificateUrl field is now certificateUrl. The old name still works for one release as a deprecated alias.
  • onPlaybackResolutionChanged and onPlaybackPlaylistItemChanged listeners now actually fire (they were silently dropped before).

See the CHANGELOG for the full list of fixes shipped with 1.2.0.

Troubleshooting #

"Player area is blank, no error" #

The most common cause is empty licenseKey strings — the SDK refuses to render anything when the keys are empty. Set real values on ByteArkPlayerLicenseKey(android: ..., iOS: ...).

iOS build fails with "main actor-isolated instance method 'play()' has different actor isolation" or "this SDK is not supported by the compiler" #

The vendor ByteArkPlayerSDK xcframework was built with a specific Swift toolchain (currently Swift 6.3.2 / Xcode 17). Hosts on an older Xcode hit a swiftinterface mismatch.

  • Fix: upgrade to Xcode 17 or newer, OR pin the plugin to byteark_player_flutter: 1.1.6 until you can upgrade.

pod install fails fetching ByteArkPlayerSDK or ByteArkPlayerSDKLighthousePlugin #

CocoaPods pulls these from private GitHub spec repos (byteark/byteark-player-sdk-ios-specs, byteark/lighthouse-sdk-native-ios-specs) over SSH.

  • Ensure your SSH key is added to your GitHub account and that the ByteArk team has granted your account access to those repos.
  • Verify the source lines in your Podfile match the ones in the iOS Configuration section above.

The plugin's android/build.gradle reads two GitLab Maven tokens from android/local.properties:

gitLabByteArkPlayerPrivateToken=...
gitLabByteArkLighthousePrivateToken=...
  • Make sure both lines exist in android/local.properties (this file is gitignored — it must be created on every developer machine and on CI).
  • Request the tokens from the ByteArk team if you don't have them.

Android build fails with "Your project's Android Gradle Plugin version is lower than Flutter's minimum supported version" #

You're below the toolchain floors. Bump to AGP 8.6+ / Gradle 8.14+ / Kotlin 1.9+ / compileSdk 35 / JDK 17 as listed at the top of the Android Configuration section.

Two ByteArkPlayer widgets on screen — listeners fire for the wrong player #

Each ByteArkPlayerController is scoped by its own playerId. As long as every widget receives its own controller (ByteArkPlayer(controller: controllerA) vs ByteArkPlayer(controller: controllerB)), events stay isolated. Sharing one controller between two widgets, or omitting the controller parameter for both, will cross-fire events.

Need help? #

Contact sales@byteark.com for licensing/credential issues, or open an issue in the project tracker for plugin-level bugs.

← Metadata

5
likes
150
points
249
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Metadata

ByteArkPlayerFlutter is a Flutter plugin for the ByteArk Player, designed to enable seamless video playback and advanced player management within your Flutter applications.

Homepage

License

BSD-3-Clause (license)

Dependencies

flutter, plugin_platform_interface, uuid

More

Packages that depend on byteark_player_flutter

Packages that implement byteark_player_flutter

Back