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 in the Post Processing card at the top 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 (pre-installed in Docker). Narratorr detects it automatically — the detection status is shown in Settings > Audio Tools, and there is no ffmpeg path setting in the UI. To force a specific binary, set the FFMPEG_PATH environment variable.
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) survive MP3 embedding and are picked up by Audiobookshelf, so your media server sees narratorr’s metadata rather than the release’s. M4B is less forgiving: the container drops series, series part, subtitle, ASIN, and publisher (date, genre, and description survive) — enable the OPF metadata sidecar so Audiobookshelf still sees narratorr’s full metadata for M4B files. 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 operation, manual by default — the opt-in Auto-merge multi-file downloads toggle in Settings > Post Processing automates the merge for completed downloads. Either way, tagging does not depend on it.