[Enhancement]: Mapping of 'Incoming' Genres/tags to Custom/Managed Genres/tags #1209

New issue

Open

opened 2026-02-20 10:07:50 -05:00 by deekerman · 1 comment

deekerman commented

2026-02-20 10:07:50 -05:00

Owner

Originally created by @cyndane31 on GitHub (Jun 23, 2023).

Describe the feature/enhancement

What I am envioning is a method through which we can automatically replace or remove (map to blank?) genres and tags coming from the chosen metadata source into custom or alternative genres defined. This would allow for easier management and sorting of our libraries, because the industry 'standard' genres are inconsistent, frequently overly vague or specific, and just generally not always helpful.

A common example is the 'Audiobook' genre that many books are tagged with. This is one I would like to automatically discard in all cases.

An example of a merge situation would be this screenshot:

I would like to map all of these to a single common genre. There are many such examples like this.

I think an ideal, but simple, solution would be add a dropdown to each genre/tag that would allow the user to select the desired replacement. An alternative solution would add a new utility that functions similarly to the 'Find Metadata variations' from the Calibre plugin 'Find Duplicates'.
Here is a screenshot of this utility in action:

Originally created by @cyndane31 on GitHub (Jun 23, 2023). ### Describe the feature/enhancement What I am envioning is a method through which we can automatically replace or remove (map to blank?) genres and tags coming from the chosen metadata source into custom or alternative genres defined. This would allow for easier management and sorting of our libraries, because the industry 'standard' genres are inconsistent, frequently overly vague or specific, and just generally not always helpful. A common example is the 'Audiobook' genre that many books are tagged with. This is one I would like to automatically discard in all cases. An example of a merge situation would be this screenshot: ![image](https://github.com/advplyr/audiobookshelf/assets/59807241/7d54b97e-d8bd-4bf7-9aec-5cff697bd173) I would like to map all of these to a single common genre. There are many such examples like this. I think an ideal, but simple, solution would be add a dropdown to each genre/tag that would allow the user to select the desired replacement. An alternative solution would add a new utility that functions similarly to the 'Find Metadata variations' from the Calibre plugin 'Find Duplicates'. Here is a screenshot of this utility in action: ![image](https://github.com/advplyr/audiobookshelf/assets/59807241/1dedfdcd-d9f5-452a-9796-32366fbb4dcc)

deekerman added the

enhancement

possible plugin

labels

2026-02-20 10:07:50 -05:00

deekerman commented

2026-02-20 10:07:50 -05:00

Author

Owner

@nichwall commented on GitHub (Dec 9, 2023):

I spent some time thinking of a UI mockup for this, but first a few questions:

Should the genres and tags both map the same? So if you mapped "Children's Audiobooks, Action & Adventure" to "Action & Adventure" under genre, this would also map a tag the same way.
Can an incoming tag/genre be mapped to multiple other tags/genres? For example, you could map this incoming genre to two genres ("Children's Audiobooks" and "Action & Adventure"), with duplicates being removed?

The Mapping Manager (name TBD)

I think this will be best served by an additional page under the Item Metada Utils.

Mockup

This page would look something like below. At the top of the page, there is an input field. The input field only supports one input string (think audiobook title), and the Output field supports multiple strings (for everything it could map to, think like the existing "Tags" field). Both of these fields have autocomplete. The "Disable Output" toggle will clear the Output field and prevent it from being used (such as when you want to get rid of a genre). Then, the "Submit" button adds this mapping to the database. The modal applies validation to ensure the "Input" does not exist in any "Output" mapping.

This menu would probably work better as a modal behind a "add new mapping" button, and would match the UI for editing existing (see below).

The table at the bottom of the image shows all of the mappings that exist (circles represent output tags/genres). Each row has a checkbox (for multiselect to delete), the Input/Output mapping, and an edit button to edit the mapping (opens modal from the top of the mockup). There can also be a delete button the right side that I didn't add to the mockup.

In the mockup, the mapping works as follows:

"Children's Audiobooks" is deleted
"Children's Audiobooks, Action & Adventure" mapped to two tags/genres "Children" and "Action & Adventure"
"Cool Genre, Action & Adventure" is only mapped to "Action & Adventure"

There is also a button of "Apply Mapping to Existing", to apply all mappings in the table to all existing library items (in all libraries). I don't know the best way to have this apply during a scan/match since replacement at that point could cause user confusion.

Interacting with existing manager

This table may cause problems with the "Manage Tags" and "Manage Genres" pages. If tags or genres are managed from there, they should behave exactly the same as they currently do. If the tag that is edited was the output for a mapping, a confirmation popup of "This tag/genre is the output of an existing mapping. Would you like to update the mappings to the new value?" will allow The Mapping Manager to update the table automatically.

The data model

The table is stored as a dictionary, where the key is the "input string" and the value is an array of "output strings". If the array is zero, then that means the tag/genre would be deleted automatically.

Edge cases

There would need to be some validation to make sure that editing a tag/genre in the existing manager does not change to match the input of any mapping, since that could lead to unexpected mapping at a later time if a user was trying to manually change a tag/genre to something that will be automatically mapped.

@nichwall commented on GitHub (Dec 9, 2023): I spent some time thinking of a UI mockup for this, but first a few questions: 1) Should the genres and tags both map the same? So if you mapped "Children's Audiobooks, Action & Adventure" to "Action & Adventure" under genre, this would also map a tag the same way. 2) Can an incoming tag/genre be mapped to multiple other tags/genres? For example, you could map this incoming genre to two genres ("Children's Audiobooks" and "Action & Adventure"), with duplicates being removed? ### The Mapping Manager (name TBD) I think this will be best served by an additional page under the Item Metada Utils. ![mapping_utils](https://github.com/advplyr/audiobookshelf/assets/5686638/0156d28d-20cf-4fc4-a619-d872df06200e) ### Mockup This page would look something like below. At the top of the page, there is an input field. The input field only supports one input string (think audiobook title), and the Output field supports multiple strings (for everything it could map to, think like the existing "Tags" field). Both of these fields have autocomplete. The "Disable Output" toggle will clear the Output field and prevent it from being used (such as when you want to get rid of a genre). Then, the "Submit" button adds this mapping to the database. The modal applies validation to ensure the "Input" does not exist in any "Output" mapping. This menu would probably work better as a modal behind a "add new mapping" button, and would match the UI for editing existing (see below). ![manager_mockup](https://github.com/advplyr/audiobookshelf/assets/5686638/6f1a5e89-c919-4f9c-a1cc-24ab16b8c55b) The table at the bottom of the image shows all of the mappings that exist (circles represent output tags/genres). Each row has a checkbox (for multiselect to delete), the Input/Output mapping, and an edit button to edit the mapping (opens modal from the top of the mockup). There can also be a delete button the right side that I didn't add to the mockup. In the mockup, the mapping works as follows: - "Children's Audiobooks" is deleted - "Children's Audiobooks, Action & Adventure" mapped to two tags/genres "Children" and "Action & Adventure" - "Cool Genre, Action & Adventure" is only mapped to "Action & Adventure" There is also a button of "Apply Mapping to Existing", to apply all mappings in the table to all existing library items (in all libraries). I don't know the best way to have this apply during a scan/match since replacement at that point could cause user confusion. ### Interacting with existing manager This table may cause problems with the "Manage Tags" and "Manage Genres" pages. If tags or genres are managed from there, they should behave exactly the same as they currently do. If the tag that is edited was the output for a mapping, a confirmation popup of "This tag/genre is the output of an existing mapping. Would you like to update the mappings to the new value?" will allow The Mapping Manager to update the table automatically. ### The data model The table is stored as a dictionary, where the key is the "input string" and the value is an array of "output strings". If the array is zero, then that means the tag/genre would be deleted automatically. ### Edge cases There would need to be some validation to make sure that editing a tag/genre in the existing manager does not change to match the input of any mapping, since that could lead to unexpected mapping at a later time if a user was trying to manually change a tag/genre to something that will be automatically mapped.