Model Integration Guide

This plugin supports two model paths:

• official Ultralytics release assets resolved by model ID
• your own exported models loaded from assets, local files, or remote URLs

The plugin treats model metadata as the source of truth whenever it is available.

📦 Official Models

Use the default official model or a specific official model ID such as yolo26n:

final yolo = YOLO(modelPath: YOLO.defaultOfficialModel() ?? 'yolo26n');

The plugin will:

1. resolve the current platform's artifact
2. download it if needed
3. cache it in app storage
4. read metadata to determine the task when possible

To see which official IDs exist on the current platform:

final models = YOLO.officialModels();
print(models);

YOLO.officialModels() only returns real downloadable artifacts for the running platform. Official assets are downloaded on first use and cached in app storage, so model URLs stay stable across package releases and the Flutter package does not carry large model files.

Official assets are maintained as GitHub release assets:

Platform	Runtime asset	Release
Android	LiteRT w8a32 .tflite	yolo-flutter-app v0.6.6
Android NPU	QNN .onnx	yolo-flutter-app v0.6.6
iOS	Core ML int8 .mlpackage.zip	yolo-ios-app v8.3.0

URL patterns:

• Android LiteRT: https://github.com/ultralytics/yolo-flutter-app/releases/download/v0.6.6/<model>_w8a32.tflite
• Android QNN (opt-in NPU): https://github.com/ultralytics/yolo-flutter-app/releases/download/v0.6.6/<model>_v73_qnn.onnx (Snapdragon 8 Gen 2+; _v81 for 8 Elite Gen 5)
• iOS Core ML: https://github.com/ultralytics/yolo-ios-app/releases/download/v8.3.0/<model>.mlpackage.zip

