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
  final result = classifier.getPerformanceClass();
  print('Performance Class: ${result.performance_class}');

  // 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']}');

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 PerformanceClassResult with the device's performance class and device information
• 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

PerformanceClassResult

class PerformanceClassResult {
  final int performance_class; // Raw enum value
  final DeviceInfo device_info;
}

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;
}

PerformanceClass Enum

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

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.