starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[Enhancement]: Support for supplementary image gallery for audiobooks - maps, charts, illustrations, photos, concept art, print book covers #3140

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

Originally created by @saltedlolly on GitHub (Dec 5, 2025).

Type of Enhancement

Server Backend

Describe the Feature/Enhancement

Many audiobooks include supplementary materials - maps, supplementary PDFs, cover art, photos, etc.

I would like to propose that Audiobookshelf adds support for some standardized audiobook sub-folders for these (in addition to the currently permitted "Disk #/CD #" folders).

These sub-folders can contain the supplementary materials for a book, aside from the main ebook itself which remains in the main folder. When the metadata scanner encounters these folders it imports the contained files into ABS to display alongside the book.

To help the metadata scanner to easily recognize these folders, I would suggest that they use square brackets to denote them so it is very clear what they contain:

"/Author/Series/Book Title/[Maps]

Contains maps relate to the book. This is useful for fantasy and science fiction books(jpg/jpeg/png/webp) as well as many non-fiction books. These can then be displayed alongside the book. The filename minus extension will be the caption for the file within ABS.

"/Author/Series/Book Title/[Supplements]

Contains supplementary pdf/ePub. Many audiobooks, particularly non-fiction inlclude a supplementary PDF (or possibly ePub) which contains figures/charts/images/glossary/family trees/dramatis personae etc. from the book. It goes in this folder. This is not for the eBook itself which is in the parent folder. The filename minus extension will be the caption for the file within ABS.

"/Author/Series/Book Title/[Artwork]

Contains all additional artwork (jpg/jpeg/png/bmp/tif/webp etc.) that you might want to view alongside the book. These might be paperback covers, concept art, illustrations, photos etc. These can be organized into sub-folders that form albums. The filename minus extension will be the caption for the file within ABS.

Additionally, it could be possible to include any of these book sub-folders as a sub-folder of the Series folder so that they show up for every book within that series, and alongside the series itself. This could be useful for charts that display a recommended reading orders for the series, or maps that apply to the entire series.

"/Author/Series/[Maps]
"/Author/Series/[Supplements]
"/Author/Series/[Artwork]

Why would this be helpful?

Firstly it will give Audiobookshelf clients the ability to display these items alongside the book. When reading a fantasy book you can quickly access the maps or glossary. With non-fiction, you have access access to the supplementary PDF. Or for avid collectors you can browse the album of additional artwork, be it photos from the book, concept art, book covers etc..

Secondly, it would solve the current issue that any images in the audiobook folder get used as the audiobook cover whether you want this are not. By moving the images into one of these sub-folders they can be ignored as the audiobook cover. Only images in the main audiobook folder will be used as the audiobook cover art.

Future Implementation (Screenshot)

There could be additional sections below the book description with thumbnails that can be tapped on form each item.

Audiobookshelf Server Version

v2.31.0

Current Implementation (Screenshot)

No response

