Document Camera Frame #

DocumentCameraFrame is an enterprise-grade document scanner for Flutter. It bridges the gap between raw camera streams and structured data by combining real-time ML edge detection, perspective-corrected cropping, and secure on-device OCR.

💎 Premium Scanning Capabilities #

⚡ Smart Capture Engine #

Intelligent Shutter: Real-time analysis of image stability and document alignment triggers auto-capture.
Dual-Sided Workflow: Native support for multi-step scanning (e.g., ID Front → ID Back) with animated transitions.
Haptic Guidance: Integrated vibration patterns to guide users without them needing to look at the screen.

🎯 Precision Computer Vision #

ML Kit Edge Detection: Sub-millisecond boundary detection for precise document isolation.
Perspective Correction: Automatically transforms skewed or angled captures into flat, top-down professional documents.
Frame-to-Sensor Mapping: Ensures high-resolution sensor output matches the UI overlay perfectly, preventing "cutoff" edges.

🧠 On-Device Intelligence & OCR #

Privacy-First OCR: Extract text from Latin-script documents 100% offline. No API keys, no latency, no data leaks.
Context-Aware Hints: Dynamic UI prompts (e.g., "Move Closer", "Too Dark", "Centering...") to maximize first-time capture success.
Multi-Object Filtering: Smart logic to ignore background clutter and focus solely on the primary document.

🎨 Fully Decoupled UI #

Logic-Agnostic Design: The detection engine is separated from the UI, allowing you to build completely custom overlays while keeping the "brains."
Theming Engine: Full control over frame colors, stroke thickness, button styles, and hint typography.

🔐 Security & Compliance #

Offline-Only: Designed for FinTech and HealthTech—zero external network calls.
No Data Retention: Images stay in the app's sandbox; you control the lifecycle.

Demo #

Here's a quick preview of DocumentCameraFrame in action:

Auto document edge detection in real-time	Driver license dual-side capture (320×200) with auto-capture and side indicators
Passport scanning (300×450) with manual capture button, no side indicators, and custom instructions	ID card dual-side capture (320×200) with auto-capture, hidden side indicators, and smooth transitions

Features #

📸 Live Camera Preview with adjustable document frame
✂️ Custom Frame Dimensions for precise cropping
🔎 Automatic Document Detection
📢 Live Guidance Engine — Real-time alignment feedback (e.g., "Move closer", "Move right")
🔄 Dual-Side Capture Support (e.g., ID front/back)
📝 Optional on-device OCR — set enableExtractText: true to get extracted text in the save callback (no API key, no internet). OCR is Latin-only (no Arabic).
🎛️ Fully Customizable UI — titles, padding, button styles
🪝 Easy Event Callbacks — onDocumentSaved, onFrontCaptured, onBackCaptured, onRetake

Quick Start #

Installation #

Add the package to your Flutter project using:

flutter pub add document_camera_frame

Minimal Example #

import 'package:document_camera_frame/document_camera_frame.dart';
import 'package:flutter/material.dart';

class QuickExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return DocumentCameraFrame(
      frameWidth: 320,
      frameHeight: 200,
      requireBothSides: false,
      enableAutoCapture: true, // Enable automatic capture
      onDocumentSaved: (documentData) {
        print('Document saved: ${documentData.frontImagePath}');
        Navigator.pop(context);
      },
    );
  }
}

OCR (Text extraction) #

Note: OCR is Latin-only (no Arabic). The on-device ML Kit model supports English and other Latin-script languages only.

Set enableExtractText: true to run on-device text recognition after capture. The onDocumentSaved callback then receives DocumentCaptureData with:

frontImagePath / backImagePath — image file paths (unchanged)
frontOcrText / backOcrText — extracted text (when enableExtractText is true)

No API key or internet is required. OCR uses Google ML Kit and supports Latin script (English and other Latin-based languages). Arabic is not supported by the on-device model.

DocumentCameraFrame(
  frameWidth: 320,
  frameHeight: 200,
  enableExtractText: true,
  onDocumentSaved: (data) {
    print('Front text: ${data.frontOcrText}');
    print('Back text: ${data.backOcrText}');
  },
)

For custom OCR (e.g. from file paths elsewhere), use the exported OcrService class and its extractText(String imagePath) method.

Setup Requirements #

iOS Setup #

Set the minimum iOS deployment target to 15.5 or higher in your ios/Podfile:

platform :ios, '15.5'  # or newer version

Add the following keys to your ios/Runner/Info.plist file to request camera and microphone permissions:


<plist version="1.0">
    <dict>
        <!-- Add the following keys inside the <dict> section -->
        <key>NSCameraUsageDescription</key>
        <string>We need camera access to capture documents.</string>
        <key>NSMicrophoneUsageDescription</key>
        <string>We need microphone access for audio-related features.</string>
    </dict>
</plist>

Android Setup #

Update the minSdkVersion to 21 or higher in android/app/build.gradle:

android {
    defaultConfig {
        minSdk 21
    }
}

Add these permissions to your AndroidManifest.xml file:


<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera" />
    <uses-feature android:name="android.hardware.camera.autofocus" />

    <application android:label="MyApp" android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <!-- Activities and other components -->
    </application>

</manifest>

Handling Camera Access Permissions #

Permission errors may occur when initializing the camera. You must handle them appropriately. Below are the possible error codes:

Error Code	Description
`CameraAccessDenied`	User denied camera access permission.
`CameraAccessDeniedWithoutPrompt`	iOS only. User previously denied access and needs to enable it manually via Settings.
`CameraAccessRestricted`	iOS only. Camera access is restricted (e.g., parental controls).
`AudioAccessDenied`	User denied microphone access permission.
`AudioAccessDeniedWithoutPrompt`	iOS only. User previously denied microphone access and needs to enable it manually via Settings.
`AudioAccessRestricted`	iOS only. Microphone access is restricted (e.g., parental controls).

