Installing Metadata Workbench

Version 0.5.0 · about 10 minutes · PDF (English and French)

Requirements

A Mac with Apple silicon (M1, M2, M3, M4 or later). Intel Macs are not supported.
macOS 15 Sequoia or later.
About 500 MB of free disk space, plus room for your projects (each file you add is copied into its project).
Optional: ffmpeg to inspect and edit audio and video files.

1. Download

Download MetadataWorkbench-macOS.dmg from the official release page on GitHub. Avoid copies from anywhere else.
Optional but recommended — check the file. Open Terminal (Applications ▸ Utilities) and run:
```
shasum -a 256 ~/Downloads/MetadataWorkbench-macOS.dmg
```
Compare the result with the SHA-256 shown on the release page (file MetadataWorkbench-macOS.dmg.sha256). They must be identical. If they differ, delete the download and try again.

2. Install

Double-click the downloaded .dmg. A window opens with Metadata Workbench, an Applications shortcut, the licence and this guide as a PDF.
Drag Metadata Workbench onto Applications.
Eject the disk image (the eject button next to it in the Finder sidebar). You can delete the .dmg.

3. Open it the first time

The app is free and is not distributed through the App Store or signed with a paid Apple Developer ID, so macOS asks you to confirm it once. This is expected. You only need to do it the first time (and again after installing a new version).

Open Applications and double-click Metadata Workbench. macOS shows a message saying it “cannot verify” the app or that it was “not opened”. Click Done (or OK) — do not move it to the Trash.
Open System Settings ▸ Privacy & Security. Scroll down to the Security section: you will see “Metadata Workbench was blocked…”. Click Open Anyway.
Confirm with Open Anyway again and enter your Mac password (or use Touch ID). The app opens. From now on it opens normally.

Alternative (Terminal). If you prefer, this single command removes the download quarantine flag from the app, after which it opens normally:

xattr -dr com.apple.quarantine "/Applications/Metadata Workbench.app"

4. Check the installation

In the app, choose Help ▾ ▸ Run self-test (offline)…. It runs about a dozen checks in under a minute without using the network: bundled tools, isolation of file parsers, editing and verification. All checks should say PASS.
Choose Help ▾ ▸ About Metadata Workbench… to see the version, the licence and the third-party notices.

5. Optional: audio and video (ffmpeg)

Photos, RAW files, Office documents and PDFs work right away. To inspect and edit audio and video (MP4, MOV, MP3, FLAC, MKV…), install the free ffmpeg tools with Homebrew:

If you do not have Homebrew yet, install it by following the one-line instructions on brew.sh.
In Terminal, run
```
brew install ffmpeg
```
Restart Metadata Workbench. The self-test now also reports ffmpeg as available.

6. Access to your folders

The first time you add files from Desktop, Documents, Downloads, an external drive or a network volume, macOS asks whether Metadata Workbench may access that location. Click Allow. You can review this later in System Settings ▸ Privacy & Security ▸ Files and Folders.

The app only reads your original files. It copies each one into the project and works on that copy.

Where your data is kept

Projects are saved by default in ~/MetadataWorkbench/projects/ (in your home folder). Each project is a folder containing a database, the verified copies of your files, edited copies and exports.
Projects are not encrypted by the app. Keep FileVault turned on (System Settings ▸ Privacy & Security ▸ FileVault), especially for sensitive material.
The app works offline and sends nothing anywhere.

Updating

