What Iris does
A single tool that replaces manual file browsing with AI-powered intelligence.
Semantic text search
Describe what you're looking for in natural language. CLIP embeddings find visual matches even without keyword overlap.
Visual similarity search
Upload a reference image and find visually similar files across your entire library instantly.
Semantic audio search
Search audio files by describing the sound in text — "male voice speaking", "electronic music". CLAP embeddings bridge text and audio semantics.
OCR
EasyOCR extracts text from images — memes, screenshots, documents — and makes it searchable.
AI captions
Florence-2-large describes scene content, objects, and context to enrich search signals.
Speech transcription
OpenAI Whisper transcribes audio and video files. Search spoken content the same way you search images.
Concept recognition
Teach Iris to recognize specific people, characters, or objects using a few reference images. It auto-tags your library.
Web enrichment
Reverse-image lookup via Google Lens, then an LLM distills character, source work, and tags from the results — applied after human review.
Auto-metadata & album suggestions
Reads EXIF date, GPS, and source app from files at import and suggests collections to group them — handy for photo libraries.
Collections & albums
Organize files into named albums. Assign during import or add later from search results.
Duplicate detection
Hash-exact, Chromaprint acoustic fingerprinting, and visual near-duplicate detection with centroid-based cluster filtering. Review and send duplicates to system trash safely.
Multi-frame video embeddings
Videos are indexed by averaging 6 CLIP embeddings across evenly-spaced frames. Trims, re-encodes, and resolution changes are detected reliably.
Deleted file registry
SHA-256 and perceptual hashes of trashed files are stored. Re-importing the same files is silently skipped — deleted content stays deleted.
Background indexing
Import thousands of files without blocking the UI. Search and browse while indexing runs in the background.
Supported formats
Drop in any of these and Iris handles the rest.
Installation
One server holds your originals and runs the AI; the browser and the Android app connect to it. It ships as a Docker image, so the server needs Docker — not Python or CUDA.
Requirements
| Component | Minimum | Recommended |
|---|---|---|
| OS | Linux x86_64 | Linux x86_64 |
| Software | Docker + Compose v2, git, curl | — |
| RAM | 8 GB | 16 GB+ |
| GPU | — | NVIDIA RTX 20+ (driver ≥ 580, NVIDIA Container Toolkit) |
| Disk (models) | ~10 GB | + a second disk for backups |
Download and install the server
git clone https://github.com/MiguelLopesDel/Iris.git cd Iris ./scripts/server.sh install # detects an NVIDIA GPU by itself
Create the administrator account
Finish setup in the browser: http://127.0.0.1:8501/setup Installation code: K7QM-4XPA
Open the /setup page, type the installation code the installer printed, and choose the administrator's username and password. Then create the other accounts in Sistema.
Reach it from your devices
sudo tailscale serve --bg http://127.0.0.1:8501
Iris listens only on 127.0.0.1. Publish it with the private layer you prefer — Tailscale, ZeroTier, WireGuard or a reverse proxy with TLS — and use that address in the browser or the Android app.
Updates, backups and every option: server guide.
Concept recognition
Teach Iris to recognize any visual entity using a handful of reference images.
Open the Concepts tab and click "Create new concept"
Give it a name and category: Person, Character, Place, Object, Animal, or Other.
Upload 2–5 reference images
Clear, varied images of the subject give better results. Iris embeds them with CLIP.
Click "Find auto matches"
Iris scans the library and proposes candidates ranked by visual similarity to the centroid of your references.
Review and apply
Reject false positives, then click Apply. Confirmed matches are stored and excluded from future auto-match runs.
Search by name
Type the concept name in the search box. Iris uses the visual embedding of the concept — not text matching — to retrieve results.
Architecture
Fully local stack — no cloud APIs, no telemetry.
Hybrid search weights
| Parameter | Default | Description |
|---|---|---|
balance | 0.65 | Weight between visual CLIP score (1.0) and description/text score (0.0) |
text_bonus | 1.0 | Multiplier applied when query terms match OCR/caption text lexically |
lexical_weight | 0.0 | Weight of pure lexical (BM25-style) scoring |
Override defaults by placing data/best_weights.json in the project root, or run python scripts/optimize.py to tune weights automatically.
CLI reference
python -m core.indexer \ --dir /path/to/media \ --db data/library.db \ --device cuda \ --recursive \ --batch-size 8
python -m core.indexer \ --dir /path/to/media \ --db data/library.db \ --clap-model laion/larger_clap_music_and_speech
python -m core.indexer \ --dir /path/to/media \ --db data/library.db \ --caption-model none \ --whisper-model none
python -m core.indexer --db data/library.db --rebuild-faiss-only
python scripts/find_duplicates.py \ --db data/library.db \ --media-root media \ --threshold 0.985
License
Iris is source-available under the Iris Non-Commercial Personal-Use License.
You may use it and create your own forks for personal, non-commercial use, as long as you credit the author.
Selling Iris or any fork is not permitted; the author retains ownership and may revoke the license at any time.