Skip to content

Bug: Chapter merging renumbers valid embedded chapter titles after an introduction #509

Closed

Description

@TheJohnnyK

ReadMeABook version

v1.2.12

Deployment type

Unified Docker image

Media backend

Audiobookshelf

Steps to reproduce

  1. Enable Chapter Merging in ReadMeABook.

  2. Import a multi-file MP3 audiobook containing an introduction followed by numbered chapters.

  3. In this case, I imported Project Hail Mary, containing 32 MP3 files.

  4. The source files have the following embedded ID3 metadata:

File | Title metadata | Track -- | -- | -- Project Hail Mary (01).mp3 | Intro & Dedication | 1/32 Project Hail Mary (02).mp3 | Chapter 1 | 2/32 Project Hail Mary (03).mp3 | Chapter 2 | 3/32
  1. Allow ReadMeABook to merge the files into a single M4B.

  2. Examine the generated chapter titles in Audiobookshelf or using ffprobe.

The problem occurs even with Metadata Tagging disabled. The source MP3 files contain the correct titles, and ReadMeABook correctly identifies their playback order.

Expected behavior

ReadMeABook should preserve valid embedded chapter titles when merging MP3 files.

The resulting chapter sequence should be:

  • Intro & Dedication
  • Chapter 1
  • Chapter 2
  • Chapter 3

Introductory tracks should not cause subsequent chapter labels to be renumbered.

Actual behavior

ReadMeABook correctly orders the audio files but generates incorrect chapter titles.

The resulting sequence is:

  • Intro & Dedication
  • Chapter 2
  • Chapter 3
  • Chapter 4

The source file titled "Chapter 1" becomes "Chapter 2" in the merged M4B.

Suspected cause:

In src/lib/utils/chapter-merger.ts, GENERIC_TITLE_PATTERNS includes a pattern that classifies titles such as "Chapter 1" as generic.

The getChapterTitle() function then ignores that valid embedded title and falls back to Chapter ${index + 1}.

Because "Intro & Dedication" occupies the first position, all subsequent chapter labels are shifted by one.

The chapter audio ordering appears correct; the issue is with the generated titles.

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 deployed through TrueNAS SCALE Apps using an automatically generated Docker Compose configuration, rather than a manually executed `docker run` command.

**Service configuration:**

services:
  readmeabook:
    image: ghcr.io/kikootwo/readmeabook:latest