Originally created by @saltedlolly on GitHub (Dec 5, 2025). ### Type of Enhancement Server Backend ### Describe the Feature/Enhancement Many audiobooks include supplementary materials - maps, supplementary PDFs, cover art, photos, etc. I would like to propose that Audiobookshelf adds support for some standardized audiobook sub-folders for these (in addition to the currently permitted "Disk #/CD #" folders). These sub-folders can contain the supplementary materials for a book, aside from the main ebook itself which remains in the main folder. When the metadata scanner encounters these folders it imports the contained files into ABS to display alongside the book. To help the metadata scanner to easily recognize these folders, I would suggest that they use square brackets to denote them so it is very clear what they contain: "/Author/Series/Book Title/[Maps] Contains maps relate to the book. This is useful for fantasy and science fiction books(jpg/jpeg/png/webp) as well as many non-fiction books. These can then be displayed alongside the book. The filename minus extension will be the caption for the file within ABS. "/Author/Series/Book Title/[Supplements] Contains supplementary pdf/ePub. Many audiobooks, particularly non-fiction inlclude a supplementary PDF (or possibly ePub) which contains figures/charts/images/glossary/family trees/dramatis personae etc. from the book. It goes in this folder. This is not for the eBook itself which is in the parent folder. The filename minus extension will be the caption for the file within ABS. "/Author/Series/Book Title/[Artwork] Contains all additional artwork (jpg/jpeg/png/bmp/tif/webp etc.) that you might want to view alongside the book. These might be paperback covers, concept art, illustrations, photos etc. These can be organized into sub-folders that form albums. The filename minus extension will be the caption for the file within ABS. Additionally, it could be possible to include any of these book sub-folders as a sub-folder of the Series folder so that they show up for every book within that series, and alongside the series itself. This could be useful for charts that display a recommended reading orders for the series, or maps that apply to the entire series. "/Author/Series/[Maps] "/Author/Series/[Supplements] "/Author/Series/[Artwork] ### Why would this be helpful? Firstly it will give Audiobookshelf clients the ability to display these items alongside the book. When reading a fantasy book you can quickly access the maps or glossary. With non-fiction, you have access access to the supplementary PDF. Or for avid collectors you can browse the album of additional artwork, be it photos from the book, concept art, book covers etc.. Secondly, it would solve the current issue that any images in the audiobook folder get used as the audiobook cover whether you want this are not. By moving the images into one of these sub-folders they can be ignored as the audiobook cover. Only images in the main audiobook folder will be used as the audiobook cover art. ### Future Implementation (Screenshot) There could be additional sections below the book description with thumbnails that can be tapped on form each item. ### Audiobookshelf Server Version v2.31.0 ### Current Implementation (Screenshot) _No response_
adam added the enhancementwaiting labels 2026-04-25 00:13:51 +02:00
adam commented 2026-04-25 00:13:51 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (Dec 6, 2025):

I'm confused by what you are requesting, as supplemental ebooks was the original use case for ebooks in ABS (limited progress tracking support was added later) and is already supported.

These supplemental files can already be added to a library item, regardless of whether they are in the same folder or a subfolder. You can also read/view supplemental files while listening to the book.

The Audiobookshelf server does not move or reorganize files, so this would still need to be handled external to ABS when adding supplemental files.

@nichwall commented on GitHub (Dec 6, 2025): I'm confused by what you are requesting, as supplemental ebooks was the original use case for ebooks in ABS (limited progress tracking support was added later) and is already supported. These supplemental files can already be added to a library item, regardless of whether they are in the same folder or a subfolder. You can also read/view supplemental files while listening to the book. The Audiobookshelf server does not move or reorganize files, so this would still need to be handled external to ABS when adding supplemental files.
adam commented 2026-04-25 00:13:51 +02:00
Author
Owner
Copy Link
Copy Source

@saltedlolly commented on GitHub (Dec 6, 2025):

This is not for the eBook itself, this is for organising the supplementary PDFs that frequently come alongside many audiobooks. These do not contain the entire book, so progress tracking is irrelevant. They usually contain just the illustrations, charts, pictures, family trees etc. from the book. I accept that currently this sort of works in that they can be viewed but there is no distinction between the main ebook that contains the entire book, and these supplementary PDFs which are very common.

The bigger issue is with images currently in the book folder, or any sub-folders. These are always getting used as the audiobook cover art, regardless of whether you want them to be. Sometimes the desired cover artwork is embedded in the audio files, but any images in these folders is taking precedence, and instead being used as the cover in ABS in place of the embedded cover. There is no way to prioritize the embedded cover. This did not happen in Plex. There really needs a way to let us organise these images to prevent this from happening - both to make it is easy to ensure the correct piece of cover art is used, and to organize how the rest of supplemental material - maps, pictures, supplentry pdfs - is presented within ABS. Currently the only way I have found to get ABS to ignore other images is to compress them into a zip - not much of a solution, since you really want to be able to view them in ABS, just not as the cover art.

For example, perhaps you have "The Lord of the Rings" audiobooks in separate folders each containing the audiobook audio files with embedded cover art, the main ebook (ePub), the maps (jpgs), Glossary & Appendices (as supplementary PDFs), and a folder of images of John Howe's artwork for the books. Currently any images in the book folder (or its sub-folders) are automatically imported as the audiobook cover art, overwriting the embedded cover art, and there is no way to have the metadata scanner ignore them. This way you frequently end up with a map or picture as the cover art, and there is no easy way to prevent it. Supplementary ebooks are treated as if the are the main ebooks - there is no distinction. There is currently no way to organise and display this material alongside the book.

