Universal File Metadata Manager — read, edit, delete and compare metadata across all major file formats, offline by default.
Tip
💡 No account, no cloud, no setup. Download a binary, double-click, and start browsing. MetaLens never touches the network unless you ask it to check for a new version (see Privacy & Security).
| 📄 Document | 📝 Purpose |
|---|---|
| 📋 REQUIREMENTS.md | System requirements and prerequisites |
| 🚀 INSTALLATION.md | Step-by-step installation & build-from-source |
| 📖 USAGE.md | How to use the application |
| 📡 API.md | Sidecar REST API reference for developers |
- Grab the latest installer for your platform from Releases
- Run it — Windows SmartScreen may warn since the build is unsigned; click "More info" → "Run anyway"
- MetaLens opens with a folder tree on the left — click a folder, then a file, to see its metadata
⏱️ No install wait, no dependency download. Python and Node.js are bundled into the binary — nothing to set up.
Important
✅ For full details, see INSTALLATION.md
File (image / audio / video / document / anything)
│
▼
┌─────────────────────────────────────────────┐
│ 🖼️ Images → EXIF, XMP, IPTC, ICC, RAW │
│ 🎵 Audio → ID3, Vorbis, ASF, APEv2, MP4 │
│ 🎬 Video → MP4/MOV atoms, MKV/WebM │
│ 📄 PDF → document info + XMP │
│ 📊 Office → OOXML, OpenDocument, OLE │
│ 📚 E-books → EPUB package metadata │
│ 📁 Any file → size, timestamps, attributes,│
│ xattr; hachoir fallback │
└─────────────────────────────────────────────┘
│
▼
👁️ View · ✏️ Edit · 🗑️ Delete · 🛡️ Share safely
⚖️ Diff · 🔑 Hash · 🗂️ Batch
- 🗂️ File-manager UI — folder tree + file list + metadata detail panel
- 🖼️ All major formats — images (JPEG/PNG/TIFF/WebP/GIF/RAW), audio (MP3/FLAC/OGG/Opus/M4A/WAV/AIFF/WMA/APE), video (MP4/MOV/MKV/AVI), documents (PDF/DOCX/XLSX/PPTX/DOC/XLS/PPT); any other file through the hachoir fallback and the filesystem layer
- ✏️ Typed editing — read, edit, add and delete individual fields with inputs matching their type (text, numbers, booleans, dates with UTC offset, exact rationals, lists); the sidecar validates every value and decides what is editable
- 🔒 Verified atomic writes — changes go to a private copy beside the file, are read back and checked, then replace the original (
ReplaceFileWon Windows,os.replaceelsewhere); a failure leaves the file untouched - ↩️ Exact Undo — up to 50 saves per session, restored byte for byte in the usual case (pictures and other binaries included; very large changes fall back to restoring the values); refused if the file changed meanwhile
- 🛡️ Prepare files for sharing — the Share tab removes location, identity, device, dates, software, thumbnails and edit history in one undoable step; each field shows a privacy badge
- 🗂️ Batch operations — on many files: prepare for sharing, shift dates, copy metadata, add a position (fixed or from a GPX track), rename from metadata, export a folder to CSV/JSON
- 🔎 Files recognized by content — a file without (or with a wrong) extension is handled as its real format
- 🔑 File integrity hashes — on-demand MD5 / SHA-1 / SHA-256 / SHA-512 / BLAKE2b with one-click copy
- 🎨 Cyber dark theme — professional dark UI with cyan/blue accents
- 📦 Compiled binaries — no Python or Node.js required to run
- 💾 Offline-first — zero telemetry; the only network call is the optional update check
- 🚪 Clean exit — the Exit button stops the background process and everything it started, and releases its memory and port
- 🔔 Update check — manual from About / Help, or opt-in at startup; downloads are SHA-256 verified
- 🆓 Free & open-source — MIT license
The badges at the top of this page always show the latest stable and beta releases.
📖 See full version history → CHANGELOG.md
- Windows 10/11 (64-bit) or Linux with glibc 2.34+ (Ubuntu 22.04+, Debian 12+, Fedora, RHEL 9/10):
.deb/.rpm/.tar.gz— see REQUIREMENTS.md - RAM 512 MB free
- Disk ~300 MB installed
- No Python or Node.js needed to run the app — only to build it from source
Important
✅ For complete requirements, see REQUIREMENTS.md
Follow INSTALLATION.md for Windows/Linux binaries or building from source.
Learn the interface in USAGE.md.
Explore the sidecar API in API.md.
| Category | Formats | Read | Write |
|---|---|---|---|
| Images | JPEG — EXIF/GPS, XMP, IPTC-IIM (also JFIF header, comments, Multi-Picture index and ICC profile, read-only) | ✅ | ✅ |
| Images | PNG (text, eXIf, XMP, ICC, header), WebP (EXIF, XMP, ICC), TIFF (EXIF, XMP, IPTC, ICC) — EXIF/XMP can be edited and added, PNG text and the IPTC record of a TIFF removed |
✅ | ✅ |
| Images | GIF (comment), BMP, ICO | ✅ | — |
| Images | HEIC, HEIF, AVIF — size, rotation, EXIF/GPS, XMP, ICC (EXIF/XMP edited, added and removed in place) | ✅ | ✅ |
| Images (RAW) | CR2, NEF, ARW, DNG, ORF, RW2, RWL, PEF, SRW and other TIFF-based RAW (EXIF, XMP, IPTC) — changes are experimental and never move existing data | ✅ | ✅ |
| Images (RAW) | Canon CR3 and Fujifilm RAF (EXIF, GPS, preview metadata) | ✅ | — |
| Audio | MP3, WAV, AIFF, TTA (ID3) · FLAC, OGG, OGA, Opus, SPX (Vorbis comments) · WMA (ASF) · APE, WV, MPC (APEv2) · M4A (MP4 atoms) | ✅ | ✅ |
| Audio | AAC (ADTS/ADIF) | ✅ | — |
| Video | MP4, M4V, MOV, M4B, M4R (MP4 atoms; structure: brand, dates, tracks, rotation, codec, frame rate; dates, location, device and text entries and XMP can be edited, added and removed) | ✅ | ✅ |
| Video | MKV, WebM, MKA (title, tags, attachments, tracks; removed or rewritten in place) | ✅ | ✅ |
| Video | AVI, WMV, FLV, TS, MTS, M2TS (via hachoir) | ✅ | — |
| Documents | PDF — document info + XMP (the XMP stream can be removed as a whole; not encrypted, not digitally signed) | ✅ | ✅ |
| Office | DOCX, XLSX, PPTX, DOCM, XLSM, PPTM — core properties (not digitally signed); app.xml/custom.xml values can be removed |
✅ | ✅ |
| OpenDocument | ODT, ODS, ODP, ODG and templates (meta.xml) |
✅ | ✅ |
| E-books | EPUB (package metadata; identifier, title and language stay) | ✅ | ✅ |
| Office (legacy) | DOC, XLS, PPT, DOT, XLT, POT (OLE property sets; properties can be removed, not edited) | ✅ | 🗑️ remove |
| Any file | Filesystem: fs:mtime writable; size, other timestamps, permissions/owner (POSIX), Windows attributes read-only; xattr (Linux: user. writable; macOS: read-only) |
✅ | ✅ (mtime, xattr) |
| Other | Many more formats recognized from their content via hachoir | ✅ | — |
Files without an extension are recognized from their content. Every change is verified (the picture, audio or video data must come out identical) and can be undone.
The Share tab removes what a file reveals before you send it (location, identity, device, dates, software, thumbnails, edit history), with a preview and Undo. The Batch button of the file list does the same on many files and also shifts dates, copies metadata between files, adds a position (fixed or from a GPX track), renames from metadata and exports a folder to CSV or JSON.
Compute cryptographic hashes on demand from the Metadata panel — no impact on browsing performance:
| Algorithm | Notes |
|---|---|
| MD5 | Legacy, widely used for checksums |
| SHA-1 | Legacy, used by Git and many tools |
| SHA-256 | Modern standard, recommended |
| SHA-512 | High-security workloads |
| BLAKE2b | Fast modern algorithm, built into Python |
| Layer | Technology | Notes |
|---|---|---|
| Desktop shell | Electron (Node.js main process) | Spawns the Python sidecar, native menus & dialogs |
| Renderer UI | React 19, Vite, TailwindCSS v4 | Folder tree, file list, metadata detail panel |
| Sidecar | Python 3.13, FastAPI, uvicorn | Metadata extraction/write engine, 127.0.0.1 only |
Electron Main (Node.js)
├── Spawns Python sidecar (FastAPI, localhost only)
├── Manages window, native menus, file dialogs
└── IPC bridge (contextBridge): dialogs, paths, menu events, and the
sidecar port + session token for the renderer
React renderer ── HTTP + Bearer token ──▶ Python Sidecar (127.0.0.1)
Python Sidecar (FastAPI)
├── /list — directory listing with handler detection
├── /read — full metadata extraction (format + filesystem layer)
├── /write — verified atomic write (and optional deletes) in one save
├── /delete — field removal
├── /sanitize, /sanitize-many — prepare one or many files for sharing
├── /shift-dates, /copy-tags, /geotag, /rename, /export — operations on several files
├── /undo — exact undo of a save by its token
├── /diff — metadata comparison
├── /aliases — common names used by the search box
└── /hash — on-demand file hashing
React Frontend (Vite + TailwindCSS)
├── FolderPanel — folder tree navigation
├── FilePanel — file list with metadata summary
├── DetailPanel — Metadata / Edit / Share / Diff tabs
└── BatchDialog — operations on several files
📖 Full endpoint reference → API.md
Automated Python, Electron and React suites cover metadata handlers, file integrity and rollback, path validation, sidecar authentication, desktop security, Undo, asynchronous UI updates and release notes.
pytest python/tests/ -v
cd electron && npm test
cd ../frontend && npm test- 🛡️ No cloud dependencies — everything runs locally
- 🔒 No telemetry — zero data collection
- 📁 Localhost-only sidecar — the Python API never binds beyond
127.0.0.1 - 🔓 Open source — fully auditable code
- ⚡ Offline by default — no internet connection required. The only network access is the update check against the public GitHub Releases API, started by you (About → Check for updates or Help → Check for Updates…) or, if you enable it, once at startup. It sends no file data, paths or identifiers (only a
User-Agent: MetaLens/<version>header). Settings are stored locally insettings.jsonin the app data folder
📖 See SECURITY.md for the full security model.
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit changes with clear messages
- Push to your fork
- Open a Pull Request to
developbranch
📖 See CONTRIBUTING.md for the full guide.
Note
📖 All PRs should target the develop branch, not main.
Distributed under the MIT License. See LICENSE for details.
- 📖 Documentation: See docs/ folder
- 🐛 Report issues: GitHub Issues
- 💬 Questions: Open a GitHub Discussion
Developed by Graziano Mariella
Distributed with MIT License · View License
Last updated: 2026-11-04 ← Requirements | Docs →