**Environment variables configured:**
- `PGID`
- `PUID`
- `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 configuration.

The above is a sanitized configuration summary, not the complete generated Compose file. Host filesystem paths and environment variable values are omitted.

**Relevant ReadMeABook settings:**
- Chapter Merging: Enabled
- Metadata Tagging: Disabled
- Media backend: Audiobookshelf

Logs

## ReadMeABook Chapter-Merging Logs

**Audiobook:** Project Hail Mary — Andy Weir  
**Source:** 32 MP3 files  
**Chapter Merging:** Enabled  
**Metadata Tagging:** Disabled  
**Deployment:** TrueNAS SCALE, Unified Docker container

### 1. File discovery and chapter analysis

The following logs were captured directly from the running ReadMeABook container:


[INFO] [OrganizeFiles] Request type: audiobook
[INFO] [OrganizeFiles] Organizing: Project Hail Mary by Andy Weir
[INFO] [OrganizeFiles] Initial metadata from audiobook record: year=2021, narrator=Ray Porter
[INFO] [OrganizeFiles] Missing series data, fetching from Audnexus for ASIN: B08G9PRS1K
[INFO] [Audible]  Fetching details for ASIN B08G9PRS1K...
[INFO] [Audible]  Successfully fetched from Audnexus for "Project Hail Mary"
[INFO] [OrganizeFiles] Final metadata for path organization: year=2021, narrator=Ray Porter, series=null, seriesPart=null
[INFO] [FileOrganizer] Found 32 audio files
[INFO] [FileOrganizer] Multiple audio files detected (32 files) - checking chapter merge settings...
[INFO] [FileOrganizer] Chapter merging enabled - analyzing files...
[INFO] [FileOrganizer] Chapter detection: 32 files with format .mp3 - attempting chapter merge
[INFO] [FileOrganizer] Analyzing 32 chapter files...
[INFO] [FileOrganizer] Sample filenames: Project Hail Mary (01).mp3, Project Hail Mary (02).mp3, Project Hail Mary (03).mp3, ...
[INFO] [FileOrganizer] Metadata analysis: 32/32 files have track numbers
[INFO] [FileOrganizer] Track numbers: 1, 2, 3 ... 32
[INFO] [FileOrganizer] Chapter ordering: Filename and metadata orders match - high confidence
[INFO] [FileOrganizer] Using filename-based ordering for 32 chapters
[INFO] [FileOrganizer] Sample chapter titles: Ch1: "Intro & Dedication", Ch2: "Chapter 2", Ch3: "Chapter 3", ...


**Important:** The incorrect chapter titles are already present in the analysis logs, before merging or audio encoding begins.

### 2. Original source MP3 metadata

The source files were independently inspected using FFprobe.


=== Project Hail Mary (01).mp3 ===
TAG:title=Intro & Dedication
TAG:track=1/32

=== Project Hail Mary (02).mp3 ===
TAG:title=Chapter 1
TAG:track=2/32

=== Project Hail Mary (03).mp3 ===
TAG:title=Chapter 2
TAG:track=3/32


The source MP3s contain correct, track-specific title metadata.

### 3. Chapter merge preparation


[INFO] [FileOrganizer] Starting chapter merge: "Project Hail Mary" by Andy Weir
[INFO] [FileOrganizer] Output: Project Hail Mary.m4b
[INFO] [FileOrganizer] Total duration: 16h 10m 52s, Estimated size: 492MB
[INFO] [FileOrganizer] Validating source files...
[INFO] [FileOrganizer] ✓ All 32 source files validated
[INFO] [FileOrganizer] Created concat list with 32 files
[INFO] [FileOrganizer] Generated chapter metadata with 32 chapter markers
[INFO] [FileOrganizer] Merge strategy: Re-encoding MP3 → AAC/M4B using native AAC VBR (quality 1.5, target ~66k)
[INFO] [FileOrganizer] Executing FFmpeg merge (timeout: 255 minutes)...
[INFO] [FileOrganizer] This is a long audiobook (16h). Encoding may take 97-194 minutes depending on CPU speed.


The captured excerpt also contains encoding progress through 40%. The final merge-completion log is not included in this excerpt.

### 4. Expected versus actual chapter titles

| Track position | Source ID3 title | Generated chapter title |
|---|---|---|
| 1 | Intro & Dedication | Intro & Dedication |
| 2 | Chapter 1 | Chapter 2 |
| 3 | Chapter 2 | Chapter 3 |

### 5. Findings and suspected cause

The logs establish that:

1. All 32 MP3 files were recognized.
2. Every file contained track-number metadata.
3. ReadMeABook confirmed the ordering was consistent.
4. The original files contained correct embedded titles.
5. ReadMeABook generated incorrect titles before invoking FFmpeg.

The likely cause is in `src/lib/utils/chapter-merger.ts`, where `GENERIC_TITLE_PATTERNS` classifies `Chapter N` as generic and `getChapterTitle()` replaces it with a positional fallback:


return `Chapter ${index + 1}`;


Because the introduction occupies the first position, the positional fallback incorrectly labels the second file as `Chapter 2`, despite its original title being `Chapter 1`.

**Suggested fix:** Preserve valid embedded chapter-number titles where they are track-specific, rather than replacing them with positional chapter numbers.

A regression test containing an introductory track followed by correctly numbered chapters should reproduce this behavior.

Activity

  1. mvanhorn commented on Nov 2, 2026

    @mvanhorn
    Contributor

    getChapterTitle() treated embedded “Chapter N” titles as generic and replaced them with numbering based on file position. An introduction occupies the first position, so the fallback numbers no longer match the embedded chapter labels.

    Accept embedded numbered chapter titles while preserving their original case and zero padding. Filename-derived names retain priority, titles identified as the book title remain excluded, and other generic titles still use fallback numbering.

    #525

  2. kikootwo commented on Nov 2, 2026

    @kikootwo
    Owner

    Thanks for the detailed report. This is fixed in #531: when a book's files are tagged "Intro", "Chapter 1", "Chapter 2" and so on, the merged book keeps those names instead of shifting each chapter by one. Sets whose tags restart at "Chapter 1" on each disc keep position numbering as before. It will be included in the next release. Books that were already merged keep their current names.

  3. kikootwo commented on Nov 3, 2026

    @kikootwo
    Owner

    @TheJohnnyK this is out now in v1.2.13: a merged book keeps embedded "Intro", "Chapter 1", "Chapter 2" names instead of shifting them by one.

  4. added a commit that references this issue on Nov 3, 2026
    abcd464
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