The most important reason is to solve the problem of supplementary artwork like the original paperback covers or maps getting mistakenly used as the audiobook cover art, but it would also great to be able to easily view any maps or supplementary materials whilst listening to the book. Artwork in the main folder should be used as cover art. Artwork in any of these sub-folders should be ignored as cover art.

@saltedlolly commented on GitHub (Dec 6, 2025): This is not for the eBook itself, this is for organising the supplementary PDFs that frequently come alongside many audiobooks. These do not contain the entire book, so progress tracking is irrelevant. They usually contain just the illustrations, charts, pictures, family trees etc. from the book. I accept that currently this sort of works in that they can be viewed but there is no distinction between the main ebook that contains the entire book, and these supplementary PDFs which are very common. The bigger issue is with images currently in the book folder, or any sub-folders. These are always getting used as the audiobook cover art, regardless of whether you want them to be. Sometimes the desired cover artwork is embedded in the audio files, but any images in these folders is taking precedence, and instead being used as the cover in ABS in place of the embedded cover. There is no way to prioritize the embedded cover. This did not happen in Plex. There really needs a way to let us organise these images to prevent this from happening - both to make it is easy to ensure the correct piece of cover art is used, and to organize how the rest of supplemental material - maps, pictures, supplentry pdfs - is presented within ABS. Currently the only way I have found to get ABS to ignore other images is to compress them into a zip - not much of a solution, since you really want to be able to view them in ABS, just not as the cover art. For example, perhaps you have "The Lord of the Rings" audiobooks in separate folders each containing the audiobook audio files with embedded cover art, the main ebook (ePub), the maps (jpgs), Glossary & Appendices (as supplementary PDFs), and a folder of images of John Howe's artwork for the books. Currently any images in the book folder (or its sub-folders) are automatically imported as the audiobook cover art, overwriting the embedded cover art, and there is no way to have the metadata scanner ignore them. This way you frequently end up with a map or picture as the cover art, and there is no easy way to prevent it. Supplementary ebooks are treated as if the are the main ebooks - there is no distinction. There is currently no way to organise and display this material alongside the book. The most important reason is to solve the problem of supplementary artwork like the original paperback covers or maps getting mistakenly used as the audiobook cover art, but it would also great to be able to easily view any maps or supplementary materials whilst listening to the book. Artwork in the main folder should be used as cover art. Artwork in any of these sub-folders should be ignored as cover art.
adam commented 2026-04-25 00:13:52 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (Dec 6, 2025):

To summarize, you just want image files to be treated as supplemental material the same way as supplemental ebooks/PDF?

@nichwall commented on GitHub (Dec 6, 2025): To summarize, you just want image files to be treated as supplemental material the same way as supplemental ebooks/PDF?
adam commented 2026-04-25 00:13:52 +02:00
Author
Owner
Copy Link
Copy Source

@saltedlolly commented on GitHub (Dec 6, 2025):

Not exactly. I want what I explained above:

  1. An agreed upon folder structure for organizing supplementary materials associated with an audiobook, so that those images/pdfs/epubs can be organized alongside the book within ABS. E.g. maps, artwork, photos, or supplementary pdfs.
  2. A distinction between the ebook of the audiobook (the full book which might support progress tracking like whispersync) and any additional pdfs/epubs containing reference materials for the audiobook. These two are not the same.
  3. The means to limit which local image files are used as audiobook covers art (which point 1 would enable).

Important: When I say ebook, I mean the entire book in ebook form - identical to the printed book. Not simply a supplementary document (pdf/epub) that contains reference material for the audiobook itself.

Clear?

@saltedlolly commented on GitHub (Dec 6, 2025): Not exactly. I want what I explained above: 1. An agreed upon folder structure for organizing supplementary materials associated with an audiobook, so that those images/pdfs/epubs can be organized alongside the book within ABS. E.g. maps, artwork, photos, or supplementary pdfs. 2. A distinction between the ebook of the audiobook (the full book which might support progress tracking like whispersync) and any additional pdfs/epubs containing reference materials for the audiobook. These two are not the same. 3. The means to limit which local image files are used as audiobook covers art (which point 1 would enable). Important: When I say ebook, I mean the entire book in ebook form - identical to the printed book. Not simply a supplementary document (pdf/epub) that contains reference material for the audiobook itself. Clear?
adam commented 2026-04-25 00:13:52 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (Dec 6, 2025):

  1. An agreed upon folder structure for organizing supplementary materials associated with an audiobook, so that those images/pdfs/epubs can be organized alongside the book within ABS. E.g. maps, artwork, photos, or supplementary pdfs.

