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]: Report potential directory structure issues #2639

New Issue
Open
opened 2026-04-25 00:09:11 +02:00 by adam · 1 comment
adam commented 2026-04-25 00:09:11 +02:00
Owner
Copy Link
Copy Source

Originally created by @nichwall on GitHub (Mar 8, 2025).

Type of Enhancement

Server Backend

Describe the Feature/Enhancement

Add a library tool which scans the library items for potential directory structure issues. I think this will need to scan the ABS database instead of the file system itself to make sure that books which were temporarily in the wrong place and correctly detected.

This feature would be run on demand by an admin and does not need to be scheduled, similar to getting the ffprobe dump of a file.

I envision the check would take the following general steps:

  • Get all books in the library
  • See if any media file paths and names (audiobook or ebook) are present on more than one book. If so, report the book which also has other media files (indicating that this book includes other books)
  • Check if media files exist at different directory depths. So, if there is a media file in an Author or Series folder as well as other books correctly in subfolders, those books would be reported. If the same "depth" exists, then these media files are likely separated into disc folders and are not a problem.

I do not think this needs to show up as "Issues" because the report doesn't really make sense in that interface. I also do not think there should be a way to "ignore" specific problem books, because those books should be reorganized anyway to reduce the chance of scanner mishaps in the future.

This could also be handled by a plugin or external script.

This is separate and distinct from reorganizing files with ABS or recognizing duplicate books.

  • ABS would not be able to correctly organize files if the library items are all messed up anyway, and this only makes issues more apparent to users without needing them to go digging in the database.
  • This is searching for duplicate entries in ABS for the same media file.

Why would this be helpful?

A relatively common issue that is brought up in Discord is why the server is not recognizing all media files in a library. This is almost always because users do not realize that every library item must be in its own directory (unless the media files are in the root of the directory), and have leftover media files in a parent directory (such as the Author or Series folder if those folders are used).

An example problem structure is shown below, where mediaFile.mp3 causes Books 1 and 2 to be grouped under that book.

Library/
  FolderA/
    mediaFile.mp3   <-- BAD
    myEbook.epub    <-- BAD
    Book1/
      Book1 files
    Book2/
      Book2 files
  rootFile.mp3

This can also happen if a user is moving files around with the Watcher enabled, where they temporarily place a media file in a parent folder, then move the book to the correct spot so their folder structure still looks correct.

Future Implementation (Screenshot)

I envision something similar to the ffprobe output. There could be a description about how this could take several seconds to minutes to complete for large libraries. A progress bar could show how many library items are remaining to scan from the database.

Scan button

The report could be something like:
"Library item [title] includes the same files as other library items."
"Library item [title] has multiple levels of media files."

Report display

Audiobookshelf Server Version

v2.19.5

Current Implementation (Screenshot)

N/A

Originally created by @nichwall on GitHub (Mar 8, 2025). ### Type of Enhancement Server Backend ### Describe the Feature/Enhancement Add a library tool which scans the library items for potential directory structure issues. I think this will need to scan the ABS database instead of the file system itself to make sure that books which were temporarily in the wrong place and correctly detected. This feature would be run on demand by an admin and does not need to be scheduled, similar to getting the ffprobe dump of a file. I envision the check would take the following general steps: - Get all books in the library - See if any media file paths and names (audiobook or ebook) are present on more than one book. If so, report the book which *also* has other media files (indicating that this book includes other books) - Check if media files exist at different directory depths. So, if there is a media file in an Author or Series folder as well as other books correctly in subfolders, those books would be reported. If the same "depth" exists, then these media files are likely separated into disc folders and are not a problem. I do not think this needs to show up as "Issues" because the report doesn't really make sense in that interface. I also do not think there should be a way to "ignore" specific problem books, because those books should be reorganized anyway to reduce the chance of scanner mishaps in the future. This could also be handled by a plugin or external script. This is separate and distinct from reorganizing files with ABS or recognizing duplicate books. - ABS would not be able to correctly organize files if the library items are all messed up anyway, and this only makes issues more apparent to users without needing them to go digging in the database. - This is searching for duplicate entries in ABS for the same media file. ### Why would this be helpful? A relatively common issue that is brought up in Discord is why the server is not recognizing all media files in a library. This is almost always because users do not realize that every library item must be in its own directory (unless the media files are in the root of the directory), and have leftover media files in a parent directory (such as the Author or Series folder if those folders are used). An example problem structure is shown below, where `mediaFile.mp3` causes Books 1 and 2 to be grouped under that book. ``` Library/ FolderA/ mediaFile.mp3 <-- BAD myEbook.epub <-- BAD Book1/ Book1 files Book2/ Book2 files rootFile.mp3 ``` This can also happen if a user is moving files around with the Watcher enabled, where they temporarily place a media file in a parent folder, then move the book to the correct spot so their folder structure still looks correct. ### Future Implementation (Screenshot) I envision something similar to the ffprobe output. There could be a description about how this could take several seconds to minutes to complete for large libraries. A progress bar could show how many library items are remaining to scan from the database. ![Scan button](https://github.com/user-attachments/assets/335701e5-5a13-434a-8c70-7c6d763c3943) The report could be something like: "Library item [title] includes the same files as other library items." "Library item [title] has multiple levels of media files." ![Report display](https://github.com/user-attachments/assets/7e4d569d-519b-4269-9529-1f4077c0ab16) ### Audiobookshelf Server Version v2.19.5 ### Current Implementation (Screenshot) N/A
adam added the enhancement label 2026-04-25 00:09:11 +02:00
adam commented 2026-04-25 00:09:11 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (Mar 8, 2025):

To clarify, the progress bar is optional, but may be nice so the user knows something is happening. It does complicate the tool.

@nichwall commented on GitHub (Mar 8, 2025): To clarify, the progress bar is optional, but may be nice so the user knows something is happening. It does complicate the tool.
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
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#2639
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?