Download the new .dmg, quit the app, drag the new version onto Applications and choose Replace. Repeat step 3 (Open Anyway) once. Your projects are not affected; a project opened with a newer version is upgraded automatically (a backup is kept in the project's backups/ folder).

Uninstalling

Drag Metadata Workbench from Applications to the Trash.
Optional: delete ~/MetadataWorkbench/ to remove all your projects (this cannot be undone — keep anything you need first) and the settings file in ~/Library/Preferences/ whose name ends in MetadataWorkbench.plist.

Command-line tool (advanced)

The app includes a command-line tool for scripting and batch work:

"/Applications/Metadata Workbench.app/Contents/MacOS/MetadataWorkbench" --cli doctor

To shorten it, add this line to ~/.zshrc and open a new Terminal window:

alias mwb='"/Applications/Metadata Workbench.app/Contents/MacOS/MetadataWorkbench" --cli'

Then mwb --help lists every command (inspect, report, plan, apply, verify, diff, selftest…).

Troubleshooting

Problem	What to do
“Metadata Workbench is damaged and can't be opened”	The download was quarantined in a way the Open Anyway button does not fix. Use the `xattr` command in step 3, then open the app again. If it persists, check the SHA-256 (step 1) and download again.
No “Open Anyway” button	Try opening the app once first (step 3.1); the button appears for about an hour afterwards. Or use the `xattr` command.
“You can't use this version with this version of macOS”	macOS 15 or later is required.
The app does not start on an Intel Mac	Only Apple silicon Macs are supported.
Audio/video files are read-only or show “ffmpeg not found”	Install ffmpeg (section 5) and restart the app.
A file is marked unstable	It changed while being read (still syncing from iCloud/OneDrive, or still being saved). Wait until it is fully downloaded and closed, then add it again.
A self-test check fails	Note which check failed and the message, then report it through the GitHub issues page.

Next: the user guide →

Installer Metadata Workbench

Version 0.5.0 · environ 10 minutes · PDF (français et anglais)

Configuration requise

Un Mac avec puce Apple (M1, M2, M3, M4 ou plus récent). Les Mac Intel ne sont pas pris en charge.
macOS 15 Sequoia ou plus récent.
Environ 500 Mo d'espace libre, plus l'espace pour vos projets (chaque fichier ajouté est copié dans son projet).
Facultatif : ffmpeg pour inspecter et éditer les fichiers audio et vidéo.

1. Télécharger

Téléchargez MetadataWorkbench-macOS.dmg à partir de la page officielle des versions sur GitHub. Évitez les copies provenant d'ailleurs.
Facultatif mais recommandé — vérifiez le fichier. Ouvrez le Terminal (Applications ▸ Utilitaires) et exécutez :
```
shasum -a 256 ~/Downloads/MetadataWorkbench-macOS.dmg
```
Comparez le résultat avec le SHA-256 affiché sur la page de la version (fichier MetadataWorkbench-macOS.dmg.sha256). Ils doivent être identiques. S'ils diffèrent, supprimez le téléchargement et recommencez.

2. Installer

Double-cliquez sur le .dmg téléchargé. Une fenêtre s'ouvre avec Metadata Workbench, un raccourci Applications, la licence et ce guide en PDF.
Glissez Metadata Workbench sur Applications.
Éjectez l'image disque (bouton d'éjection à côté de son nom dans la barre latérale du Finder). Vous pouvez supprimer le .dmg.

3. L'ouvrir la première fois

L'application est gratuite; elle n'est pas distribuée par l'App Store ni signée avec un identifiant de développeur Apple payant. macOS vous demande donc de la confirmer une fois. C'est normal. Il suffit de le faire la première fois (et de nouveau après l'installation d'une nouvelle version).

Ouvrez Applications et double-cliquez sur Metadata Workbench. macOS affiche un message indiquant qu'il « ne peut pas vérifier » l'application ou qu'elle « n'a pas été ouverte ». Cliquez sur Terminé (ou OK) — ne la placez pas dans la corbeille.
Ouvrez Réglages Système ▸ Confidentialité et sécurité. Descendez jusqu'à la section Sécurité : vous verrez « Metadata Workbench a été bloqué… ». Cliquez sur Ouvrir quand même.
Confirmez de nouveau avec Ouvrir quand même et saisissez le mot de passe de votre Mac (ou utilisez Touch ID). L'application s'ouvre. Par la suite, elle s'ouvrira normalement.

Autre méthode (Terminal). Si vous préférez, cette commande unique retire de l'application l'attribut de quarantaine du téléchargement; elle s'ouvre ensuite normalement :

xattr -dr com.apple.quarantine "/Applications/Metadata Workbench.app"

4. Vérifier l'installation

Dans l'application, choisissez Help ▾ ▸ Run self-test (offline)… (autotest hors ligne). Il effectue une douzaine de vérifications en moins d'une minute, sans utiliser le réseau : outils inclus, isolement des analyseurs, édition et vérification. Toutes doivent indiquer PASS.
Choisissez Help ▾ ▸ About Metadata Workbench… pour voir la version, la licence et les avis relatifs aux composants tiers.

L'interface de l'application est en anglais; les libellés sont donc indiqués en anglais dans ce guide.

5. Facultatif : audio et vidéo (ffmpeg)