You can already put supplemental material (specifically ebooks) in subfolders and have them show up as supplemental for reference while listening to an audiobook.

  1. A distinction between the ebook of the audiobook (the full book which might support progress tracking like whispersync) and any additional pdfs/epubs containing reference materials for the audiobook. These two are not the same.

This has been implemented for several years which I think is where my confusion is coming from. https://www.audiobookshelf.org/guides/ebooks

  1. The means to limit which local image files are used as audiobook covers art (which point 1 would enable).

So this is just allowing images to be added as supplemental and viewed like other supplemental files?

@nichwall commented on GitHub (Dec 6, 2025): > 1. An agreed upon folder structure for organizing supplementary materials associated with an audiobook, so that those images/pdfs/epubs can be organized alongside the book within ABS. E.g. maps, artwork, photos, or supplementary pdfs. You can already put supplemental material (specifically ebooks) in subfolders and have them show up as supplemental for reference while listening to an audiobook. > 2. A distinction between the ebook of the audiobook (the full book which might support progress tracking like whispersync) and any additional pdfs/epubs containing reference materials for the audiobook. These two are not the same. This has been implemented for several years which I think is where my confusion is coming from. https://www.audiobookshelf.org/guides/ebooks > 3. The means to limit which local image files are used as audiobook covers art (which point 1 would enable). So this is just allowing images to be added as supplemental and viewed like other supplemental files?
adam commented 2026-04-25 00:13:53 +02:00
Author
Owner
Copy Link
Copy Source

@advplyr commented on GitHub (Dec 6, 2025):

It looks like for the most part this is already supported

@advplyr commented on GitHub (Dec 6, 2025): It looks like for the most part this is already supported
adam commented 2026-04-25 00:13:53 +02:00
Author
Owner
Copy Link
Copy Source

@saltedlolly commented on GitHub (Dec 7, 2025):

  1. An agreed upon folder structure for organizing supplementary materials associated with an audiobook, so that those images/pdfs/epubs can be organized alongside the book within ABS. E.g. maps, artwork, photos, or supplementary pdfs.

You can already put supplemental material (specifically ebooks) in subfolders and have them show up as supplemental for reference while listening to an audiobook.

Ok I see that this is already pretty much possible for eBooks/supplementary PDFs, but presumably not images.

  1. A distinction between the ebook of the audiobook (the full book which might support progress tracking like whispersync) and any additional pdfs/epubs containing reference materials for the audiobook. These two are not the same.

This has been implemented for several years which I think is where my confusion is coming from. https://www.audiobookshelf.org/guides/ebooks

Ok, I don't think I had fully understood this feature. I can see this is already possible. My only question is, is there a way to name the eBooks in the folder so that one is set as the primary eBook and the other as supplementary (e.g. rename it supplementary.pdf or something), or can the primary/supplementary book only be set after importing from within the web ui?

