starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-08-29 14:47:20 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[Enhancement]: Metadata Scanner should be able to add multiple Series (or Sub-Series) via the additonal metadata sources #3082

New Issue
Open
opened 2026-04-25 00:13:34 +02:00 by adam · 0 comments
adam commented 2026-04-25 00:13:34 +02:00
Owner
Copy Link
Copy Source

Originally created by @saltedlolly on GitHub (Nov 11, 2025).

Type of Enhancement

Server Backend

Describe the Feature/Enhancement

In this issue, I propose an improvement to how the metadata scanner operates to better allow for adding multiple series to a single audiobook. Currently, only the first series found is added (unless you list multiple in the CONTENTGROUP meta tag - more on this below).

Additional metadata sources should be able to add other series, or sub-series, provided they have not already been added from a previous source.

A Detailed Explanation

Organizing multiple series via folders and meta tags

For this explanation, I will use the following example audiobook which can potentially belong to multiple series:

Example Audiobook
Title The Alloy of Law
Author Brandon Sanderson
Series The Cosmere #16
The Mistborn Saga #4
Mistborn: Wax & Wayne #1

It is currently possible to add multiple series to the CONTENTGROUP id3 tag so all three series could be added in the meta tags like so:

ID3 v2.3 metadata tag
CONTENTGROUP The Cosmere #16; The Mistborn Saga #4; Mistborn: Wax & Wayne #1

However, there is a condiderable downside to this, particularly with large series, where the sequence numbering may change over time. If a new book later gets added to the middle of the sequence of the Cosmere, you need to update the mp3 metadata of many of your other books simple to accomodate this one change.

A better solution is to organize in this hybrid method using both meta tags and folder structure. The book goes in this folder to set it to "The Cosmere #16":

/Brandon Sanderson/The Cosmere/Vol 16 - The Allow of Law

Then in the file meta tags you can include additional sub-series like this:

ID3 v2.3 metadata tag
CONTENTGROUP The Mistborn Saga #4; Mistborn: Wax & Wayne #1

This makes it easy to quickly adjust the overall book order in "The Cosmere" series by changing vol number in the folder name, without needing to touch the metadata of any other books in the series.

The sub-series numbering are less likely to change, and also only require changing a few files if they do. This keeps things cleanly organized, while also supporting multiple series per book.

Now to the scanning part...

Scanning multiple series for a single book

Let's assume for this example that our scanner priority is set as follows:

Metadata order or precendence
1 Audiobookshelf metadata file OFF
2 OPF file OFF
3 desc.txt & reader.txt files ON
4 Audio file meta tags OR ebook metadata ON
5 Folder structure ON
6 NFO file OFF

The problem right now is that when Audiobookshelf scanner finds the CONTENTGROUP entry in the audio file meta tag, it sets this as the series and then ignores any additional series sources. (e.g. a series set in the folder stucture is ignored, simply because the series was already set via the meta tags.)

The Solution

I propose that scanner be changed to allow it to append another series or sub-series, from a later metadata source, provided the same series has not already been added via a prior metadata source.

So in the above example, when scanning the meta tags it would find and add the series:

The Mistborn Saga #4
Mistborn: Wax & Wayne #1

Then when it scans the folder structure, it will see that book is also in "The Cosmere" (Vol 16). Since "The Cosmere" series has not already been added via the meta tags, it will add it as an additional series for the same book:

The Cosmere #16

Important

The higher priority scanner will always take precedence, so a series that exists in multiple sources will use the first one it finds based on the metadata order of precedence, unless the latter series entry includes a number and the former does not.

So in the above example, if the folder structure remained the same, but the audio file meta tags contained:

ID3 v2.3 metadata tag
CONTENTGROUP The Cosmere #20; The Mistborn Saga #4; Mistborn: Wax & Wayne #1

Then the series added would be:

The Cosmere #20
The Mistborn Saga #4
Mistborn: Wax & Wayne #1