Common Use Cases #

Driver's License (Both Sides) #

DocumentCameraFrame(
  frameWidth: 320,
  frameHeight: 200,
  frontSideTitle: Text('Scan Front of License', 
    style: TextStyle(color: Colors.white)),
  backSideTitle: Text('Scan Back of License',
    style: TextStyle(color: Colors.white)),
  requireBothSides: true,
  enableAutoCapture: true, // Automatically capture when document is aligned
  onFrontCaptured: (imagePath) => print('Front: $imagePath'),
  onBackCaptured: (imagePath) => print('Back: $imagePath'),
  onDocumentSaved: (data) => handleDocument(data),
)

Passport (Single Side) #

DocumentCameraFrame(
  frameWidth: 300,
  frameHeight: 450,
  title: Text('Scan Passport', style: TextStyle(color: Colors.white)),
  requireBothSides: false,
  showSideIndicator: false,
  enableAutoCapture: false, // Manual capture only
  frontSideInstruction: "Position passport within the frame",
  onDocumentSaved: (data) => handlePassport(data),
)

ID Card with Custom Styling #

DocumentCameraFrame(
  frameWidth: 320,
  frameHeight: 200,
  requireBothSides: true,
  enableAutoCapture: true,
  captureButtonText: "Take Photo",
  saveButtonText: "Done",
  retakeButtonText: "Try Again",
  progressIndicatorColor: Colors.blue,
  outerFrameBorderRadius: 16.0,
  onDocumentSaved: (data) => processIdCard(data),
)

Widget Parameters #

Core Parameters #

Parameter	Type	Description	Required	Default Value
`frameWidth`	`double`	Width of the document capture frame.	✅	—
`frameHeight`	`double`	Height of the document capture frame.	✅	—
`enableAutoCapture`	`bool`	Enables automatic capture when a document is properly aligned in the frame.	❌	`false`
`requireBothSides`	`bool`	Whether to require both sides (if false, can save with just front side).	❌	`true`
`showCloseButton`	`bool`	Flag to control the visibility of the CloseButton (optional).	❌	`false`
`cameraIndex`	`int?`	Index to specify which camera to use (e.g., 0 for back, 1 for front) (optional).	❌	`0` (back)
`bottomFrameContainerChild`	`Widget?`	Custom content for the bottom container (optional).	❌	`null`
`bottomHintText`	`String?`	Optional bottom hint text shown in the bottom container.	❌	`null`
`sideInfoOverlay`	`Widget?`	Optional widget shown on the right (e.g. a check icon).	❌	`null`
`showDetectionStatusText`	`bool`	Show the (dynamic) live detection status text (e.g. "Move closer").	❌	`true`

Styling Classes #

Parameter	Type	Description	Required	Default Value
`animationStyle`	`DocumentCameraAnimationStyle`	Animation styling configuration for the camera widget.	❌	`DocumentCameraAnimationStyle()`
`frameStyle`	`DocumentCameraFrameStyle`	Frame styling configuration for borders and appearance.	❌	`DocumentCameraFrameStyle()`
`buttonStyle`	`DocumentCameraButtonStyle`	Button styling configuration for all buttons.	❌	`DocumentCameraButtonStyle()`
`titleStyle`	`DocumentCameraTitleStyle`	Title styling configuration for screen titles.	❌	`DocumentCameraTitleStyle()`
`sideIndicatorStyle`	`DocumentCameraSideIndicatorStyle`	Side indicator styling configuration.	❌	`DocumentCameraSideIndicatorStyle()`
`progressStyle`	`DocumentCameraProgressStyle`	Progress indicator styling configuration.	❌	`DocumentCameraProgressStyle()`
`instructionStyle`	`DocumentCameraInstructionStyle`	Instruction text styling configuration.	❌	`DocumentCameraInstructionStyle()`

Callbacks #

Parameter	Type	Description	Required	Default Value
`onFrontCaptured`	`Function(String)?`	Callback triggered when front side is captured.	❌	`null`
`onBackCaptured`	`Function(String)?`	Callback triggered when back side is captured.	❌	`null`
`onDocumentSaved`	`Function(DocumentCaptureData)?`	Callback when document is saved (one-sided e.g. passport, or both sides). One of `onDocumentSaved` or `onBothSidesSaved` required.	✅*	—
`onBothSidesSaved`	`Function(DocumentCaptureData)?`	Deprecated. Use `onDocumentSaved` instead. Still supported for backward compatibility.	✅*	—
`enableExtractText`	`bool`	When true, runs on-device OCR and sets `documentData.frontOcrText` / `backOcrText` before the callback.	❌	`false`
`onRetake`	`VoidCallback?`	Callback triggered when the "Retake" button is pressed.	❌	`null`
`onCameraError`	`void Function(Object error)?`	Callback triggered when a camera-related error occurs (e.g., initialization, streaming, or capture failure).	❌	`null`

*At least one of onDocumentSaved or onBothSidesSaved must be provided. Prefer onDocumentSaved.

Styling Classes Details #

DocumentCameraAnimationStyle #

Property	Type	Description	Default Value
`capturingAnimationDuration`	`Duration?`	Duration for the capturing animation (optional).	`null`
`capturingAnimationColor`	`Color?`	Color for the capturing animation (optional).	`null`
`capturingAnimationCurve`	`Curve?`	Curve for the capturing animation (optional).	`null`
`frameFlipDuration`	`Duration`	Duration for the flip animation between sides.	`Duration(milliseconds: 1200)`
`frameFlipCurve`	`Curve`	Curve for the flip animation between sides.	`Curves.easeInOut`