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]: Allow setting metadata on upload via API #2487

New Issue
Closed
opened 2026-04-25 00:07:39 +02:00 by adam · 5 comments
adam commented 2026-04-25 00:07:39 +02:00
Owner
Copy Link
Copy Source

Originally created by @mstaffa on GitHub (Jan 13, 2025).

Type of Enhancement

Web Interface/Frontend

Describe the Feature/Enhancement

This issue is mainly because I can't find a good way to add the ASIN or ISBN ID3 tags to an m4b file for the . If you can advise on an effective way to do that in python (or even just a CLI program) I will -- with immense gratitude -- close my feature request.

I am uploading items via the API as documented here. I would primarily like to be able to provide the ASIN as part of the upload request so matching is done correctly, but as a stretch other metadata could be accepted.

In the documentation it notes that the form keys are ignored. I think it would be helpful if they weren't, or there was some way to enable them.

Why would this be helpful?

I am writing a program to synchronise books from multiple Audible accounts (in different regions) to Audiobookshelf. Setting the ASIN at upload - alongside the Auto Fetch Metadata setting - would make this a much simpler process.

Future Implementation (Screenshot)

Currently the upload request looks something like this:

    def upload(self, book):
        '''
        Upload a single book file to audiobookshelf.
        '''

        folder_id = self.get_folder().get("id")

        data = {
            'asin' : book.asin,
            'isbn' : book.isbn,
            'title': book.title,
            'author': book.author,
            'provider': "audible",
            'library': self.id,
            'folder': folder_id
        }

        with open(book.m4b_filepath, "rb") as book_file:
            req = httpx.post(self.url + '/api/upload', headers=self.headers, data=data, files={'0': (book.m4b_filepath, book_file)}, timeout=self.timeout)

        if req.status_code != 200:
            raise(RuntimeError(req.status_code, req.content))

As stated in the documentation, all of these fields are ignored. I would like them to be used if provided, and for an additional boolean option "autoFetchMetadata": true/false similarly to how the upload webpage works.

Audiobookshelf Server Version

v2.17.2

Current Implementation (Screenshot)

The documentation for uploading files via the API. It provides no options for metadata except embedded.

Originally created by @mstaffa on GitHub (Jan 13, 2025). ### Type of Enhancement Web Interface/Frontend ### Describe the Feature/Enhancement This issue is mainly because I can't find a good way to add the `ASIN` or `ISBN` ID3 tags to an m4b file for the . If you can advise on an effective way to do that in python (or even just a CLI program) I will -- with immense gratitude -- close my feature request. --- I am uploading items via the API as documented [here](https://api.audiobookshelf.org/#upload-files). I would primarily like to be able to provide the ASIN as part of the upload request so matching is done correctly, but as a stretch other metadata could be accepted. In the documentation it notes that the form keys are ignored. I think it would be helpful if they weren't, or there was some way to enable them. ### Why would this be helpful? I am writing a program to synchronise books from multiple Audible accounts (in different regions) to Audiobookshelf. Setting the ASIN at upload - alongside the `Auto Fetch Metadata` setting - would make this a much simpler process. ### Future Implementation (Screenshot) Currently the upload request looks something like this: ```python def upload(self, book): ''' Upload a single book file to audiobookshelf. ''' folder_id = self.get_folder().get("id") data = { 'asin' : book.asin, 'isbn' : book.isbn, 'title': book.title, 'author': book.author, 'provider': "audible", 'library': self.id, 'folder': folder_id } with open(book.m4b_filepath, "rb") as book_file: req = httpx.post(self.url + '/api/upload', headers=self.headers, data=data, files={'0': (book.m4b_filepath, book_file)}, timeout=self.timeout) if req.status_code != 200: raise(RuntimeError(req.status_code, req.content)) ``` As stated in the documentation, all of these fields are ignored. I would like them to be used if provided, and for an additional boolean option `"autoFetchMetadata": true/false` similarly to how the upload webpage works. ### Audiobookshelf Server Version v2.17.2 ### Current Implementation (Screenshot) The documentation for [uploading files via the API](https://api.audiobookshelf.org/#upload-files). It provides no options for metadata except embedded.
adam added the enhancement label 2026-04-25 00:07:39 +02:00
adam closed this issue 2026-04-25 00:07:39 +02:00
adam commented 2026-04-25 00:07:40 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (Jan 13, 2025):

To clarify, "Auto fetch metadata" on the upload page in the web client only fetches metadata to help auto populate the folder fields, and this metadata is not used to set any metadata for the library item after you finish uploading. Metadata for the item is still set based on the library metadata priority from the file system, so as long as you have your metadata set up in the file you are uploading, there should not be a need to include metadata with the upload.