(The Cosmere is not #16 as set in the folder structure, as the #20 was found first, and that takes precedence.)

Similarly, if The Cosmere was set in the first source but without a series number:

ID3 v2.3 metadata tag
CONTENTGROUP The Cosmere; The Mistborn Saga #4; Mistborn: Wax & Wayne #1

Then the series added would be:

The Cosmere #16
The Mistborn Saga #4
Mistborn: Wax & Wayne #1

This is because if the first source has no series number, but the second source does, it will add the latter number. If the first source has a series number The Cosmere #16 and the second source does not, then the first source would take precedence, since a series number is already set.

Why would this be helpful?

Benefits

The advantage of this improvement to the scanner, is that multiple sources that individually can only specify a single series and number (such as using folder structure) can be supplemented to add additional series via a secondary source (such as via the meta tags).

It also allows users to organize their books into series folders, helping to keep their audiobooks well organized, while still being able to include metadata for sub-series, and other series outside of the current folder structure.

It also means for that for series that are only part of a single series, you can rely solely on folder structure, which makes it very quick and easy to organize you audiobooks for use in Audiobookshelf.

Future Implementation (Screenshot)

I explained this in detail above.

Audiobookshelf Server Version

v2.30.0

Current Implementation (Screenshot)

The scanner currently only uses the series metadata from the first source it finds, and ignores any additional series. In many cases, this means that only a single series per book can ve added via the scanner, escially if relying on folder structure.

Originally created by @saltedlolly on GitHub (Nov 11, 2025). ### Type of Enhancement Server Backend ### Describe the Feature/Enhancement In this issue, I propose an improvement to how the metadata scanner operates to better allow for adding multiple series to a single audiobook. Currently, only the first series found is added (unless you list multiple in the CONTENTGROUP meta tag - more on this below). Additional metadata sources should be able to add other series, or sub-series, provided they have not already been added from a previous source. ## A Detailed Explanation ### Organizing multiple series via folders and meta tags For this explanation, I will use the following example audiobook which can potentially belong to multiple series: <table> <tr> <td colspan="2" style="text-align: center;">Example Audiobook</td> </tr> <tr> <td style="text-align: right;">Title</td> <td>The Alloy of Law</td> </tr> <tr> <td style="text-align: right;">Author</td> <td>Brandon Sanderson</td> </tr> <tr> <td rowspan="3" style="vertical-align: top;">Series</td> <td>The Cosmere <span>#</span>16</td> </tr> <tr> <td>The Mistborn Saga <span>#</span>4</td> </tr> <tr> <td>Mistborn: Wax & Wayne <span>#</span>1</td> </tr> </table> It is currently possible to add multiple series to the CONTENTGROUP id3 tag so all three series could be added in the meta tags like so: <table> <tr> <td colspan="2" style="text-align: center;">ID3 v2.3 metadata tag</td> </tr> <tr> <td>CONTENTGROUP</td> <td>The Cosmere <span>#</span>16; The Mistborn Saga <span>#</span>4; Mistborn: Wax & Wayne <span>#</span>1</td> </tr> </table> However, there is a condiderable downside to this, particularly with large series, where the sequence numbering may change over time. If a new book later gets added to the middle of the sequence of the Cosmere, you need to update the mp3 metadata of many of your other books simple to accomodate this one change. A better solution is to organize in this hybrid method using both meta tags and folder structure. The book goes in this folder to set it to "The Cosmere <span>#</span>16": /Brandon Sanderson/The Cosmere/Vol 16 - The Allow of Law Then in the file meta tags you can include additional sub-series like this: <table> <tr> <td colspan="2" style="text-align: center;">ID3 v2.3 metadata tag</td> </tr> <tr> <td>CONTENTGROUP</td> <td>The Mistborn Saga <span>#</span>4; Mistborn: Wax & Wayne <span>#</span>1</td> </tr> </table> This makes it easy to quickly adjust the overall book order in "The Cosmere" series by changing vol number in the folder name, without needing to touch the metadata of any other books in the series. The sub-series numbering are less likely to change, and also only require changing a few files if they do. This keeps things cleanly organized, while also supporting multiple series per book. Now to the scanning part... ### Scanning multiple series for a single book Let's assume for this example that our scanner priority is set as follows: <table> <tr> <td colspan="3" style="text-align: center;">Metadata order or precendence</td> </tr> <tr> <td>1</td> <td>Audiobookshelf metadata file</td> <td>OFF</td> </tr> <tr> <td>2</td> <td>OPF file</td> <td>OFF</td> </tr> <tr> <td>3</td> <td>desc.txt & reader.txt files</td> <td>ON</td> </tr> <tr> <td>4</td> <td>Audio file meta tags OR ebook metadata</td> <td>ON</td> </tr> <tr> <td>5</td> <td>Folder structure</td> <td>ON</td> </tr> <tr> <td>6</td> <td>NFO file</td> <td>OFF</td> </tr> </table> The problem right now is that when Audiobookshelf scanner finds the CONTENTGROUP entry in the audio file meta tag, it sets this as the series and then ignores any additional series sources. (e.g. a series set in the folder stucture is ignored, simply because the series was already set via the meta tags.) ## The Solution I propose that scanner be changed to allow it to append another series or sub-series, from a later metadata source, provided the same series has not already been added via a prior metadata source. So in the above example, when scanning the meta tags it would find and add the series: `The Mistborn Saga #4` `Mistborn: Wax & Wayne #1` Then when it scans the folder structure, it will see that book is also in "The Cosmere" (Vol 16). Since "The Cosmere" series has not already been added via the meta tags, it will add it as an additional series for the same book: `The Cosmere #16` ### Important The higher priority scanner will always take precedence, so a series that exists in multiple sources will use the first one it finds based on the metadata order of precedence, <em>unless the latter series entry includes a number and the former does not.</em> So in the above example, if the folder structure remained the same, but the audio file meta tags contained: <table> <tr> <td colspan="2" style="text-align: center;">ID3 v2.3 metadata tag</td> </tr> <tr> <td>CONTENTGROUP</td> <td>The Cosmere <span>#</span>20; The Mistborn Saga <span>#</span>4; Mistborn: Wax & Wayne <span>#</span>1</td> </tr> </table> Then the series added would be: `The Cosmere #20` `The Mistborn Saga #4` `Mistborn: Wax & Wayne #1` (The Cosmere is not `#16` as set in the folder structure, as the `#20` was found first, and that takes precedence.) Similarly, if The Cosmere was set in the first source but without a series number: <table> <tr> <td colspan="2" style="text-align: center;">ID3 v2.3 metadata tag</td> </tr> <tr> <td>CONTENTGROUP</td> <td>The Cosmere; The Mistborn Saga <span>#</span>4; Mistborn: Wax & Wayne <span>#</span>1</td> </tr> </table> Then the series added would be: `The Cosmere #16` `The Mistborn Saga #4` `Mistborn: Wax & Wayne #1` This is because if the first source has no series number, but the second source does, it will add the latter number. If the first source has a series number `The Cosmere #16` and the second source does not, then the first source would take precedence, since a series number is already set. ### Why would this be helpful? ## Benefits The advantage of this improvement to the scanner, is that multiple sources that individually can only specify a single series and number (such as using folder structure) can be supplemented to add additional series via a secondary source (such as via the meta tags). It also allows users to organize their books into series folders, helping to keep their audiobooks well organized, while still being able to include metadata for sub-series, and other series outside of the current folder structure. It also means for that for series that are only part of a single series, you can rely solely on folder structure, which makes it very quick and easy to organize you audiobooks for use in Audiobookshelf. ### Future Implementation (Screenshot) I explained this in detail above. ### Audiobookshelf Server Version v2.30.0 ### Current Implementation (Screenshot) The scanner currently only uses the series metadata from the first source it finds, and ignores any additional series. In many cases, this means that only a single series per book can ve added via the scanner, escially if relying on folder structure.
adam added the enhancement label 2026-04-25 00:13:34 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No labels enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#3082