Ultra QR Scanner 📱⚡ #

Ultra-fast, low-latency QR code scanner plugin for Flutter with native performance optimization.

🎯 Goal: Open scanner → detect QR instantly → return result → done ✅

✨ Features #

🚀 Ultra-fast startup - Preload scanner during app initialization for instant access
⚡ Native performance - CameraX (Android) + AVCapture (iOS) for maximum speed
📱 Simple API - Single scan or continuous stream modes
🛡️ Production ready - Comprehensive error handling & memory management

🚀 Performance Optimizations #

📊 Benchmarks #

🛠 Installation #

Add to your pubspec.yaml:

dependencies:
  ultra_qr_scanner: ^1.0.0

flutter pub get

🏃‍♂️ Quick Start #

1. Request Permissions & Prepare Scanner #

import 'package:ultra_qr_scanner/ultra_qr_scanner.dart';

// Best practice: Call during app initialization
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Request camera permission
  final hasPermission = await UltraQrScanner.requestPermissions();
  
  if (hasPermission) {
    // Preload scanner for ultra-fast access
    await UltraQrScanner.prepareScanner();
  }
  
  runApp(MyApp());
}

2. Single QR Scan (Recommended for most use cases) #

Future<void> scanQRCode() async {
  try {
    final qrCode = await UltraQrScanner.scanOnce();
    if (qrCode != null) {
      print('Scanned QR Code: $qrCode');
      // Process your QR code here
    }
  } catch (e) {
    print('Scan failed: $e');
  }
}

3. Continuous Scanning Stream #

StreamSubscription<String>? _scanSubscription;

void startContinuousScanning() {
  _scanSubscription = UltraQrScanner.scanStream().listen(
    (qrCode) {
      print('Detected QR Code: $qrCode');
      // Handle each QR code as it's detected
    },
    onError: (error) {
      print('Scan error: $error');
    },
  );
}

void stopScanning() {
  _scanSubscription?.cancel();
  UltraQrScanner.stopScanner();
}

🎨 Using the Widget #

Basic Usage #

import 'package:ultra_qr_scanner/ultra_qr_scanner_widget.dart';

class QRScannerPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: UltraQrScannerWidget(
        onQrDetected: (qrCode) {
          print('QR Code detected: $qrCode');
          Navigator.pop(context, qrCode);
        },
      ),
    );
  }
}

Advanced Widget Usage #

UltraQrScannerWidget(
  onQrDetected: (qrCode) {
    // Handle QR code detection
    _handleQRCode(qrCode);
  },
  showFlashToggle: true,  // Show flash button
  autoStop: true,         // Auto-stop after first detection
  overlay: CustomOverlayWidget(), // Your custom overlay
)

Custom Overlay Example #

Widget buildCustomOverlay() {
  return Stack(
    children: [
      // Semi-transparent background
      Container(color: Colors.black54),
      
      // Scanning area cutout
      Center(
        child: Container(
          width: 250,
          height: 250,
          decoration: BoxDecoration(
            border: Border.all(color: Colors.green, width: 3),
            borderRadius: BorderRadius.circular(16),
          ),
        ),
      ),
      
      // Instructions
      Positioned(
        bottom: 100,
        left: 0,
        right: 0,
        child: Text(
          'Align QR code within the frame',
          textAlign: TextAlign.center,
          style: TextStyle(
            color: Colors.white,
            fontSize: 18,
            fontWeight: FontWeight.bold,
          ),
        ),
      ),
    ],
  );
}

🔧 Advanced Usage #

Flash Control #

// Toggle flashlight
await UltraQrScanner.toggleFlash(true);  // Turn on
await UltraQrScanner.toggleFlash(false); // Turn off

Pause/Resume Detection #

// Pause detection (keeps camera active)
await UltraQrScanner.pauseDetection();

// Resume detection
await UltraQrScanner.resumeDetection();

Check Scanner Status #

