Skip to content

Bug: Metadata tagging corrupts existing M4B chapter markers #511

Closed

Description

@TheJohnnyK

ReadMeABook version

v1.2.12

Deployment type

Unified Docker image

Media backend

Audiobookshelf

Steps to reproduce

  1. Deploy ReadMeABook using the unified Docker container.
  2. Configure Audiobookshelf as the media backend.
  3. Enable Metadata Tagging in ReadMeABook.
  4. Enable Chapter Merging (although merging will be skipped for a single-file M4B).
  5. Download or import an existing M4B that already contains valid embedded chapter markers.
  6. Allow ReadMeABook to tag the audio file and copy the processed version into the audiobook library.
  7. 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.140

Additional 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:

  1. Disabled Metadata Tagging in ReadMeABook.

  2. Restored a copy of the untouched downloaded M4B into the audiobook library.

  3. Confirmed the restored file's chapter markers using FFprobe.

  4. Removed the stale Audiobookshelf library entry without deleting files.

  5. 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

  1. mb3581 commented on Oct 30, 2026

    @mb3581

    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.m4b has the correct chapter timestamps. The FFprobe output confirms it directly.

    Chapter raw.m4b imported.m4b
    Chapter 5 12:33–15:12 12:33–12:33
    Chapter 7 15:12–24:04 12:33–12:33.001
    Chapter 53 6:09:03–6:13:23 12:33.011–13:11.289
    Chapter 54 6:13:23–6:19:17 6:13:23–6:19:17

    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

    • The original M4B is already a single-file audiobook with 77 valid chapter markers.
    • Chapter Merging was enabled, but this file did not require merging.
    • The imported file retains the same audio duration as the original.
    • The imported file has 77 chapter entries, but the first 55 have malformed timestamps. The remaining 22 entries retain their correct timestamps.
    • SHA256 hashes confirm the original and imported files are different.

    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.

  2. kikootwo commented on Nov 2, 2026

    @kikootwo
    Owner

    @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:

    ffmpeg -i original.m4b -codec copy -movflags +faststart -f mp4 /tmp/test.m4b
    ffprobe -v error -show_chapters /tmp/test.m4b
    

    A fix is on the way for the next release.

  3. kikootwo commented on Nov 2, 2026

    @kikootwo
    Owner

    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.

  4. mb3581 commented on Nov 2, 2026

    @mb3581

    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.

  5. kikootwo commented on Nov 2, 2026

    @kikootwo
    Owner

    @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.m4b should print the book's chapter count. To repair it, delete its audio file from the library and import the original again, as described above.

  6. kikootwo commented on Nov 3, 2026

    @kikootwo
    Owner

    @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).

  7. added a commit that references this issue on Nov 3, 2026
    aa3841f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ReleasedbugSomething isn't workingdev-completedev work is completed, being tested or awaiting release

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions