Clarification requested: per_disc_numbering behavior for multi-disc releases in beets 2.13.1

[EgLe0307]

Title

Clarification requested: per_disc_numbering behavior for multi-disc releases in beets 2.13.1

---

Hello everyone,

I'm currently evaluating beets 2.13.1 as part of a large music library migration and encountered a behavior that I cannot reconcile with the documentation.

I'm not sure whether this is the intended behavior, a documentation issue, or an implementation issue, so I would appreciate some clarification before proceeding with my migration.

---

Environment

• beets 2.13.1
• Python 3.12.13

Enabled plugins:

• musicbrainz
• fromfilename
• fetchart
• inline
• mbsubmit

---

Configuration

import:
  copy: no
  move: no
  link: no
  hardlink: yes
  write: yes
  quiet: no
  per_disc_numbering: yes

paths:
  default: $albumartist/$year - $album$release_type/$disc_prefix$track - $title

I also verified the active configuration using:

beet config

which confirms that per_disc_numbering: yes is correctly loaded.

---

What I expected

According to the documentation, I expected track numbering to restart for every disc.

Example:

Disc 1

1-01
1-02
...
1-16

Disc 2

2-01
2-02
...

---

What actually happens

The second disc continues with the global release numbering.

Example:

Disc 1

1-01
...
1-16

Disc 2

2-17
2-18
...

---

Test methodology

For every test I used exactly the same procedure:

1. Delete the beets database.
2. Remove the destination directory.
3. Copy untouched original files into a fresh test directory.
4. Verify the original metadata using ffprobe.
5. Import with beets.
6. Inspect the SQLite database.
7. Inspect the resulting filenames.
8. Verify the written ID3 tags using ffprobe.

The database was recreated before every test.

---

Test case 1

Unheilig – Lichter der Stadt

MusicBrainz Release:

1e32fca7-f84a-423c-b468-41de791124a9

Original file before import:

01. Unheilig - Brenne Auf (Demoversion).mp3

Original metadata:

track = 1
disc = 2/2

During matching beets correctly shows:

CD 2

(#1)
(#2)
(#3)
...

So MusicBrainz clearly provides disc-local numbering.

After the import:

SQLite:

disc = 2
track = 17

Written ID3 tag:

DISC = 2/2
TRCK = 17/26

Generated filename:

2-17 - Brenne auf (Demoversion).mp3

---

Test case 2

Pink Floyd – The Wall

MusicBrainz Release:

198f1c17-f002-4921-b974-f0969bfc3b32

Exactly the same behavior:

Disc 2

2-14
2-15
...

---

What has been verified

The following have been ruled out:

• incorrect YAML syntax
• configuration not being loaded
• stale database
• incorrect source tags
• incorrect disc tags
• MusicBrainz matching problems
• release-specific issue

Both tested releases produce the same result.

---

Observation

The complete processing chain looks like this:

Original file

track = 1
disc = 2

        ↓

MusicBrainz matching

CD 2
(#1)

        ↓

beets import

        ↓

SQLite

track = 17
disc = 2

        ↓

Written ID3 tags

TRCK = 17/26
DISC = 2/2

        ↓

Generated filename

2-17 - ...

---

My question

Could you clarify whether this is the expected behavior?

More specifically:

• Does $track intentionally always represent the global release position?
• If so, is the documentation for per_disc_numbering outdated or am I misunderstanding its purpose?
• If this behavior is expected, what is the recommended built-in way to generate filenames like

1-01
...
2-01
...

without using custom plugins or inline Python?

If this is not the expected behavior, the two MusicBrainz releases above should be sufficient to reproduce it.

---

Thank you very much for your time.

I intentionally avoided custom plugins or workarounds because I first wanted to understand the intended behavior of the beets core before building my migration workflow.

Bestr regards

[EgLe0307]

During additional testing I found a built-in workaround that produces a much cleaner directory layout for multi-disc albums.

Instead of relying on filename prefixes such as 1-01 / 2-01, I switched to conditional disc subdirectories using the documented %if{} path syntax:

item_fields:
multidisc: 1 if disctotal and disctotal > 1 else 0

paths:
default: $albumartist/$year - $album/%if{$multidisc,CD $disc/}$track - $title

This results in:

Album/
CD 01/
01 - ...

CD 02/
    17 - ...

This avoids filename collisions and gives a much cleaner directory structure.

However, my original question remains:

Is this the approach that the beets developers recommend for multi-disc libraries, or is there an intended built-in way to have $track restart at 01 on each disc when per_disc_numbering: yes is enabled?

I would like to stay as close as possible to the recommended beets architecture and avoid custom plugins or non-standard workarounds if possible.

[Hikari-Tsai]

per_disc_numbering is a top-level option, not an option inside the import section. In the configuration shown above, the importer therefore continues to use the default (no).

Move it out one indentation level:

per_disc_numbering: yes

import:
  copy: no
  move: no
  link: no
  hardlink: yes
  write: yes
  quiet: no

paths:
  default: $albumartist/$year - $album$release_type/$disc-$track - $title

With that setting, beets uses MusicBrainz's medium-local position for track, so the second disc starts at track 1 and tracktotal becomes the number of tracks on that disc. Including both $disc and $track in the path avoids collisions.

One subtle point: beet config displays the complete configuration tree, so seeing import.per_disc_numbering there only confirms that the YAML key was parsed; it does not mean the importer consumes that key at that location. beet config per_disc_numbering should show true after moving it.