// Check if scanner is prepared and ready
if (UltraQrScanner.isPrepared) {
  // Ready to scan
  final result = await UltraQrScanner.scanOnce();
} else {
  // Need to prepare first
  await UltraQrScanner.prepareScanner();
}

🔒 Permissions Setup #

Android #

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

iOS #

Add to ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required to scan QR codes</string>

📱 Platform Support #

🎯 Complete Example App #

import 'package:flutter/material.dart';
import 'package:ultra_qr_scanner/ultra_qr_scanner.dart';
import 'package:ultra_qr_scanner/ultra_qr_scanner_widget.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize scanner on app startup for best performance
  final hasPermission = await UltraQrScanner.requestPermissions();
  if (hasPermission) {
    await UltraQrScanner.prepareScanner();
  }
  
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Ultra QR Scanner Demo',
      home: HomePage(),
    );
  }
}

class HomePage extends StatefulWidget {
  @override
  _HomePageState createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  String? lastQRCode;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Ultra QR Scanner'),
        centerTitle: true,
      ),
      body: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          // Display last scanned QR code
          if (lastQRCode != null)
            Container(
              margin: EdgeInsets.all(20),
              padding: EdgeInsets.all(16),
              decoration: BoxDecoration(
                color: Colors.green.shade50,
                border: Border.all(color: Colors.green),
                borderRadius: BorderRadius.circular(8),
              ),
              child: Column(
                children: [
                  Text(
                    'Last Scanned QR Code:',
                    style: TextStyle(
                      fontWeight: FontWeight.bold,
                      fontSize: 16,
                    ),
                  ),
                  SizedBox(height: 8),
                  Text(
                    lastQRCode!,
                    style: TextStyle(fontSize: 14),
                    textAlign: TextAlign.center,
                  ),
                ],
              ),
            ),
          
          // Action buttons
          Padding(
            padding: EdgeInsets.all(20),
            child: Column(
              children: [
                SizedBox(
                  width: double.infinity,
                  child: ElevatedButton.icon(
                    onPressed: _scanOnce,
                    icon: Icon(Icons.qr_code_scanner),
                    label: Text('Scan QR Code'),
                    style: ElevatedButton.styleFrom(
                      padding: EdgeInsets.all(16),
                    ),
                  ),
                ),
                SizedBox(height: 16),
                SizedBox(
                  width: double.infinity,
                  child: OutlinedButton.icon(
                    onPressed: _openContinuousScanner,
                    icon: Icon(Icons.camera_alt),
                    label: Text('Continuous Scanner'),
                    style: OutlinedButton.styleFrom(
                      padding: EdgeInsets.all(16),
                    ),
                  ),
                ),
              ],
            ),
          ),
          
          // Performance info
          Expanded(
            child: Container(
              margin: EdgeInsets.all(20),
              padding: EdgeInsets.all(16),
              decoration: BoxDecoration(
                color: Colors.blue.shade50,
                borderRadius: BorderRadius.circular(8),
              ),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
                    '⚡ Performance Features:',
                    style: TextStyle(
                      fontWeight: FontWeight.bold,
                      fontSize: 16,
                    ),
                  ),
                  SizedBox(height: 12),
                  Text('✅ Ultra-fast startup with preloading'),
                  Text('✅ Native camera performance'),
                  Text('✅ MLKit/Vision API optimization'),
                  Text('✅ Frame throttling for battery efficiency'),
                  Text('✅ Background processing threads'),
                  Text('✅ Auto-stop on detection'),
                  Text('✅ 640x480 resolution for speed'),
                  Text('✅ Memory leak prevention'),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }

  Future<void> _scanOnce() async {
    try {
      final qrCode = await UltraQrScanner.scanOnce();
      if (qrCode != null) {
        setState(() {
          lastQRCode = qrCode;
        });
        
        // Show success message
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            content: Text('QR Code scanned successfully!'),
            backgroundColor: Colors.green,
          ),
        );
      }
    } catch (e) {
      // Show error message
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text('Scan failed: $e'),
          backgroundColor: Colors.red,
        ),
      );
    }
  }

  void _openContinuousScanner() {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => ContinuousScannerPage(
          onQrDetected: (qrCode) {
            setState(() {
              lastQRCode = qrCode;
            });
          },
        ),
      ),
    );
  }
}