The Flutter resolver uses the LiteRT release for Android and the Core ML release for Apple platforms. QNN models are not auto-resolved by model ID — pass their URL or file path explicitly; any path ending in _qnn.onnx runs on the Hexagon NPU via the ONNX Runtime QNN Execution Provider (see the README's NPU section for the required Gradle opt-in). QNN assets are nano-only and use channel-last inputs with in-graph ArgMax class maps for semantic segmentation. The native iOS app uses the same Core ML release through RemoteModels.swift. These release tags are intentionally pinned in code for reproducible first-use downloads; when official assets move to a new release, update the resolver constants, docs, and URL tests in the same PR.

Official export properties:

Property	TFLite	Core ML
Model IDs	yolo26{n,s,m,l,x}	yolo26{n,s,m,l,x}
Tasks	detect, seg, sem, depth, cls, pose, obb	detect, seg, sem, depth, cls, pose, obb
Format	.tflite	.mlpackage.zip
Quantization	w8a32 LiteRT (int8 weights, FP32 activations)	int8 Core ML
imgsz	224 cls; 640 others	224 cls; 640 others
nms	None	False
end2end metadata	False	False cls/sem/depth; True others
Calibration	None (w8a32 dynamic-range)	exporter default
Postprocessing	Android native	Swift/Core ML

Export scripts require ultralytics>=8.4.142. LiteRT uses nms=None for raw one-to-many outputs with Android-side NMS. Core ML uses nms=False for NMS-free detect, segment, pose, and OBB outputs; classification, semantic, and depth retain their native outputs. nms=True embeds NMS where supported. The end2end metadata field describes the exported graph; use nms to configure exports. Android w8a32 uses int8 weights and FP32 activations without calibration.

If you want the simplest “start from the default Ultralytics model” entry point, prefer YOLO.defaultOfficialModel().

📁 Custom Models

You can also point the plugin at your own fine-tuned exported model:

final yolo = YOLO(modelPath: 'assets/models/my-finetuned-model.tflite');

Supported sources:

• official model ID, for example yolo26n
• Flutter asset path
• local file path
• http or https URL

If the exported model metadata includes task, the plugin resolves it automatically. If metadata is missing or ambiguous, pass task explicitly:

final yolo = YOLO(
  modelPath: 'assets/models/my-finetuned-model.tflite',
  task: YOLOTask.detect,
);

🍳 Custom Model Cookbook

1. Bundled Flutter asset on Android

final yolo = YOLO(modelPath: 'assets/models/custom.tflite');

2. Bundled Flutter asset on iOS

final yolo = YOLO(modelPath: 'assets/models/custom.mlpackage.zip');

3. Model added directly to the iOS app bundle

final yolo = YOLO(modelPath: 'MyModel.mlpackage');

4. Local file already downloaded by your app

final yolo = YOLO(modelPath: file.path);

5. Remote URL resolved by the plugin

final yolo = YOLO(
  modelPath: 'https://example.com/models/custom.tflite',
  task: YOLOTask.detect,
);

Use explicit task only when the export does not include it or when you already know the metadata is missing.

🧠 Metadata Resolution

Exported metadata commonly includes:

• task
• names
• image size and stride
• author/version/export details

The plugin uses that metadata to keep the Dart API simpler:

• task can usually be omitted
• class names can come directly from the export
• model switching uses the same metadata-based resolution path

If you want to inspect a model without loading it for inference:

final info = await YOLO.inspectModel('assets/models/custom.tflite');
print(info['task']);
print(info['labels']);

🏗️ Platform Asset Placement

Android

You can use either:

• native assets in android/app/src/main/assets/
• Flutter assets such as assets/models/custom.tflite

Flutter asset models are copied into app storage automatically before loading.

iOS

You can use either:

• .mlpackage or .mlmodel files added to ios/Runner.xcworkspace
• zipped Core ML packages in Flutter assets, for example assets/models/custom.mlpackage.zip

For Flutter assets on iOS, use .mlpackage.zip so the package can unpack the model into app storage before loading it.

🍏 Core AI (Opt-In)

Core ML (.mlpackage) remains the default, and official model IDs always resolve to Core ML on iOS. Core AI (.aimodel) is an opt-in for iOS 27 and later devices: pass an .aimodel path, an .aimodel.zip Flutter asset, or an .aimodel.zip URL. It is not available on earlier iOS versions or in the iOS Simulator, where loading an .aimodel fails with a load error. The file extension is the only switch. The Ultralytics iOS app exposes the same opt-in as a Settings toggle (off by default).

// Official opt-in asset, downloaded and cached on first use
final yolo = YOLO(modelPath: 'https://github.com/ultralytics/yolo-ios-app/releases/download/v8.3.0/yolo26n.aimodel.zip');
// Your own export, bundled as a Flutter asset
final custom = YOLO(modelPath: 'assets/models/custom.aimodel.zip');

The official opt-in assets are the <model>.aimodel.zip files on the yolo-ios-app v8.3.0 release, for the same 35 model IDs as Core ML. They are FP16 and use the raw one-to-many head for detect, segment, pose, and OBB, decoded by the UltralyticsYOLO SDK's Swift NMS. To export your own, use ultralytics>=8.4.155 on macOS 26 or later with Apple silicon, then zip the .aimodel directory, keeping it as the top-level entry:

from ultralytics import YOLO

# Use 224 for classification and 640 for every other mobile task. Do not pass nms=False for Core AI.
YOLO("yolo26n.pt").export(format="coreai", quantize=16, imgsz=640)

Core AI is level with Core ML end to end, slower for semantic, depth, and CPU-only inference, and twice the download, so read the yolo-ios-app performance record for the trade-offs before opting in.

🐍 Official Asset Maintenance

Official release assets are generated from YOLO26 checkpoints with task/size loops so the app, package, and release assets use the same naming scheme.

Runtime	Existing export path	Release
LiteRT w8a32	scripts/export-tflite-models.py	yolo-flutter-app v0.6.6
QNN	Ultralytics QNN export (224 cls; 640 others)	yolo-flutter-app v0.6.6
Core ML int8	../yolo-ios-app/scripts/export-models.py	yolo-ios-app v8.3.0

scripts/export-tflite-models.py is the source of truth for Android export settings, verification, output names, and optional release upload. The Core ML counterpart in ../yolo-ios-app owns the Apple asset export settings and packaging.

Export Android LiteRT Assets

Use Linux x86 or macOS with Python ≥3.10 for LiteRT export.

uv venv --python 3.12 .venv
uv pip install --torch-backend cpu "ultralytics-opencv-headless[export-litert]>=8.4.142"
uv run python scripts/export-tflite-models.py --verify

Use --upload --repo ultralytics/yolo-flutter-app --tag v0.6.6 to replace the existing .tflite assets. The script exports YOLO26 n/s/m/l/x models for every task in its TASKS registry, including depth. Output files are written under exports/yolo26-tflite/release-assets/ and are ignored by Git. The w8a32 format (int8 weights, FP32 activations) is dynamic-range quantization, so no calibration data is required. Use Ultralytics QNN export on a supported QNN export host with ultralytics>=8.4.142 and nms=None to export the matching nano QNN assets for HTP v73 and v81. QNN uses raw one-to-many outputs with Android-side NMS; it does not support the NMS-free head or embedded NMS.

Android inference runs on LiteRT 2.x with an automatic GPU -> CPU accelerator ladder. w8a32 assets are the official download artifacts (the smallest GPU-compatible litert format); the GPU delegate compiles the whole graph on supported devices and otherwise falls back to CPU. GPU coverage still depends on the device driver and graph, so confirm delegate placement on your target hardware (the GPU delegate runs the graph in FP16):

# Requires ultralytics>=8.4.142
from ultralytics import YOLO

YOLO("yolo26n.pt").export(format="litert", nms=None, imgsz=640)
# Classification models use imgsz=224.

🔄 Switching Models

YOLO, YOLOView, and YOLOViewController.switchModel() all use the same resolver.

That means switching models supports:

• official model IDs
• asset paths
• local file paths
• remote URLs
• metadata-inferred tasks

Example:

final controller = YOLOViewController();

await controller.switchModel('yolo26n');
await controller.switchModel('assets/models/custom.tflite', YOLOTask.detect);

✅ Recommendations

• Start with YOLO.officialModels() when you want the simplest path.
• Use official IDs for the default app flow.
• Use custom models when you need a specific export or fine-tuned model.
• Prefer metadata-driven loading over hardcoded task/model tables.
• Pass task only when the export does not carry it.