Repository navigation
Description
ReadMeABook version
v1.2.12
Deployment type
Unified Docker image
Media backend
Audiobookshelf
Steps to reproduce
- Deploy ReadMeABook using the unified Docker container.
- Configure Audiobookshelf as the media backend.
- Enable Metadata Tagging in ReadMeABook.
- Enable Chapter Merging (although merging will be skipped for a single-file M4B).
- Download or import an existing M4B that already contains valid embedded chapter markers.
- Allow ReadMeABook to tag the audio file and copy the processed version into the audiobook library.
- Compare the original downloaded M4B against the imported library copy using
ffprobe -show_chapters.
Test audiobook: Carl's Doomsday Scenario (Dungeon Crawler Carl, Book 2) by Matt Dinniman.
The original downloaded M4B contained valid chapter markers before ReadMeABook processed it.
ReadMeABook identified a single audio file, skipped chapter merging, applied metadata tagging, and reported successful file organization.
After importing, Audiobookshelf displayed incorrect chapter markers, including a zero-duration first chapter, a missing Chapter 002, and a duplicated Chapter 028.
Expected behavior
Metadata Tagging should preserve the existing chapter structure of an M4B file.
Specifically:
- The chapter count should remain unchanged.
- Chapter titles should remain unchanged.
- Chapter start and end timestamps should remain accurate, allowing for insignificant container timestamp rounding.
- Existing chapter order should be preserved.
- Audio duration and playback should remain intact.
ReadMeABook should add or update metadata such as title, author, narrator, series, genre, description, and ASIN without damaging the original chapter information.
If metadata processing changes or corrupts chapter markers, the application should detect the discrepancy, reject the damaged derivative, and preserve the valid source file.
The import should not be marked successful when chapter validation fails.
Actual behavior
ReadMeABook reported successful metadata tagging and file organization, but the resulting M4B contained corrupted chapter markers.
The original file contained the following chapters:
Chapter | Start (seconds) | End (seconds) -- | -- | -- 001 | 0.000 | 20.572 002 | 20.572 | 1533.352 003 | 1533.352 | 3327.140Additional observations:
Chapter 001 had zero duration.
Chapter 002 was missing.
Chapter 028 incorrectly appeared at the beginning and also near the end.
The audio duration remained approximately 41,295.366 seconds.
Audiobookshelf displayed the corrupted chapter information.
ReadMeABook did not report a chapter validation error.
Workaround successfully tested:
Disabled Metadata Tagging in ReadMeABook.
Restored a copy of the untouched downloaded M4B into the audiobook library.
Confirmed the restored file's chapter markers using FFprobe.
Removed the stale Audiobookshelf library entry without deleting files.
Rescanned the library.
Audiobookshelf then displayed the correct chapters.
This strongly indicates that corruption occurred during ReadMeABook's metadata-processing workflow. However, it has not yet been determined whether the FFmpeg remux or the subsequent MP4 metadata post-processing step caused the damage.
Docker Compose (or run command)
**Deployment:** TrueNAS SCALE Apps — Unified Docker container
**Docker image:** `ghcr.io/kikootwo/readmeabook:latest`
**Docker Compose project:** `ix-readmeabook`
ReadMeABook is managed through the TrueNAS SCALE Apps interface using an automatically generated Docker Compose configuration.
Sanitized service configuration:
services:
readmeabook:
image: ghcr.io/kikootwo/readmeabook:latest
**Configured environment variable names:**
- `PUID`
- `PGID`
- `UMASK`
**Container volume destinations:**
/app/config
/app/cache
/var/lib/postgresql/data
/var/lib/redis
/data/90_Downloads
/media/audiobooks
**Networking:** Default Docker Compose network.
**Relevant application settings at the time of the failure:**
- Metadata Tagging: Enabled
- Chapter Merging: Enabled (not invoked for the single-file M4B)
- Media backend: Audiobookshelf
The configuration above is a sanitized summary of the TrueNAS-generated deployment. Host filesystem paths, environment values, and credentials are intentionally omitted.Logs
ORIGINAL DOWNLOAD
Duration: 41295.365805 seconds
Chapters: 28
Duplicate titles: None
Zero-duration chapters: None
01 | 001 | 0.000000 -> 20.572000
02 | 002 | 20.572000 -> 1533.352000
03 | 003 | 1533.352000 -> 3327.140000
04 | 004 | 3327.140000 -> 4208.500000
05 | 005 | 4208.500000 -> 5259.087000
06 | 006 | 5259.087000 -> 6426.911000
...
27 | 027 | 39445.571000 -> 41013.730000
28 | 028 | 41013.730000 -> 41295.365805
CORRUPTED IMPORT (METADATA TAGGING ENABLED)
Duration: 41295.365805 seconds
Chapters: 28
Duplicate titles: {'028': 2}
Zero/negative-duration chapters: [1]
01 | 001 | 0.000000 -> 0.000000
02 | 028 | 0.000000 -> 281.635805
03 | 003 | 1533.352000 -> 3327.140000
04 | 004 | 3327.140000 -> 4208.500000
05 | 005 | 4208.500000 -> 5259.087000
06 | 006 | 5259.087000 -> 6426.911000
...
27 | 027 | 39445.571000 -> 41013.730000
28 | 028 | 41013.730000 -> 41295.365805
REPAIRED LIBRARY COPY (RESTORED FROM SOURCE)
Duration: 41295.365805 seconds
Chapters: 28
Duplicate titles: None
Zero-duration chapters: None
01 | 001 | 0.000000 -> 20.572000
02 | 002 | 20.572000 -> 1533.352000
03 | 003 | 1533.352000 -> 3327.140000
04 | 004 | 3327.140000 -> 4208.500000
05 | 005 | 4208.500000 -> 5259.087000
06 | 006 | 5259.087000 -> 6426.911000
...
27 | 027 | 39445.571000 -> 41013.730000
28 | 028 | 41013.730000 -> 41295.365805
COMPARISON SUMMARY
Original matches corrupted import: False
Original matches repaired copy: True
Activity
mb3581 commentedon Oct 30, 2026
I can confirm I am having this same issue. I compared an original file to one that had been imported into ABS.
The imported file has a malformed chapter table, while
raw.m4bhas the correct chapter timestamps. The FFprobe output confirms it directly.The imported file contains 55 broken chapter entries followed by 22 correctly timed entries. FFprobe is reading the malformed timestamps directly from
imported.m4b.Additional observations
One potentially relevant detail: RMAB v1.2.9 introduced additional ASIN metadata writing for M4B files after FFmpeg processing. I am wondering whether the FFmpeg remux or subsequent metadata-writing step is responsible for corrupting existing chapter timestamps.
kikootwo commentedon Nov 2, 2026
@TheJohnnyK thanks for the clear report, and @mb3581 for the ffprobe output. I can reproduce it: with "Auto-tag audio files with metadata" on, the ffmpeg build in the current image rewrites the chapter table of an M4B that has an embedded cover, the chapters come out wrong, and the import still reports success.
Until the fix is out, turn that setting off (Admin Settings > Paths, "Auto-tag audio files with metadata") so new imports keep their chapters. For a book that was already imported this way, a manual import of the original (if it's still in your download folder) or a fresh download brings the chapters back.
If you still have an original file handy, it would help to know whether this, run inside the RMAB container, gives the same broken chapters:
A fix is on the way for the next release.
kikootwo commentedon Nov 2, 2026
One correction to what I wrote above: RMAB doesn't overwrite a book file that's already in your library, so a manual import or a fresh download on its own leaves the broken copy in place. For a book that was already imported with broken chapters, delete its audio file from the book's library folder first (with "Auto-tag audio files with metadata" still off), then do the manual import of the original or the fresh download.
fix: an M4B whose chapters tagging would break is imported untagged, …
mb3581 commentedon Nov 2, 2026
Hey, thanks for looking into this.
Unfortunately I don't remember which specific book I used the other day for troubleshooting and I deleted the files when I got done with testing. I did just try it again with a couple other random original files though and neither of them showed the chapter errors after running ffmpeg -i original.m4b -codec copy -movflags +faststart -f mp4 /tmp/test.m4b.
I ended up rolling back to a previous version in the meantime and I manuall removed and re-added all the broken chapters in ABS for the affected files so I don't need to re-import anything.
docs: the chapter-track frame count is the check for #511 damage
kikootwo commentedon Nov 2, 2026
@mb3581 thanks for running that, and glad your books are sorted. Files coming out fine there fits what I found: it only happens with the ffmpeg 9 build in RMAB's image (ffmpeg 8 and earlier are fine), and only for an M4B with an embedded cover, 22.05 or 44.1 kHz audio and a chapter longer than about 8 minutes.
This is fixed in #529: with "Auto-tag audio files with metadata" on, an M4B with an embedded cover keeps all its chapters when it is tagged and when chapters are merged. It will be included in the next release, and once you're on it you can turn the setting back on.
Books that were already imported with broken chapters aren't repaired. To check one,
ffprobe -v error -select_streams d -show_entries stream=nb_frames -of csv=p=0 book.m4bshould print the book's chapter count. To repair it, delete its audio file from the library and import the original again, as described above.kikootwo commentedon Nov 3, 2026
@TheJohnnyK the fix is out now in v1.2.13: M4B files with an embedded cover keep their chapters when they're tagged. It doesn't repair books already imported with broken chapters; for those, the steps above still apply (delete the book's audio file from the library, then import it again).
fix: an M4B with a cover keeps every chapter when it is tagged or mer…