feat: Implement Mp3tag Audible API standard metadata tags #4959
+72
−12
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add AUDIBLE_ASIN tag to FFmpeg metadata object - Use -movflags use_metadata_tags to preserve custom tags in mp4/m4b - Fix .m4b extension detection for mp4 format handling - Remove redundant -map_metadata 0 option - Update tests to match new FFmpeg options The mp4 muxer in FFmpeg only writes standard iTunes tags by default. Custom tags like AUDIBLE_ASIN are silently dropped unless use_metadata_tags is specified. Tested and verified with ffprobe and mediainfo on clean m4b files.
H2OKing89
pushed a commit
to H2OKing89/audiobookshelf
that referenced
this pull request
Jan 3, 2026
|
Would it be possible to make the embedded tags comply with the standard audiobook layout set out by https://community.mp3tag.de/t/ws-audible-via-api/64347 Which is an evolution of https://github.com/seanap/Plex-Audiobook-Guide which layout which information should be put in which Tag all software has an easy time understanding and parsing the metadata |
added 2 commits
January 4, 2026 09:43
Enriches audiobook metadata by adding support for additional fields including abridged/unabridged format, full publication date, ISBN, language, explicit content flags, and subtitle. Improves compatibility with Libation by including both lowercase and uppercase ASIN variants. Sets appropriate iTunes advisory flags to distinguish explicit from clean content.
Author
@binyaminyblatt Great suggestion! I've updated the PR to fully comply with both the Mp3tag Audible API standard and the Plex Audiobook Guide. Added Tags (Tier 1 - Basic Metadata):
Added Tags (Tier 2 - Series Support):
Example Output:The implementation now matches the standards you referenced, ensuring compatibility with Mp3tag, Plex, Booksonic, Libation, and other audiobook management tools. All tags are only written when the corresponding data exists in AudiobookShelf. Thanks for pointing me to these standards! MediaInfo (click to expand) |
|
Full disclosure I probably should've said this earlier, but I'm one of the maintainers of that standard and the only time we add anything to it is if we find something in the Audible API that should be saved so this is probably one of the last iterations of it for instance, the last major update to the standard was v0.6.0 which included, saving the ISBN and copyright information also I have put in a lot of effort in making sure we never break compatibility with anything in the past so this should be a really good standard to base things off of for mapping import tags as well |
H2OKing89
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Brief summary
Embeds comprehensive audiobook metadata tags in m4b/mp4 files following the Mp3tag Audible API standard and Plex Audiobook Guide, ensuring compatibility with ABS, Mp3tag, Plex, Booksonic, and other audiobook management tools.
Which issue is fixed?
Not a specific issue. This change was implemented based on a community request by @binyaminyblatt to comply with standardized audiobook metadata layouts for better cross-application compatibility.
Original request: Comment #3708018840
In-depth Description
What changed
server/utils/ffmpegHelpers.js• Basic metadata:
asin,AUDIBLE_ASIN,ISBN,subtitle,LANGUAGE,RELEASETIME,EXPLICIT,ITUNESADVISORY,FORMAT• Series support:
SERIES,SERIES-PART,PART,MOVEMENTNAME,MOVEMENT,SHOWMOVEMENT,ALBUMSORT• Added
-movflags use_metadata_tagsto preserve custom tags in m4b/mp4• Fixed
.m4bextension detection• Removed redundant
-map_metadata 0to prevent duplicate tagstest/server/utils/ffmpegHelpers.test.jsTags added
Tier 1 - Basic Metadata
asin+AUDIBLE_ASIN- Amazon Standard Identification Number (dual format for compatibility)ISBN- International Standard Book Numbersubtitle- Subtitle field for M4B/MP4 (in addition toTIT3for MP3)LANGUAGE- Language tagRELEASETIME- Full release date (YYYY-MM-DD format)EXPLICIT/ITUNESADVISORY- Content advisory (1=explicit, 2=clean)FORMAT- Abridged/unabridged indicatorTier 2 - Series Support
SERIES- Series nameSERIES-PART/PART- Book number in series (both for compatibility)MOVEMENTNAME/MOVEMENT/SHOWMOVEMENT- M4B-specific series tagsALBUMSORT- Computed sorting key for proper series ordering (e.g., "Series Name 003 - Title")How it works
Why this solution?
Why
-movflags use_metadata_tags?The mp4 muxer in FFmpeg only writes standard iTunes-style tags by default. Custom tags like
AUDIBLE_ASIN,SERIES,ISBN, etc. are silently dropped unlessuse_metadata_tagsis specified.Why these specific tag names?
Follows the Mp3tag Audible API standard v0.6.0+ and Plex Audiobook Guide, ensuring compatibility with the established audiobook management software ecosystem.
Why removed
-map_metadata 0?The original approach mapped metadata from the metadata file first (
-map_metadata 1), then added metadata from the input file (-map_metadata 0). This caused duplicate tags when re-embedding metadata. Since the metadata file now contains all desired metadata, only one mapping is needed.Does it solve a problem that affects multiple users?
Yes - users who manage audiobooks with tools like Libation, Mp3tag, Plex, and Booksonic expect standardized metadata tags to be embedded. This enables seamless interoperability between Audiobookshelf and other audiobook management tools in the ecosystem.
How have you tested this?
Test Results:
ffprobetag verificationmediainfotag verificationALBUMSORTcomputed correctlyReproducible test steps:
ffmpeg -map_metadata -1 -map_chapters -1ffprobeandmediainfoALBUMSORTformattingSample verification output:
MediaInfo (click to expand)
Screenshots
Metadata verification screenshots (click to expand)
Acknowledgments
Thanks to @binyaminyblatt for the suggestion and for maintaining the Mp3tag Audible API standard, ensuring compatibility across the audiobook management ecosystem.