Les photos, les fichiers RAW, les documents Office et les PDF fonctionnent tout de suite. Pour inspecter et éditer l'audio et la vidéo (MP4, MOV, MP3, FLAC, MKV…), installez les outils gratuits ffmpeg avec Homebrew :

Si vous n'avez pas encore Homebrew, installez-le en suivant l'instruction d'une ligne sur brew.sh.
Dans le Terminal, exécutez
```
brew install ffmpeg
```
Redémarrez Metadata Workbench. L'autotest indique maintenant que ffmpeg est disponible.

6. Accès à vos dossiers

La première fois que vous ajoutez des fichiers provenant du Bureau, de Documents, de Téléchargements, d'un disque externe ou d'un volume réseau, macOS demande si Metadata Workbench peut accéder à cet emplacement. Cliquez sur Autoriser. Vous pouvez revoir ce choix dans Réglages Système ▸ Confidentialité et sécurité ▸ Fichiers et dossiers.

L'application ne fait que lire vos fichiers originaux. Elle copie chacun d'eux dans le projet et travaille sur cette copie.

Où vos données sont conservées

Par défaut, les projets sont enregistrés dans ~/MetadataWorkbench/projects/ (dans votre dossier personnel). Chaque projet est un dossier contenant une base de données, les copies vérifiées de vos fichiers, les copies modifiées et les exportations.
L'application ne chiffre pas les projets. Gardez FileVault activé (Réglages Système ▸ Confidentialité et sécurité ▸ FileVault), surtout pour du contenu sensible.
L'application fonctionne hors ligne et n'envoie rien nulle part.

Mettre à jour

Téléchargez le nouveau .dmg, quittez l'application, glissez la nouvelle version sur Applications et choisissez Remplacer. Refaites l'étape 3 (Ouvrir quand même) une fois. Vos projets ne sont pas touchés; un projet ouvert avec une version plus récente est mis à niveau automatiquement (une sauvegarde est conservée dans le dossier backups/ du projet).

Désinstaller

Glissez Metadata Workbench d'Applications vers la corbeille.
Facultatif : supprimez ~/MetadataWorkbench/ pour retirer tous vos projets (irréversible — conservez d'abord ce dont vous avez besoin) et, pour les réglages, le fichier de ~/Library/Preferences/ dont le nom se termine par MetadataWorkbench.plist.

Outil en ligne de commande (avancé)

L'application comprend un outil en ligne de commande pour les scripts et le traitement par lots :

"/Applications/Metadata Workbench.app/Contents/MacOS/MetadataWorkbench" --cli doctor

Pour l'abréger, ajoutez cette ligne à ~/.zshrc et ouvrez une nouvelle fenêtre de Terminal :

alias mwb='"/Applications/Metadata Workbench.app/Contents/MacOS/MetadataWorkbench" --cli'

Ensuite, mwb --help énumère toutes les commandes (inspect, report, plan, apply, verify, diff, selftest…).

Dépannage

Problème	Que faire
« Metadata Workbench est endommagé et ne peut pas être ouvert »	Le téléchargement a été mis en quarantaine d'une façon que le bouton Ouvrir quand même ne règle pas. Utilisez la commande `xattr` de l'étape 3, puis rouvrez l'application. Si le problème persiste, vérifiez le SHA-256 (étape 1) et téléchargez de nouveau.
Aucun bouton « Ouvrir quand même »	Essayez d'abord d'ouvrir l'application une fois (étape 3.1); le bouton apparaît ensuite pendant environ une heure. Ou utilisez la commande `xattr`.
« Vous ne pouvez pas utiliser cette version avec cette version de macOS »	macOS 15 ou plus récent est requis.
L'application ne démarre pas sur un Mac Intel	Seuls les Mac avec puce Apple sont pris en charge.
Les fichiers audio/vidéo sont en lecture seule ou « ffmpeg not found » s'affiche	Installez ffmpeg (section 5) et redémarrez l'application.
Un fichier est marqué unstable (instable)	Il a changé pendant sa lecture (synchronisation iCloud/OneDrive en cours, ou enregistrement non terminé). Attendez qu'il soit entièrement téléchargé et fermé, puis ajoutez-le de nouveau.
Une vérification de l'autotest échoue	Notez la vérification en cause et le message, puis signalez-le sur la page des problèmes GitHub.

Suite : le guide d'utilisation →