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+ 14.0+

The screenshot

Installation

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

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: ^1.0.6 // Put the latest version of the plugin.

    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

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

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"/>

  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

import 'package:byteark_player_flutter/data/byteark_player_license_key.dart';
import 'package:byteark_player_flutter/domain/byteark_player_listener.dart';
import 'package:flutter/material.dart';
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/presentation/byteark_player.dart';

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

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

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

class _MyAppState extends State<MyApp> {
  // Declare required variables
  late ByteArkPlayerItem _item;
  late ByteArkPlayerConfig _config;
  late ByteArkPlayerListener _listener;
  late ByteArkPlayer _player;

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

    // Step 1: Create a listener to handle player and ad events
    _listener = ByteArkPlayerListener(
      onPlayerReady: () {
        debugPrint("Player is ready.");
      },
      onAdsStart: (data) {
        debugPrint("Ad started. Data: ${data.toMap()}");
      },
    );

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

    // Step 3: Configure the player using ByteArkPlayerConfig
    _config = ByteArkPlayerConfig(
      // Optional : Set up ads if needed.
      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,
    );

    // Step 4: Initialize the ByteArkPlayer with the config and listener
    _player = ByteArkPlayer(playerConfig: _config, listener: _listener);
  }

  @override
  void dispose() {
    // Clean up player instance.
    _player.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 into your UI using AspectRatio
            AspectRatio(
              aspectRatio: 16 / 9,
              child: _player,
            ),
            const SizedBox(height: 16),
            // Optional: Add controls to interact with the player
            ElevatedButton(
              onPressed: () => _player.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.

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
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 in the media (in seconds).[position] is the target position in the media.
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.
currentPosition() Retrieves the current playback position in seconds.
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.
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() Gets the current time.
getDuration() Gets the duration of content.

Example usage

late ByteArkPlayerItem _item;
late ByteArkPlayerConfig _config;
late ByteArkPlayer _player;

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

  // Step 1: Define the video source using ByteArkPlayerItem
  // Replace the URL with your actual video stream URL
  _item = ByteArkPlayerItem(
    url: "https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8",
  );

  // Step 2: Configure the player with license key and video item
  // Replace license keys with your valid Android/iOS keys
  _config = ByteArkPlayerConfig(
    licenseKey: ByteArkPlayerLicenseKey(
      android: "ANDROID_KEY", // Your Android license key here
      iOS: "IOS_KEY",         // Your iOS license key here
    ),
    playerItem: _item,
  );

  // Step 3: Create the player using the config
  _player = ByteArkPlayer(playerConfig: _config);
}

// Step 4: Add player controls (e.g., play button)
ElevatedButton(
  onPressed: () {
    // Call play function to start the video
    _player.play();
  },
  child: const Text("Play"),
);

@override
void dispose() {
  // Step 5: Always dispose of the player when done to release resources
  _player.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.
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 listerner.
  late ByteArkPlayerListener _listener;

  @override
  void initState() {
    super.initState();
    
    // Step 2: Create a listener to handle player and ad events
    _listener = ByteArkPlayerListener(
      onPlayerReady: () {
        debugPrint("Player is ready.");
      },
      onAdsStart: (data) {
        debugPrint("Ad started. Data: ${data.toMap()}");
      },
    );
    
    // Step 3: add listener to ByteArkPlayer.
    _player = ByteArkPlayer(
      playerConfig: _config,
      listener: _listener,
    );

  }

Libraries

data/ads/byteark_player_ads_data
data/ads/byteark_player_ads_error_data
data/ads/byteark_player_playback_error
data/byteark_player_config
data/byteark_player_event_types
data/byteark_player_item
data/byteark_player_license_key
data/byteark_player_lighthouse_meta_data
data/byteark_player_media_track
data/byteark_player_native_event
data/byteark_player_subtitle_size
domain/byteark_player_listener
domain/event_channel/byteark_player_event_channel
domain/method_channel/byteark_player_controller
domain/method_channel/byteark_player_controller_method_channel
domain/method_channel/byteark_player_controller_platform_interface
presentation/byteark_player