16-pipeline
The background pipeline
The pipeline is the engine that turns a folder of files into a browsable Iris library. It runs continuously and quietly in the background — you don't have to manage it, but it helps to know what it's doing.
What the pipeline does
When you add a source (see Adding sources), the pipeline begins working through every file it finds. Each file moves through a series of stages, each one doing one specific kind of work.
| Stage | What happens |
|---|---|
| Scanning | The source folder is walked recursively to discover new and changed files. |
| EXIF extraction | Embedded metadata is read: date, GPS, camera, lens, exposure settings, dimensions, duration. |
| Thumbnail generation | Preview thumbnails are rendered and cached. Used everywhere in the UI. |
| Hashing | A perceptual fingerprint is computed for duplicate detection and integrity checking. |
| ML classification | On-device ML models detect faces, generate content tags, and run OCR. |
| Transcription | If enabled, the audio of video files is transcribed to searchable text using a downloadable speech-to-text model. |
| Live Photo pairing | Live Photo still images are linked to their companion video clips. |
| Search indexing | Every metadata field is added to the full‑text search index. |
The initial scanning should take less than a few minutes, and EXIF importing should complete next. The full import process is heavily dependent on the size of your library and if the files live on your Mac's internal hard drive, and external disk, or a network drive.
Example: a full import of a 250,000 item library from an external USB drive on an M-series MacBook Pro will take 6-12 hours to complete. Smaller libraries will complete much faster.
Be patient, and feel free to leave Iris running in the background. You can close your Iris windows and the import will continue. If you quit Iris during an import, the app will attempt to continue where it left off the next time you launch Iris.
Note: Iris caches a thumbnail of each item and its metadata. Which means, after the import is complete, you can disconnect any external drives and continue using Iris uninterrupted.
Watching progress
Choose Window → Status (⌘⇧1) to open the Pipeline Status window.
It shows:
- The current phase (Scanning, Processing, Idle).
- Which stages are currently active and how many items are pending in each.
- Overall progress as a single percentage.
The window updates several times a second, so you can see the work flowing through.
A small progress indicator also appears in the toolbar whenever the pipeline is busy, so you don't need to keep the Status window open.
How long it takes
There's no single answer because the pipeline depends on:
- How many files you have
- How fast your Mac and disks are
- Whether ML tasks and transcription are enabled
Rough orders of magnitude on a modern Apple Silicon Mac:
| Library size | Scanning + EXIF + thumbnails | Full ML + transcription |
|---|---|---|
| 1,000 photos | seconds | minutes |
| 10,000 photos | a couple minutes | an hour |
| 100,000 photos | tens of minutes | less than a day |
You can use Iris normally while the pipeline runs — it's designed to stay out of the way.
When the pipeline is idle
When everything has been processed, the Status window shows Idle. Iris then periodically scans your sources for new files; when a file is added or modified, the relevant stages run automatically just for that file.
Adjusting what the pipeline does
Some stages can be turned off in Settings → Library:
- Transcribe Videos — the most expensive stage and is disabled by default. Requires a ~460 MB on‑device model download the first time it's enabled.
- Enable Face Recognition — face detection.
- Detect Text in Images — OCR.
- Tag Items — content tagging.
Turning a stage off makes the pipeline finish faster and skips that data for new items. You can turn a stage back on later and Iris will catch up by processing previously‑skipped items.