Skip to content
CouverturesCouvertures

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 records, the covers an ISBN, a barcode, a title

The catalogues

Books BnF, Open Library, Google Books with a key
Albums MusicBrainz, Cover Art Archive
Movies TMDB
Magazines Wikidata

what it read there a cover, a contents page, a dictated sentence

An AI, if you want one

Claude or OpenAI, with your own key.
Or Ollama, on your Mac: nothing leaves it.

what changed elsewhere what changed here, the images

Your other devices

If you turn it on: the same library on the iPhone, the iPad and the Mac, through your iCloud Drive.

a copy, when you leave the app after a change

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.
over the Wi-Fi photos, barcodes, contents, dictated titles, changed records the books, the covers

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.

over the Wi-Fi photos the web page

Another phone

Android, or a friend’s: the Mac’s web page, opened from the QR code.

the records, the covers an ISBN, a barcode, a title

The catalogues

Books BnF, Open Library, Google Books with a key
Albums MusicBrainz, Cover Art Archive
Movies TMDB
Magazines Wikidata

what it read there a cover, a contents page, a dictated sentence

An AI, if you want one

Claude or OpenAI, with your own key.
Or Ollama, on your Mac: nothing leaves it.

what changed elsewhere what changed here, the images

Your other devices

If you turn it on: the same library on the iPhone, the iPad and the Mac, through your iCloud Drive.

a copy, every day, week or month

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:

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:

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:

The library itself stays the Mac’s: the iPhone holds a copy, it doesn’t replace it.

From a photo to a record

  1. 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.
  2. The engine receives the photo, files it among the “photos to process” and makes it smaller. It keeps a large version in originals.
  3. 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.
  4. 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:

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:

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.

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.