performance_class

A Flutter FFI plugin for Android device performance classification.

Overview

This plugin analyzes Android devices and classifies them into performance categories based on various hardware and software factors including:

  • CPU cores and frequency
  • Memory capacity
  • Android version
  • Media performance class (Android 12+)

⚠️ Important: This plugin is designed specifically for Android devices only. It will not provide accurate performance classification on other platforms.

Performance Classes

The plugin classifies devices into four performance categories:

  • Unknown: Unable to determine performance class
  • Low: Low-end devices with limited resources
  • Average: Mid-range devices with moderate performance
  • High: High-end devices with excellent performance

Installation

Add this dependency to your pubspec.yaml:

dependencies:
  performance_class: ^1.0.0

Usage

Basic Usage

import 'package:performance_class/performance_class.dart';

void main() {
  final classifier = PerformanceClassifier.instance;

  // Get performance class as enum
  final performanceClass = classifier.getPerformanceClass();
  print('Performance Class: ${performanceClass.name}'); // e.g., "PERFORMANCE_CLASS_HIGH"

  // Get human-readable string
  final displayName = classifier.getPerformanceClassString(performanceClass);
  print('Display Name: $displayName'); // e.g., "High"

  // Get device information
  final deviceInfo = classifier.getDeviceInfo();
  print('CPU Cores: ${deviceInfo.cpu_count}');
  print('Memory: ${deviceInfo.memory_class_mb} MB');
}

Detailed Device Information

final classifier = PerformanceClassifier.instance;
final detailedInfo = classifier.getDetailedDeviceInfo();

print('Performance Class: ${detailedInfo['performanceClass']}');
print('Android Version: ${detailedInfo['androidVersion']}');
print('CPU Cores: ${detailedInfo['cpuCount']}');
print('Memory: ${detailedInfo['memoryClassMb']} MB');
print('Max CPU Frequency: ${detailedInfo['maxCpuFreqMhz']} MHz');
print('Is High-End: ${detailedInfo['isHighEnd']}');
print('Is Low-End: ${detailedInfo['isLowEnd']}');

Using Performance Class Enum

import 'package:performance_class/performance_class.dart';

final classifier = PerformanceClassifier.instance;
final performanceClass = classifier.getPerformanceClass();

// Direct enum comparison
if (performanceClass == PerformanceClass.PERFORMANCE_CLASS_HIGH) {
  print('This is a high-end device!');
} else if (performanceClass == PerformanceClass.PERFORMANCE_CLASS_LOW) {
  print('This is a low-end device');
}

// Switch statement
switch (performanceClass) {
  case PerformanceClass.PERFORMANCE_CLASS_UNKNOWN:
    print('Unable to determine performance class');
    break;
  case PerformanceClass.PERFORMANCE_CLASS_LOW:
    print('Low performance device');
    break;
  case PerformanceClass.PERFORMANCE_CLASS_AVERAGE:
    print('Average performance device');
    break;
  case PerformanceClass.PERFORMANCE_CLASS_HIGH:
    print('High performance device');
    break;
}

CPU Frequency Reading

final classifier = PerformanceClassifier.instance;
final cpuFreq = classifier.readAverageMaxCpuFreq(4); // Check 4 CPU cores

if (cpuFreq != -1) {
  print('Average Max CPU Frequency: $cpuFreq MHz');
} else {
  print('Unable to read CPU frequency');
}

API Reference

PerformanceClassifier

Singleton class that provides performance classification functionality.

Methods

  • getPerformanceClass(): Returns a PerformanceClass enum value representing the device's performance category
  • getDeviceInfo(): Returns a DeviceInfo structure with detailed device capabilities
  • readAverageMaxCpuFreq(int cpuCount): Reads CPU frequency from system files (Android only)
  • getPerformanceClassString(PerformanceClass): Converts performance class enum to human-readable string
  • getDetailedDeviceInfo(): Returns a map with comprehensive device information

Data Structures

PerformanceClass Enum

enum PerformanceClass {
  PERFORMANCE_CLASS_UNKNOWN(0),
  PERFORMANCE_CLASS_LOW(1),
  PERFORMANCE_CLASS_AVERAGE(2),
  PERFORMANCE_CLASS_HIGH(3);
}

DeviceInfo

class DeviceInfo {
  final int android_version;
  final int cpu_count;
  final int memory_class_mb;
  final int max_cpu_freq_mhz;
  final int media_performance_class;
}

Classification Algorithm

The plugin uses a multi-tiered approach to classify device performance:

  1. Android 12+ (API 31+): Uses the system's media_performance_class property when available
  2. Fallback Algorithm: Analyzes hardware specifications:
    • Low: Android < 26, ≤4 CPU cores, ≤2GB RAM, or ≤1.5GHz CPU
    • Average: ≤6 CPU cores, ≤4GB RAM, or ≤2.5GHz CPU
    • High: All other devices

Platform Support

  • Android: ✅ Full support with native performance analysis
  • iOS: ❌ Not supported (returns default values)
  • Linux: ❌ Not supported (returns default values)
  • Windows: ❌ Not supported (returns default values)
  • macOS: ❌ Not supported (returns default values)

Note: This plugin is specifically designed for Android devices. While it may compile and run on other platforms, it will not provide accurate performance classification and should only be used on Android devices.

Building

Regenerating FFI Bindings

If you modify the C header file (src/performance_class.h), regenerate the Dart bindings:

dart run ffigen --config ffigen.yaml

Building Native Code

The plugin automatically builds native code for Android:

  • Android: Uses Android NDK via Gradle

Example

See the example/ directory for a complete Flutter application demonstrating the plugin's capabilities.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Libraries

performance_class
performance_class_bindings_generated