class ContinuousScannerPage extends StatelessWidget {
  final Function(String) onQrDetected;

  const ContinuousScannerPage({
    Key? key,
    required this.onQrDetected,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('QR Scanner'),
        backgroundColor: Colors.transparent,
        elevation: 0,
      ),
      extendBodyBehindAppBar: true,
      body: UltraQrScannerWidget(
        onQrDetected: (qrCode) {
          onQrDetected(qrCode);
          Navigator.pop(context);
          
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text('Scanned: $qrCode'),
              backgroundColor: Colors.green,
            ),
          );
        },
        showFlashToggle: true,
        autoStop: true,
      ),
    );
  }
}

🔍 Error Handling #

try {
  await UltraQrScanner.prepareScanner();
  final result = await UltraQrScanner.scanOnce();
  // Handle success
} on UltraQrScannerException catch (e) {
  // Handle scanner-specific errors
  print('Scanner error: ${e.message}');
} catch (e) {
  // Handle other errors
  print('General error: $e');
}

🚀 Performance Tips #

1. Initialize Early #

// ✅ GOOD: Initialize during app startup
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await UltraQrScanner.prepareScanner();
  runApp(MyApp());
}

// ❌ BAD: Initialize when needed
void scanQR() async {
  await UltraQrScanner.prepareScanner(); // Adds 200ms delay
  final result = await UltraQrScanner.scanOnce();
}

2. Use Single Scan for One-time Use #

// ✅ GOOD: For single scans
final qrCode = await UltraQrScanner.scanOnce();

// ❌ LESS EFFICIENT: Stream for single scan
final stream = UltraQrScanner.scanStream();
final qrCode = await stream.first;

3. Clean Up Resources #

// ✅ GOOD: Always clean up
@override
void dispose() {
  UltraQrScanner.stopScanner();
  super.dispose();
}

🐛 Troubleshooting #

Common Issues #

1. Camera Permission Denied

// Check and request permissions
final hasPermission = await UltraQrScanner.requestPermissions();
if (!hasPermission) {
  // Show permission dialog or redirect to settings
}

2. Scanner Not Prepared

// Always check if prepared
if (!UltraQrScanner.isPrepared) {
  await UltraQrScanner.prepareScanner();
}

3. Camera Already in Use

// Stop scanner before starting new session
await UltraQrScanner.stopScanner();
await UltraQrScanner.scanOnce();

Platform-Specific Issues #

Android:

• Ensure minSdkVersion is at least 21
• Add camera permission to AndroidManifest.xml
• ProGuard: Add keep rules for MLKit if using code obfuscation

iOS:

• Add camera usage description to Info.plist
• Ensure deployment target is iOS 11.0+
• Test on physical device (camera not available in simulator)

📈 Changelog #

[1.0.0] - 2024-01-XX #

• 🎉 Initial release
• ⚡ Ultra-fast QR code scanning
• 📱 Native performance optimization
• 🔋 Battery efficient frame throttling
• 🎨 Customizable scanner widget
• 🛡️ Comprehensive error handling
• 📊 Performance benchmarking
• 🧪 Extensive test coverage

🤝 Contributing #

We welcome contributions! Please see our Contributing Guide for details.

Development Setup #

git clone https://github.com/yourusername/ultra_qr_scanner.git
cd ultra_qr_scanner
flutter pub get
cd example
flutter run

Running Tests #

# Unit tests
flutter test

# Integration tests
flutter drive --target=test_driver/integration_test.dart

# Performance tests
flutter drive --target=test_driver/performance_test.dart

📄 License #

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

🙏 Acknowledgments #

• MLKit for Android barcode scanning
• Vision Framework for iOS barcode detection
• CameraX for Android camera handling
• AVFoundation for iOS camera management

📞 Support #

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email: [email protected]