Tagging & Cover Art
Narratorr can write metadata tags to your audiobook files after import — author, title, narrator, series, and cover art. This ensures your files are properly tagged regardless of how the original release was labeled.
Enabling Tagging
Section titled “Enabling Tagging”Configure in Settings > Post Processing (the tagging controls are at the bottom of that page). Tagging is disabled by default.
| Setting | Description |
|---|---|
| Tag Embedding | Master toggle for tag writing |
| Tag Mode | How tags are written (see below) |
| Embed Cover Art | Embed cover art into audio files as an attached picture |
Tagging requires ffmpeg — configure its path in Settings > Post Processing > ffmpeg Path (pre-installed in Docker).
Tag Modes
Section titled “Tag Modes”| Mode | Behavior |
|---|---|
| Populate Missing | Only writes tags to fields that are currently empty. Preserves any existing tags. This is the default and safest option. |
| Overwrite | Writes all tags from Narratorr’s metadata, replacing whatever was in the file. Use this when you trust Narratorr’s metadata more than the source files. |
What Gets Tagged
Section titled “What Gets Tagged”| Tag Field | Source |
|---|---|
| Artist / Album Artist | Book author |
| Album | Book title |
| Title | Book title (single file) or preserved (multi-file) |
| Composer | Narrator |
| Grouping / Series | Series name |
| Series Part | Position in series |
| Track / Track Total | File position (multi-file only) |
| Subtitle | Book subtitle |
| ASIN | Audible ASIN |
| Publisher | Publisher |
| Description | Book description |
| Date | Publication year |
| Genre | Genre |
The extended fields (series, series part, subtitle, ASIN, publisher, description, date, genre) are the Audiobookshelf-survivable set — they’re written in the form that survives M4B embedding and is picked up by Audiobookshelf, so your media server sees narratorr’s metadata rather than the release’s. When writing M4B files, existing chapter markers are preserved.
Cover Art Embedding
Section titled “Cover Art Embedding”When Embed Cover Art is enabled, Narratorr looks for a cover.jpg, cover.jpeg, cover.png, or cover.webp file in the book’s directory and embeds it as the audio file’s attached picture.
In populate missing mode, cover art is only embedded if the file doesn’t already have embedded artwork. In overwrite mode, it always embeds.
If no cover image file is found in the directory, a warning is logged but tagging continues for the text metadata.
OPF Metadata Sidecar
Section titled “OPF Metadata Sidecar”Separately from embedded tags, Narratorr can write a metadata.opf sidecar file into each book’s folder. OPF is a portable metadata format that media servers — Audiobookshelf in particular — can read as a metadata source, so your library shows Narratorr’s metadata instead of whatever tags shipped with the release.
Enable it with OPF Metadata Sidecar in Settings > Post Processing. It’s independent of tag embedding — you can write OPF sidecars without turning on audio tag writing, which is handy when you’d rather not rewrite the audio files themselves.
When it’s written. Narratorr writes or refreshes the sidecar whenever a book’s metadata changes on disk: on import, when you edit a book’s metadata, on Fix Match, when you upload a cover, and during a library sidecar reconcile. It’s skipped for single-file “pointer” imports that don’t own a folder.
Your own OPF is never overwritten. Narratorr marks the files it writes with an internal narratorr:managed marker. If a book folder already contains a metadata.opf that Narratorr didn’t write — one from Calibre or a previous Audiobookshelf match, say — Narratorr leaves it untouched and logs a warning rather than clobbering it.
Writing or refreshing a sidecar also nudges your connectors so the media server re-reads it.
Supported Formats
Section titled “Supported Formats”Tag writing works with: MP3 (.mp3), M4A (.m4a), M4B (.m4b).
Other audio formats (FLAC, OGG, etc.) in the book directory are skipped with a warning.
Re-tagging
Section titled “Re-tagging”You can re-tag an existing book’s files from the book detail page. Re-tagging opens a preview-and-confirm modal that shows exactly which files will change and how — a per-file before→after diff of every tag field, built from the book’s current metadata in Narratorr.
In the preview you can opt individual fields out via checkboxes (for example, keep the file’s existing title while updating everything else), and you can temporarily override the Tag Mode and Embed Cover Art options for that single run without changing your saved settings. The preview defaults to your saved Settings > Post Processing tagging settings.
How It Fits in the Pipeline
Section titled “How It Fits in the Pipeline”When tagging is enabled, it runs automatically as a post-import step: once a download’s files are copied into your library, Narratorr writes the tags, then continues with any post-processing script and notifications. It is best-effort — a tagging failure is logged but does not fail the import. If tagging is disabled, files are imported as-is.
Audio processing (merge/convert) is a separate, manual operation you trigger per book — it is not an automatic step in the import pipeline, so tagging does not depend on it.