(I like to do as much as possible through filenames, folder structure and metadata so that if i ever need to rebuild my ABS server from scratch, for whatever reason, I don't have to manually redo everything again through the web UI.)

  1. The means to limit which local image files are used as audiobook covers art (which point 1 would enable).

So this is just allowing images to be added as supplemental and viewed like other supplemental files?

The majority of my audiobooks have embedded cover art within the files themselves. Currently if the metadata scanner finds another image file, such as a map or illustration, in the book folder, or its sub-folders, it uses it as the audiobook cover art and there seems to be no way to prevent this. At it's most simple, I am looking for the ability to create an 'Artwork' sub-folder within the book folder that (a) means that the images within it are ignored as the audiobook cover art, and (b) these images are displayed alongside the book in ABS as a gallery of thumbnail artwork that you can tap on to enlarge.

I was proposing that there be different folders for different types of image, since it's nice if the map that you refer to frequently while reading a fantasy book is not mixed in with the other artwork - that's why i suggested having a "Maps" folder that is separate. Perhaps allowing two artwork sub-folders - such as 'images-primary' and 'images-supplementary' - would be a clean solution giving you a way to keep the most important reference images separate from the rest. Images in the primary folder appear more prominently.

I hope I have explained this clearly.

@saltedlolly commented on GitHub (Dec 7, 2025): > > 1. An agreed upon folder structure for organizing supplementary materials associated with an audiobook, so that those images/pdfs/epubs can be organized alongside the book within ABS. E.g. maps, artwork, photos, or supplementary pdfs. > > You can already put supplemental material (specifically ebooks) in subfolders and have them show up as supplemental for reference while listening to an audiobook. Ok I see that this is already pretty much possible for eBooks/supplementary PDFs, but presumably not images. > > > 2. A distinction between the ebook of the audiobook (the full book which might support progress tracking like whispersync) and any additional pdfs/epubs containing reference materials for the audiobook. These two are not the same. > > This has been implemented for several years which I think is where my confusion is coming from. https://www.audiobookshelf.org/guides/ebooks Ok, I don't think I had fully understood this feature. I can see this is already possible. My only question is, is there a way to name the eBooks in the folder so that one is set as the primary eBook and the other as supplementary (e.g. rename it supplementary.pdf or something), or can the primary/supplementary book only be set after importing from within the web ui? (I like to do as much as possible through filenames, folder structure and metadata so that if i ever need to rebuild my ABS server from scratch, for whatever reason, I don't have to manually redo everything again through the web UI.) > > > 3. The means to limit which local image files are used as audiobook covers art (which point 1 would enable). > > So this is just allowing images to be added as supplemental and viewed like other supplemental files? The majority of my audiobooks have embedded cover art within the files themselves. Currently if the metadata scanner finds another image file, such as a map or illustration, in the book folder, or its sub-folders, it uses it as the audiobook cover art and there seems to be no way to prevent this. At it's most simple, I am looking for the ability to create an 'Artwork' sub-folder within the book folder that (a) means that the images within it are ignored as the audiobook cover art, and (b) these images are displayed alongside the book in ABS as a gallery of thumbnail artwork that you can tap on to enlarge. I was proposing that there be different folders for different types of image, since it's nice if the map that you refer to frequently while reading a fantasy book is not mixed in with the other artwork - that's why i suggested having a "Maps" folder that is separate. Perhaps allowing two artwork sub-folders - such as 'images-primary' and 'images-supplementary' - would be a clean solution giving you a way to keep the most important reference images separate from the rest. Images in the primary folder appear more prominently. I hope I have explained this clearly.
adam commented 2026-04-25 00:13:54 +02:00
Author
Owner
Copy Link
Copy Source

@saltedlolly commented on GitHub (Dec 7, 2025):

Basically I'm looking for a way to be able to view a gallery of images alongside the book. These could be maps, recommended reading order charts, family trees, illustrations/photos from the book, paperback cover images, concept art etc. that you may want to refer while listening to the book.

And, most importantly, ensure that none of these images get accidentally used as the cover art for the audiobook. By having a dedicated folder for these images, it would make it easy for the scanner to know to ignore them when searching for an image to use as the audiobook cover art. (i.e. if the main book folder is empty of images, it would then revert to the embedded art, ignoring all the images in the 'images-primary' and 'images-supplementary' sub-folders).

@saltedlolly commented on GitHub (Dec 7, 2025): Basically I'm looking for a way to be able to view a gallery of images alongside the book. These could be maps, recommended reading order charts, family trees, illustrations/photos from the book, paperback cover images, concept art etc. that you may want to refer while listening to the book. And, most importantly, ensure that none of these images get accidentally used as the cover art for the audiobook. By having a dedicated folder for these images, it would make it easy for the scanner to know to ignore them when searching for an image to use as the audiobook cover art. (i.e. if the main book folder is empty of images, it would then revert to the embedded art, ignoring all the images in the 'images-primary' and 'images-supplementary' sub-folders).
adam commented 2026-04-25 00:13:54 +02:00
Author
Owner
Copy Link
Copy Source

@ZLoth commented on GitHub (Dec 8, 2025):

Please review and upvote https://github.com/advplyr/audiobookshelf/issues/4040

@ZLoth commented on GitHub (Dec 8, 2025): Please review and upvote https://github.com/advplyr/audiobookshelf/issues/4040
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 Label enhancement waiting
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#3140
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?