You can include the ASIN in folder name in brackets when uploading, which ABS will parse. For example, 3 - My Book [ASIN]/

Is there a reason you are not just uploading directly to the file system and then letting ABS scan the file?

@nichwall commented on GitHub (Jan 13, 2025): To clarify, "Auto fetch metadata" on the upload page in the web client *only* fetches metadata to help auto populate the folder fields, and this metadata is not used to set any metadata for the library item after you finish uploading. Metadata for the item is still set based on the library metadata priority from the file system, so as long as you have your metadata set up in the file you are uploading, there should not be a need to include metadata with the upload. You can include the ASIN in folder name in brackets when uploading, which ABS will parse. For example, `3 - My Book [ASIN]/` Is there a reason you are not just uploading directly to the file system and then letting ABS scan the file?
adam commented 2026-04-25 00:07:40 +02:00
Author
Owner
Copy Link
Copy Source

@mstaffa commented on GitHub (Jan 13, 2025):

@nichwall You make many excellent points. As of about 45 minutes ago I'm looking at exactly what you suggest - managing files directly on the filesystem and letting Audiobookshelf scan them.

I'll close the enhancement if I get that to succeed, or alternatively if I use the 3 - My Book [ASIN]/ suggestion.

Thank you!

@mstaffa commented on GitHub (Jan 13, 2025): @nichwall You make many excellent points. As of about 45 minutes ago I'm looking at exactly what you suggest - managing files directly on the filesystem and letting Audiobookshelf scan them. I'll close the enhancement if I get that to succeed, or alternatively if I use the `3 - My Book [ASIN]/` suggestion. Thank you!
adam commented 2026-04-25 00:07:40 +02:00
Author
Owner
Copy Link
Copy Source

@nichwall commented on GitHub (Jan 13, 2025):

For others reading this, another option would be to manually create a metadata.json in your upload function and populate the fields you want included, such as ASIN. Then you can just upload the media files with this simple JSON file, so ABS will pull fields from there as part of the normal metadata scan.

There are definitely improvements needed for the upload page and endpoints, but they aren't as high of a priority because in almost all cases it is just simpler to upload directly to the file system (gets around upload limits, generally faster because you're not going through the ABS server, more control on what goes where, etc)

@nichwall commented on GitHub (Jan 13, 2025): For others reading this, another option would be to manually create a `metadata.json` in your upload function and populate the fields you want included, such as ASIN. Then you can just upload the media files with this simple JSON file, so ABS will pull fields from there as part of the normal metadata scan. There are definitely improvements needed for the upload page and endpoints, but they aren't as high of a priority because in almost all cases it is just simpler to upload directly to the file system (gets around upload limits, generally faster because you're not going through the ABS server, more control on what goes where, etc)
adam commented 2026-04-25 00:07:40 +02:00
Author
Owner
Copy Link
Copy Source

@mstaffa commented on GitHub (Jan 13, 2025):

@nichwall Thanks for the input. I've tried the tagged file directly on the filesystem as you suggested but the scanner still isn't picking up the asin metadata tag. Am I tagging this wrong? I'm using the mutagen library to add/verify them.

  # Embed ASIN and ISBN ID3 tags into file metadata
  mutagen_file = mutagen.File(book.mp4_filepath)
  mutagen_file.tags["asin"] = book.asin
  mutagen_file.tags["isbn"] = book.isbn

  mutagen_file.tags.save(book.mp4_filepath)

Otherwise I'll work on code that will create/manage the directory structure properly.

@mstaffa commented on GitHub (Jan 13, 2025): @nichwall Thanks for the input. I've tried the tagged file directly on the filesystem as you suggested but the scanner still isn't picking up the `asin` metadata tag. Am I tagging this wrong? I'm using the mutagen library to add/verify them. ```python # Embed ASIN and ISBN ID3 tags into file metadata mutagen_file = mutagen.File(book.mp4_filepath) mutagen_file.tags["asin"] = book.asin mutagen_file.tags["isbn"] = book.isbn mutagen_file.tags.save(book.mp4_filepath) ``` Otherwise I'll work on code that will create/manage the directory structure properly.
adam commented 2026-04-25 00:07:41 +02:00
Author
Owner
Copy Link
Copy Source

@mstaffa commented on GitHub (Jan 14, 2025):

@nichwall Thank you again for the input. I've rewritten the code to manage the filesystem rather than try and bend the API upload to my will. The metadata.json file inside the book directly did exactly as you described and I wanted.

Cheers 👍 😁

@mstaffa commented on GitHub (Jan 14, 2025): @nichwall Thank you again for the input. I've rewritten the code to manage the filesystem rather than try and bend the API upload to my will. The `metadata.json` file inside the book directly did exactly as you described and I wanted. Cheers :+1: :grin:
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#2487
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?