Under the hood
Where your books live, how the iPhone and the Mac talk, what goes out to the Internet and what never does.
Where does your library live?
The iPhone
- The app The camera, the scanner, dictation. The library, the records, the classification.
- The engine The only one that reads and writes the database. It analyses the photos and asks the catalogues; with no AI set up, Apple Intelligence reads the covers, on the iPhone.
- The folder The database (
colophon.db) and your images: photos, covers, originals, contents.
The catalogues
Books BnF, Open Library, Google Books with a key
Albums MusicBrainz, Cover Art Archive
Movies TMDB
Magazines Wikidata
An AI, if you want one
Claude or OpenAI, with your own key.
Or Ollama, on your Mac: nothing leaves it.
Your other devices
If you turn it on: the same library on the iPhone, the iPad and the Mac, through your iCloud Drive.
The backup
The “Couvertures iPhone” file, in iCloud Drive › Couvertures or a folder you choose. A Mac restores it with a double-click.
The Mac
- The app The window, the menus, the settings.
- The server The engine’s door. It answers the iPhone, the other phone, and the Mac’s own window too.
- The engine The only one that reads and writes the database. It analyses the photos and asks the catalogues; with no AI set up, Apple Intelligence reads the covers, on the Mac.
- The folder The database (
colophon.db) and your images: photos, covers, originals, contents.
The iPhone and iPad
The camera, the scanner, dictation. A copy of the library, to browse it away from the Mac, and what is waiting to be sent.
Another phone
Android, or a friend’s: the Mac’s web page, opened from the QR code.
The catalogues
Books BnF, Open Library, Google Books with a key
Albums MusicBrainz, Cover Art Archive
Movies TMDB
Magazines Wikidata
An AI, if you want one
Claude or OpenAI, with your own key.
Or Ollama, on your Mac: nothing leaves it.
Your other devices
If you turn it on: the same library on the iPhone, the iPad and the Mac, through your iCloud Drive.
The backup
The “Couvertures Mac” file, in a folder of your choice: iCloud Drive, Dropbox, a disk, a NAS.
A folder keeps everything
Your library is a folder: on the Mac, wherever you chose to put it, or inside the app, on the iPhone. Inside:
colophon.db, the database: a single file in the SQLite format, the one used by nearly every phone and browser. It holds each book, magazine, movie or album, its classification, your notes, your readings, and the library’s settings (categories, locations, lists).photos, your photos, cropped and made lighter;covers, the covers, posters and sleeves found online and kept;originals, your photos at full size, so they can be cropped or read again later;contents, the photos of your magazines’ contents pages.
The database only stores each image’s name, never its full path: the folder can move to another place, disk or device without breaking anything. Its format is open: any program that reads SQLite can open it; the app’s former name, Colophon, has stayed there.
One engine, on the iPhone or on the Mac
At the heart of Couvertures is an engine: it alone reads and writes the database, analyses the photos and asks the catalogues. The screens never touch the database themselves: they ask the engine. It is the same engine on the iPhone and on the Mac, with the same rules.
It runs where the library lives, chosen the first time you open the iPhone app (Where does your library live?) and changed in Settings > Where the Library Lives:
- On This iPhone: the engine runs inside the iPhone app, which talks to it directly, with no server and no local network. No Mac needed.
- On My Computer: the engine runs inside the Mac app, and the iPhone talks to it over the Wi-Fi. The next three sections describe this path.
Switching from one to the other erases nothing: each mode keeps its own library. To take the iPhone’s library to the Mac, you go through its backup (below); to have the same one on several devices, through sync (below too).
With a Mac, a small server
When the library lives on the Mac, Couvertures runs a web server there, like a website that can only be seen in your home. It is the engine’s door. Everything talks to it: the iPhone, the web page on another phone (opened from the QR code in the Mac’s Settings), and even the Mac’s own window, which goes through the same door as the others. A single keeper: two screens can’t change a book at the same time and trip over each other.
The server runs as long as the app is open, even with its window closed. That is why the iPhone, to send its photos, needs the Mac on, awake, and Couvertures not quit.
How the iPhone finds the Mac
The Mac announces itself on the Wi-Fi with Bonjour, Apple’s way of making a printer or an Apple TV appear without any setup: “Couvertures is here, on this Mac”. The iPhone listens, and remembers the Mac’s name rather than its address, which may change from one day to the next.
Then they speak HTTP, the language of the web, straight from one device to the other, without going through the Internet. The conversation isn’t encrypted: it stays on your network, like a printer’s. On a public Wi-Fi (train, café, hotel), uncheck Reachable from the Wi-Fi in the Mac’s Settings: the server then refuses anything that doesn’t come from the Mac itself.
If the network hides devices (some office or hotel Wi-Fi), you type the Mac’s address by hand: see Getting started.
Away from the Mac
Each time it connects, the iPhone receives the library from the Mac and keeps a copy: all the text, and the colour of each cover. The images, only if you ask (Settings, “Keep the covers on this phone”): they are then copied one by one, without slowing the library down. Away from the Mac, the iPhone can still show the whole library, and answer “Do I already have it?” in a bookshop.
What you do away from the Mac waits on the iPhone, then goes when you’re back:
- photos and scanned barcodes. Photos wait in an upload queue: the iPhone tries again regularly, and iOS keeps sending even while the app is in the background. A photo only leaves the queue once the Mac has answered that it got it;
- changed records, field by field. If the Mac hasn’t touched that field in the meantime, the change goes through without asking. If it changed it too, the iPhone asks which one to keep (Changed on both sides). Keywords and lists add up: no classification is lost.
The library itself stays the Mac’s: the iPhone holds a copy, it doesn’t replace it.
From a photo to a record
- On the iPhone, Apple’s scanner reads the barcode live, without sending anything anywhere. A cover photo can be cropped and brightened before it goes (Crop); otherwise, the engine crops it itself. A dictated title is transcribed by Apple’s speech recognition, on the device. The back cover is read by Vision, Apple’s text recognition, on the device too: its lines are grouped into paragraphs (columns, words split at line ends) without AI, and only the text you keep goes to the engine.
- The engine receives the photo, files it among the “photos to process” and makes it
smaller. It keeps a large version in
originals. - It searches. If it finds a barcode in the photo, it asks the catalogues with it. Otherwise, if you’ve set up an AI, the AI reads the cover (title, author, publisher, and where the item sits in the photo, to crop it); with no AI set up, Apple Intelligence does it, on the device, and its reading is checked word by word against the text that Vision, Apple’s text recognition, finds in the photo. The catalogues are asked at the same time, and their answers are ranked from most to least likely.
- You review. Nothing enters the database before that point, with the cover you kept and the session’s batch (“Box 4”).
A dictated title takes the same path: the AI understands the sentence (“The Little Prince by Saint-Exupéry, Penguin edition”) and fixes misheard names, helped by the authors already in your library.
The barcode says what you’re holding, and so where to look:
- A book: its ISBN, at the Bibliothèque nationale de France, Open Library, and Google Books if you have given it a key.
- A magazine: its code is not an ISBN. French newsstand magazines carry a title code, which
the iPhone reads along with the issue number printed just above it; foreign magazines carry an
ISSN, which Wikidata, Wikipedia’s open database, can name. The first time, the AI reads the
magazine’s name on the cover. The photos of the contents are kept in
contents, and the AI turns them into the list of articles, the masthead and a few keywords. - A movie (DVD): its barcode, an EAN, at the BnF, which knows the DVDs deposited in France. The title found then goes to TMDB, the movie and TV database, for the poster, the overview and the genres.
- An album (CD): its EAN, at the BnF and MusicBrainz, the open music database; the Cover Art Archive, next door, gives the sleeve.
Without a barcode, you photograph the cover or the sleeve, or type or dictate the title. In Add, on the iPhone and iPad, the Books, Movies, Music bar tells the engine where to look: a movie at TMDB, an album at MusicBrainz, a book in the catalogues.
What goes out to the Internet
Only when you add or look something up, or ask for keywords, and only this:
- to the public catalogues (Bibliothèque nationale de France, Open Library, and Google Books if you have given it a key): an ISBN or a barcode, or a title and an author;
- to MusicBrainz and the Cover Art Archive: a CD’s barcode or title, for the disc and its sleeve;
- to TMDB: a movie’s title, for its poster, its overview and its genres;
- to Wikidata: the ISSN of a foreign magazine, to find its name;
- to the AI, if you’ve set one up: the photo of the cover, the dictated sentence, the photos of a contents page; and, when you ask for keywords, a book’s text (title, authors, summary, back cover, contents) with the list of your keywords. With Claude or OpenAI, it goes to them, with your own key. With Ollama, the AI runs on your Mac and nothing leaves it. With no AI set up, Apple Intelligence reads the cover on the device: the photo doesn’t leave.
And, once a day, to our website: the request for the number of the app’s latest version, to offer the update; nothing else goes with it.
No account, no server of ours, no analytics: we see nothing go by. See also Privacy.
Several devices, one library
Turned on in Settings, sync gives the same library to your iPhone, your iPad and your Mac. It does not put the database in iCloud: that would damage it (see the backup, below). Each device keeps its own database, whole, and it is the changes that travel.
- A shared name. Every book and every magazine carries an identifier, the same on all devices, next to its local number.
- A journal kept by the database. At each write, the database itself notes the time of the change, field by field; for keywords, lists and the values you organise with, item by item. A deletion leaves a trace.
- One file per device. In your iCloud Drive, folder Couvertures › Synchronisation, each device writes a single file, its own: what it knows, with those times. Nobody writes another device’s file; each one reads the others’. Images go into a store next to it, under their name.
- One rule, the same everywhere. For a field, the most recent change wins. For a keyword or a value you organise with, two additions are combined, a removal travels. A deleted book only comes back if it was changed elsewhere since. Because the rule is the same on every device, they reach the same result, whatever the order of the exchanges; reading a file again changes nothing.
There is no server between your devices: iCloud Drive carries files, nothing more. Your AI keys are never written there. Photos to review go through it once the device that took them has analysed them, with their suggestions; confirmed on two devices, a photo makes the same book, because the book takes the photo’s identifier.
The backup
Automatic backup copies the library to a folder of your choice: iCloud Drive, Dropbox, a disk, a NAS. It shows there as a single file, with the Couvertures icon: “Couvertures Mac”, “Couvertures iPhone”, “Couvertures iPad”, one per device, so they don’t get mixed up. Only new images are sent each time; of the database, the last ten versions are kept. Inside, the copy is itself a library: Couvertures can restore it as it is.
The Mac backs up on the schedule you choose: every day, week or month. The iPhone, when the library lives on it, backs up to your iCloud Drive, in the Couvertures folder (or another folder you choose), when you leave the app after a change. Tapping that file in the Files app, or double-clicking it in the Finder, offers to restore it: that is how a library moves from the iPhone to the Mac, or from one iPhone to another.
The library itself, on the other hand, must not live in a synced folder. The database is
written in small touches, across three files at once (colophon.db and its two neighbours,
-wal and -shm); a sync service copying one of them in the middle of a write could damage
it. The Mac’s Settings point it out.
Later, Windows and Android
Couvertures for Windows and for Android will come later. The Windows version is written with other tools (a web page and Node.js), and opens the same folder, without conversion: a library will be able to move from one computer to the other as it is.
To make that hold, the database carries a version number. Every change to its structure is written in both versions, with the same number. And a version of Couvertures that finds a newer database than itself doesn’t open it: it says so, rather than risk damaging it.
Made with
Couvertures is written in Swift, Apple’s language, with SwiftUI for the screens: one code base for the iPhone, the iPad and the Mac. It relies on Apple’s tools for the scanner, reading barcodes in photos, dictation, reading covers (Vision, Apple Intelligence) and iCloud Drive, and on a few open-source components: GRDB for the database, Hummingbird for the server. The full list, with their licences, is on the About page: Couvertures > About Couvertures on the Mac, at the bottom of Settings on the iPhone.
The records come from open or public sources: the Bibliothèque nationale de France, Open Library, Google Books, MusicBrainz and the Cover Art Archive, Wikidata, and TMDB for movies. Movie posters, overviews and genres come from TMDB. Couvertures uses TMDB and the TMDB APIs but is not endorsed, certified, or otherwise approved by TMDB.