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

[PR #4959] feat: Implement Mp3tag Audible API standard metadata tags #4385

New Issue
Open
opened 2026-04-25 00:19:32 +02:00 by adam · 0 comments
adam commented 2026-04-25 00:19:32 +02:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/advplyr/audiobookshelf/pull/4959
Author: @H2OKing89
Created: 1/3/2026
Status: 🔄 Open

Base: master ← Head: feat/embed-audible-asin

📝 Commits (3)

  • 9e7d4ab feat: Embed AUDIBLE_ASIN metadata in m4b files
  • e7a980d Adds extended metadata fields to FFmpeg output
  • cbd63de Add series metadata tags to FFmpeg encoding

📊 Changes

2 files changed (+72 additions, -12 deletions)

View changed files

📝 server/utils/ffmpegHelpers.js (+67 -7)
📝 test/server/utils/ffmpegHelpers.test.js (+5 -5)

📄 Description

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

"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"

In-depth Description

What changed

File Change
server/utils/ffmpegHelpers.js Added comprehensive metadata tags complying with Mp3tag/Plex standards:
• 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_tags to preserve custom tags in m4b/mp4
• Fixed .m4b extension detection
• Removed redundant -map_metadata 0 to prevent duplicate tags
test/server/utils/ffmpegHelpers.test.js Updated test expectations to match new FFmpeg options

Tags added

Tier 1 - Basic Metadata

  • asin + AUDIBLE_ASIN - Amazon Standard Identification Number (dual format for compatibility)
  • ISBN - International Standard Book Number
  • subtitle - Subtitle field for M4B/MP4 (in addition to TIT3 for MP3)
  • LANGUAGE - Language tag
  • RELEASETIME - Full release date (YYYY-MM-DD format)
  • EXPLICIT / ITUNESADVISORY - Content advisory (1=explicit, 2=clean)
  • FORMAT - Abridged/unabridged indicator

Tier 2 - Series Support

  • SERIES - Series name
  • SERIES-PART / PART - Book number in series (both for compatibility)
  • MOVEMENTNAME / MOVEMENT / SHOWMOVEMENT - M4B-specific series tags
  • ALBUMSORT - Computed sorting key for proper series ordering (e.g., "Series Name 003 - Title")

How it works

┌─────────────────────────────────────────────────────────────────────┐
│  FFmpeg Metadata Flow (m4b embedding)                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  LibraryItem.media ──► getFFMetadataObject() ──► ffmetadata file    │
│      ├─ asin                       │                                │
│      ├─ isbn                       ▼                                │
│      ├─ series          AUDIBLE_ASIN=1039400205                     │
│      ├─ language        ISBN=9781039400207                          │
│      └─ ...             SERIES=He Who Fights with Monsters          │
│                         PART=3                                      │
│                         ALBUMSORT=He Who Fights... 003 - Title      │
│                                    │                                │
│                                    ▼                                │
│                         addCoverAndMetadataToFile()                 │
│                                    │                                │
│                      ┌─────────────┴─────────────┐                  │
│                      ▼                           ▼                  │
│               mp3 (ID3v2)                  m4b/mp4                  │
│                                                  │                  │
│                                    ┌─────────────┴─────────────┐    │
│                                    ▼                           ▼    │
│                              -f mp4              -movflags          │
│                                               use_metadata_tags     │
│                                                      │              │
│                                                      ▼              │
│                                            Custom tags preserved    │
│                                      (AUDIBLE_ASIN, SERIES, etc.)   │
└─────────────────────────────────────────────────────────────────────┘

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 unless use_metadata_tags is 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:

Test Result
Unit tests (315 total) ✅ All passing
Manual embed via ABS UI ✅ Verified
ffprobe tag verification ✅ All new tags present
mediainfo tag verification ✅ All new tags present
Stripped file re-embed ✅ Tags correctly written to clean file
Series ordering validation ✅ ALBUMSORT computed correctly

Reproducible test steps:

  1. Started with m4b file containing existing metadata
  2. Stripped all metadata using ffmpeg -map_metadata -1 -map_chapters -1
  3. Verified clean file had no custom tags
  4. Ran ABS embed metadata feature
  5. Verified all new tags present via ffprobe and mediainfo
  6. Validated series tags and ALBUMSORT formatting

Sample verification output:

$ ffprobe -show_entries format_tags -i audiobook.m4b
[FORMAT]
TAG:title=He Who Fights with Monsters 3
TAG:artist=Shirtaloon, Travis Deverell
TAG:AUDIBLE_ASIN=1039400205
TAG:asin=1039400205
TAG:ISBN=9781039400207
TAG:LANGUAGE=English
TAG:SERIES=He Who Fights with Monsters
TAG:PART=3
TAG:ALBUMSORT=He Who Fights with Monsters 003 - He Who Fights with Monsters 3
TAG:FORMAT=unabridged
TAG:ITUNESADVISORY=2
...
[/FORMAT]
MediaInfo (click to expand) 
General
Complete name                            : /home/H2OKing/abs-dev/He Who Fights with Monsters vol_03 (2021) (Shirtaloon) {ASIN.1039400205}/He Who Fights with Monsters vol_03 (2021) (Shirtaloon) {ASIN.1039400205}.nometa.m4b
Format                                   : MPEG-4
Format profile                           : Base Media
Codec ID                                 : isom (isom/iso2/mp41)
File size                                : 1.31 GiB
Duration                                 : 24 h 39 min
Overall bit rate mode                    : Constant
Overall bit rate                         : 127 kb/s
ISBN                                     : 9781039400207
title                                    : He Who Fights with Monsters 3
artist                                   : Shirtaloon, Travis Deverell
album_artist                             : Shirtaloon, Travis Deverell
album                                    : He Who Fights with Monsters 3: A LitRPG Adventure (He Who Fights with Monsters, Book 3)
TIT3                                     : A LitRPG Adventure (He Who Fights with Monsters, Book 3)
subtitle                                 : A LitRPG Adventure (He Who Fights with Monsters, Book 3)
genre                                    : Science Fiction & Fantasy
date                                     : 2021
comment                                  : <p><b>For all that Jason knows, life is amazing. But he's about to learn that all his new power, wealth, and influence comes at a price.</b></p> <p>Riding high on success, he and his team are looking to the future, preparing themselves for the challenges to come. Nothing, however, could have prepared him for the lessons his enemies have to teach. When magic is involved, the stakes can be even greater than life and death. </p> <p>While Jason’s personal enemies make plans, the greater foes plaguing his new home have been pushed to the brink. With one powerful card left to play, they are on a collision course with Jason and his team. With no one to help and more than their lives on the line, Jason and his companions must fight with more monsters than ever in the race to grow stronger. With an invincible enemy already anticipating them, they will learn that sometimes winning the battle is more important than surviving it. </p>
description                              : <p><b>For all that Jason knows, life is amazing. But he's about to learn that all his new power, wealth, and influence comes at a price.</b></p> <p>Riding high on success, he and his team are looking to the future, preparing themselves for the challenges to come. Nothing, however, could have prepared him for the lessons his enemies have to teach. When magic is involved, the stakes can be even greater than life and death. </p> <p>While Jason’s personal enemies make plans, the greater foes plaguing his new home have been pushed to the brink. With one powerful card left to play, they are on a collision course with Jason and his team. With no one to help and more than their lives on the line, Jason and his companions must fight with more monsters than ever in the race to grow stronger. With an invincible enemy already anticipating them, they will learn that sometimes winning the battle is more important than surviving it. </p>
composer                                 : Heath Miller
copyright                                : Podium Audio
publisher                                : Podium Audio
TRACKTOTAL                               : 1
grouping                                 : He Who Fights with Monsters #3
asin                                     : 1039400205
AUDIBLE_ASIN                             : 1039400205
LANGUAGE                                 : English
ITUNESADVISORY                           : 2
FORMAT                                   : unabridged
SERIES                                   : He Who Fights with Monsters
SERIES-PART                              : 3
PART                                     : 3
MOVEMENTNAME                             : He Who Fights with Monsters
MOVEMENT                                 : 3
SHOWMOVEMENT                             : 1
ALBUMSORT                                : He Who Fights with Monsters 003 - He Who Fights with Monsters 3
track                                    : 1
encoder                                  : Lavf59.27.100

Audio
ID                                       : 1
Format                                   : AAC LC
Format/Info                              : Advanced Audio Codec Low Complexity
Codec ID                                 : mp4a-40-2
Duration                                 : 24 h 39 min
Bit rate mode                            : Constant
Bit rate                                 : 126 kb/s
Channel(s)                               : 2 channels
Channel layout                           : L R
Sampling rate                            : 44.1 kHz
Frame rate                               : 43.066 FPS (1024 SPF)
Compression mode                         : Lossy
Stream size                              : 1.30 GiB (99%)
Default                                  : Yes
Alternate group                          : 1
Menus                                    : 3

Menu #1
ID                                       : 3
Format                                   : Timed Text
Codec ID                                 : text
Duration                                 : 24 h 39 min
Language                                 : English
 For                                     : 1
00:00:00.000                             : Intro
00:00:18.227                             : 1. A Question You Don’t Yet Know to Ask
00:25:26.177                             : 2. Looking Forward
00:44:12.717                             : 3. Adventurers Are People Too
00:59:31.670                             : 4. Valkyrie
01:17:05.902                             : 5. Departures
01:36:20.166                             : 6. No Pot of Gold
01:49:47.710                             : 7. The Glory of Success or the Price of Failure
02:12:24.150                             : 8. Adequate
02:30:04.582                             : 9. Trash Bonanza
02:45:30.826                             : 10. Strangeness
02:57:16.480                             : 11. Full Circle
03:23:18.324                             : 12. Regretting it Later
03:42:22.905                             : 13. Swat
03:58:15.620                             : 14. The Purpose of the Adventure Society
04:16:04.969                             : 15. Elven Storage Solutions
04:30:21.181                             : 16. Disbanded
04:48:30.383                             : 17. The Man Behind the Mouth
05:05:35.196                             : 18. Search
05:26:22.177                             : 19. Defiance
05:57:41.461                             : 20. Hanging Around
06:14:31.738                             : 21. What Doesn’t Kill You
06:37:39.269                             : 22. Lingering Doubts
06:51:53.856                             : 23. Scars
07:06:00.920                             : 24. I Won’t Let Them Turn Me Into That
07:22:47.134                             : 25. Putting the Band Back Together
07:36:49.949                             : 26. Nothing Speaks Louder Than Power
07:53:58.778                             : 27. My Name is Jason Asano
08:13:32.802                             : 28. While They Watch Me Kill You
08:33:32.229                             : 29. Inherently Corrupting
08:54:45.890                             : 30. Beholden to No One
09:11:47.638                             : 31. Evil Detector
09:32:58.489                             : 32. The World Needs People Like You
09:53:41.430                             : 33. I’m Very Big on Cowardice
10:13:48.728                             : 34. More Powerful Than We Anticipated
10:29:40.329                             : 35. Fate Can’t Wait to Kill Us All
10:43:28.329                             : 36. Running Towards Something
10:59:34.349                             : 37. Greenhouse Flowers
11:17:57.691                             : 38. A Man Transformed
11:37:19.061                             : 39. The Worst Possible Option
11:55:39.919                             : 40. Brave Little Tailor
12:18:38.928                             : 41. Terms of the Pact
12:36:34.407                             : 42. Trading Safety Today For Death Tomorrow
12:55:13.191                             : 43. Stalwart
13:19:14.616                             : 44. I’m Sick of Fighting Magic Rocks
13:37:57.069                             : 45. Crossing the Threshold
13:55:47.160                             : 46. Anyone Can Be Useful
14:10:59.844                             : 47. A Series of Familiar Powers
14:28:32.219                             : 48. It’s Not About Killing Monsters
14:43:24.817                             : 49. Sin Eater
14:59:25.426                             : 50. The Most Dangerous Thing in the Dark
15:17:18.862                             : 51. The Boss Comes to Town
15:38:50.704                             : 52. It’s Very Complicated and You All Need to Go Away
15:55:32.691                             : 53. Strong Foundations
16:14:49.858                             : 54. A Valiant Death
16:30:09.275                             : 55. Ambitions
16:45:21.192                             : 56. Faith and Glory
17:02:50.363                             : 57. Thadwick
17:25:42.500                             : 58. The True Danger
17:47:05.193                             : 59. Forsaken Place
18:13:21.782                             : 60. Being What he Needs to Be
18:30:45.982                             : 61. A Significantly More Dangerous Entity
18:47:30.710                             : 62. Losing the Battle to Win the War
19:05:50.152                             : 63. War of Adaptation
19:24:34.485                             : 64. The Hero of This Story
19:45:00.406                             : 65. Good News, Bad News
20:04:59.206                             : 66. Here We Are
20:24:33.044                             : 67. Outmatched
20:49:43.897                             : 68. The Power of Friendship
21:14:37.312                             : 69. A War of Stolen Moments
21:38:22.204                             : Epilogue Chapter 1
21:55:11.669                             : Epilogue Chapter 2
22:22:37.197                             : Epilogue Chapter 3
22:49:28.941                             : Epilogue Chapter 4
23:07:28.181                             : Epilogue Chapter 5
23:27:23.776                             : Epilogue Chapter 6
23:51:17.446                             : Epilogue Chapter 7
24:08:30.200                             : Epilogue Chapter 8
24:38:25.637                             : Outro

Menu #2
00:00:00.000                             : Intro
00:00:18.227                             : 1. A Question You Don’t Yet Know to Ask
00:25:26.177                             : 2. Looking Forward
00:44:12.717                             : 3. Adventurers Are People Too
00:59:31.670                             : 4. Valkyrie
01:17:05.902                             : 5. Departures
01:36:20.166                             : 6. No Pot of Gold
01:49:47.710                             : 7. The Glory of Success or the Price of Failure
02:12:24.150                             : 8. Adequate
02:30:04.582                             : 9. Trash Bonanza
02:45:30.826                             : 10. Strangeness
02:57:16.480                             : 11. Full Circle
03:23:18.324                             : 12. Regretting it Later
03:42:22.905                             : 13. Swat
03:58:15.620                             : 14. The Purpose of the Adventure Society
04:16:04.969                             : 15. Elven Storage Solutions
04:30:21.181                             : 16. Disbanded
04:48:30.383                             : 17. The Man Behind the Mouth
05:05:35.196                             : 18. Search
05:26:22.177                             : 19. Defiance
05:57:41.461                             : 20. Hanging Around
06:14:31.738                             : 21. What Doesn’t Kill You
06:37:39.269                             : 22. Lingering Doubts
06:51:53.856                             : 23. Scars
07:06:00.920                             : 24. I Won’t Let Them Turn Me Into That
07:22:47.134                             : 25. Putting the Band Back Together
07:36:49.949                             : 26. Nothing Speaks Louder Than Power
07:53:58.778                             : 27. My Name is Jason Asano
08:13:32.802                             : 28. While They Watch Me Kill You
08:33:32.229                             : 29. Inherently Corrupting
08:54:45.890                             : 30. Beholden to No One
09:11:47.638                             : 31. Evil Detector
09:32:58.489                             : 32. The World Needs People Like You
09:53:41.430                             : 33. I’m Very Big on Cowardice
10:13:48.728                             : 34. More Powerful Than We Anticipated
10:29:40.329                             : 35. Fate Can’t Wait to Kill Us All
10:43:28.329                             : 36. Running Towards Something
10:59:34.349                             : 37. Greenhouse Flowers
11:17:57.691                             : 38. A Man Transformed
11:37:19.061                             : 39. The Worst Possible Option
11:55:39.919                             : 40. Brave Little Tailor
12:18:38.928                             : 41. Terms of the Pact
12:36:34.407                             : 42. Trading Safety Today For Death Tomorrow
12:55:13.191                             : 43. Stalwart
13:19:14.616                             : 44. I’m Sick of Fighting Magic Rocks
13:37:57.069                             : 45. Crossing the Threshold
13:55:47.160                             : 46. Anyone Can Be Useful
14:10:59.844                             : 47. A Series of Familiar Powers
14:28:32.219                             : 48. It’s Not About Killing Monsters
14:43:24.817                             : 49. Sin Eater
14:59:25.426                             : 50. The Most Dangerous Thing in the Dark
15:17:18.862                             : 51. The Boss Comes to Town
15:38:50.704                             : 52. It’s Very Complicated and You All Need to Go Away
15:55:32.691                             : 53. Strong Foundations
16:14:49.858                             : 54. A Valiant Death
16:30:09.275                             : 55. Ambitions
16:45:21.192                             : 56. Faith and Glory
17:02:50.363                             : 57. Thadwick
17:25:42.500                             : 58. The True Danger
17:47:05.193                             : 59. Forsaken Place
18:13:21.782                             : 60. Being What he Needs to Be
18:30:45.982                             : 61. A Significantly More Dangerous Entity
18:47:30.710                             : 62. Losing the Battle to Win the War
19:05:50.152                             : 63. War of Adaptation
19:24:34.485                             : 64. The Hero of This Story
19:45:00.406                             : 65. Good News, Bad News
20:04:59.206                             : 66. Here We Are
20:24:33.044                             : 67. Outmatched
20:49:43.897                             : 68. The Power of Friendship
21:14:37.312                             : 69. A War of Stolen Moments
21:38:22.204                             : Epilogue Chapter 1
21:55:11.669                             : Epilogue Chapter 2
22:22:37.197                             : Epilogue Chapter 3
22:49:28.941                             : Epilogue Chapter 4
23:07:28.181                             : Epilogue Chapter 5
23:27:23.776                             : Epilogue Chapter 6
23:51:17.446                             : Epilogue Chapter 7
24:08:30.200                             : Epilogue Chapter 8
24:38:25.637                             : Outro

Screenshots

Metadata verification screenshots (click to expand) image image image

Acknowledgments

Thanks to @binyaminyblatt for the suggestion and for maintaining the Mp3tag Audible API standard, ensuring compatibility across the audiobook management ecosystem.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/advplyr/audiobookshelf/pull/4959 **Author:** [@H2OKing89](https://github.com/H2OKing89) **Created:** 1/3/2026 **Status:** 🔄 Open **Base:** `master` ← **Head:** `feat/embed-audible-asin` --- ### 📝 Commits (3) - [`9e7d4ab`](https://github.com/advplyr/audiobookshelf/commit/9e7d4ab5e7f64b1fd6201a355f17e128c83d4142) feat: Embed AUDIBLE_ASIN metadata in m4b files - [`e7a980d`](https://github.com/advplyr/audiobookshelf/commit/e7a980d55ab157e1ed52345c1989a41c9bd815f9) Adds extended metadata fields to FFmpeg output - [`cbd63de`](https://github.com/advplyr/audiobookshelf/commit/cbd63de17d5be105b1be5934af7707fa0d174057) Add series metadata tags to FFmpeg encoding ### 📊 Changes **2 files changed** (+72 additions, -12 deletions) <details> <summary>View changed files</summary> 📝 `server/utils/ffmpegHelpers.js` (+67 -7) 📝 `test/server/utils/ffmpegHelpers.test.js` (+5 -5) </details> ### 📄 Description ## Brief summary Embeds comprehensive audiobook metadata tags in m4b/mp4 files following the [Mp3tag Audible API standard](https://community.mp3tag.de/t/ws-audible-via-api/64347) and [Plex Audiobook Guide](https://github.com/seanap/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](https://github.com/binyaminyblatt) to comply with standardized audiobook metadata layouts for better cross-application compatibility. **Original request:** [Comment #3708018840](https://github.com/advplyr/audiobookshelf/pull/4959#issuecomment-3708018840) > "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" ## In-depth Description ### What changed | File | Change | |------|--------| | `server/utils/ffmpegHelpers.js` | Added comprehensive metadata tags complying with Mp3tag/Plex standards:<br>• **Basic metadata**: `asin`, `AUDIBLE_ASIN`, `ISBN`, `subtitle`, `LANGUAGE`, `RELEASETIME`, `EXPLICIT`, `ITUNESADVISORY`, `FORMAT`<br>• **Series support**: `SERIES`, `SERIES-PART`, `PART`, `MOVEMENTNAME`, `MOVEMENT`, `SHOWMOVEMENT`, `ALBUMSORT`<br>• Added `-movflags use_metadata_tags` to preserve custom tags in m4b/mp4<br>• Fixed `.m4b` extension detection<br>• Removed redundant `-map_metadata 0` to prevent duplicate tags | | `test/server/utils/ffmpegHelpers.test.js` | Updated test expectations to match new FFmpeg options | ### Tags added #### Tier 1 - Basic Metadata - `asin` + `AUDIBLE_ASIN` - Amazon Standard Identification Number (dual format for compatibility) - `ISBN` - International Standard Book Number - `subtitle` - Subtitle field for M4B/MP4 (in addition to `TIT3` for MP3) - `LANGUAGE` - Language tag - `RELEASETIME` - Full release date (YYYY-MM-DD format) - `EXPLICIT` / `ITUNESADVISORY` - Content advisory (1=explicit, 2=clean) - `FORMAT` - Abridged/unabridged indicator #### Tier 2 - Series Support - `SERIES` - Series name - `SERIES-PART` / `PART` - Book number in series (both for compatibility) - `MOVEMENTNAME` / `MOVEMENT` / `SHOWMOVEMENT` - M4B-specific series tags - `ALBUMSORT` - Computed sorting key for proper series ordering (e.g., "Series Name 003 - Title") ### How it works ``` ┌─────────────────────────────────────────────────────────────────────┐ │ FFmpeg Metadata Flow (m4b embedding) │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ LibraryItem.media ──► getFFMetadataObject() ──► ffmetadata file │ │ ├─ asin │ │ │ ├─ isbn ▼ │ │ ├─ series AUDIBLE_ASIN=1039400205 │ │ ├─ language ISBN=9781039400207 │ │ └─ ... SERIES=He Who Fights with Monsters │ │ PART=3 │ │ ALBUMSORT=He Who Fights... 003 - Title │ │ │ │ │ ▼ │ │ addCoverAndMetadataToFile() │ │ │ │ │ ┌─────────────┴─────────────┐ │ │ ▼ ▼ │ │ mp3 (ID3v2) m4b/mp4 │ │ │ │ │ ┌─────────────┴─────────────┐ │ │ ▼ ▼ │ │ -f mp4 -movflags │ │ use_metadata_tags │ │ │ │ │ ▼ │ │ Custom tags preserved │ │ (AUDIBLE_ASIN, SERIES, etc.) │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 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 unless `use_metadata_tags` is specified. **Why these specific tag names?** Follows the [Mp3tag Audible API standard v0.6.0+](https://community.mp3tag.de/t/ws-audible-via-api/64347) and [Plex Audiobook Guide](https://github.com/seanap/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:** | Test | Result | |------|--------| | Unit tests (315 total) | ✅ All passing | | Manual embed via ABS UI | ✅ Verified | | `ffprobe` tag verification | ✅ All new tags present | | `mediainfo` tag verification | ✅ All new tags present | | Stripped file re-embed | ✅ Tags correctly written to clean file | | Series ordering validation | ✅ `ALBUMSORT` computed correctly | **Reproducible test steps:** 1. Started with m4b file containing existing metadata 2. Stripped all metadata using `ffmpeg -map_metadata -1 -map_chapters -1` 3. Verified clean file had no custom tags 4. Ran ABS embed metadata feature 5. Verified all new tags present via `ffprobe` and `mediainfo` 6. Validated series tags and `ALBUMSORT` formatting **Sample verification output:** ``` $ ffprobe -show_entries format_tags -i audiobook.m4b [FORMAT] TAG:title=He Who Fights with Monsters 3 TAG:artist=Shirtaloon, Travis Deverell TAG:AUDIBLE_ASIN=1039400205 TAG:asin=1039400205 TAG:ISBN=9781039400207 TAG:LANGUAGE=English TAG:SERIES=He Who Fights with Monsters TAG:PART=3 TAG:ALBUMSORT=He Who Fights with Monsters 003 - He Who Fights with Monsters 3 TAG:FORMAT=unabridged TAG:ITUNESADVISORY=2 ... [/FORMAT] ``` <details> <summary>MediaInfo (click to expand)</summary> ```text General Complete name : /home/H2OKing/abs-dev/He Who Fights with Monsters vol_03 (2021) (Shirtaloon) {ASIN.1039400205}/He Who Fights with Monsters vol_03 (2021) (Shirtaloon) {ASIN.1039400205}.nometa.m4b Format : MPEG-4 Format profile : Base Media Codec ID : isom (isom/iso2/mp41) File size : 1.31 GiB Duration : 24 h 39 min Overall bit rate mode : Constant Overall bit rate : 127 kb/s ISBN : 9781039400207 title : He Who Fights with Monsters 3 artist : Shirtaloon, Travis Deverell album_artist : Shirtaloon, Travis Deverell album : He Who Fights with Monsters 3: A LitRPG Adventure (He Who Fights with Monsters, Book 3) TIT3 : A LitRPG Adventure (He Who Fights with Monsters, Book 3) subtitle : A LitRPG Adventure (He Who Fights with Monsters, Book 3) genre : Science Fiction & Fantasy date : 2021 comment : <p><b>For all that Jason knows, life is amazing. But he's about to learn that all his new power, wealth, and influence comes at a price.</b></p> <p>Riding high on success, he and his team are looking to the future, preparing themselves for the challenges to come. Nothing, however, could have prepared him for the lessons his enemies have to teach. When magic is involved, the stakes can be even greater than life and death. </p> <p>While Jason’s personal enemies make plans, the greater foes plaguing his new home have been pushed to the brink. With one powerful card left to play, they are on a collision course with Jason and his team. With no one to help and more than their lives on the line, Jason and his companions must fight with more monsters than ever in the race to grow stronger. With an invincible enemy already anticipating them, they will learn that sometimes winning the battle is more important than surviving it. </p> description : <p><b>For all that Jason knows, life is amazing. But he's about to learn that all his new power, wealth, and influence comes at a price.</b></p> <p>Riding high on success, he and his team are looking to the future, preparing themselves for the challenges to come. Nothing, however, could have prepared him for the lessons his enemies have to teach. When magic is involved, the stakes can be even greater than life and death. </p> <p>While Jason’s personal enemies make plans, the greater foes plaguing his new home have been pushed to the brink. With one powerful card left to play, they are on a collision course with Jason and his team. With no one to help and more than their lives on the line, Jason and his companions must fight with more monsters than ever in the race to grow stronger. With an invincible enemy already anticipating them, they will learn that sometimes winning the battle is more important than surviving it. </p> composer : Heath Miller copyright : Podium Audio publisher : Podium Audio TRACKTOTAL : 1 grouping : He Who Fights with Monsters #3 asin : 1039400205 AUDIBLE_ASIN : 1039400205 LANGUAGE : English ITUNESADVISORY : 2 FORMAT : unabridged SERIES : He Who Fights with Monsters SERIES-PART : 3 PART : 3 MOVEMENTNAME : He Who Fights with Monsters MOVEMENT : 3 SHOWMOVEMENT : 1 ALBUMSORT : He Who Fights with Monsters 003 - He Who Fights with Monsters 3 track : 1 encoder : Lavf59.27.100 Audio ID : 1 Format : AAC LC Format/Info : Advanced Audio Codec Low Complexity Codec ID : mp4a-40-2 Duration : 24 h 39 min Bit rate mode : Constant Bit rate : 126 kb/s Channel(s) : 2 channels Channel layout : L R Sampling rate : 44.1 kHz Frame rate : 43.066 FPS (1024 SPF) Compression mode : Lossy Stream size : 1.30 GiB (99%) Default : Yes Alternate group : 1 Menus : 3 Menu #1 ID : 3 Format : Timed Text Codec ID : text Duration : 24 h 39 min Language : English For : 1 00:00:00.000 : Intro 00:00:18.227 : 1. A Question You Don’t Yet Know to Ask 00:25:26.177 : 2. Looking Forward 00:44:12.717 : 3. Adventurers Are People Too 00:59:31.670 : 4. Valkyrie 01:17:05.902 : 5. Departures 01:36:20.166 : 6. No Pot of Gold 01:49:47.710 : 7. The Glory of Success or the Price of Failure 02:12:24.150 : 8. Adequate 02:30:04.582 : 9. Trash Bonanza 02:45:30.826 : 10. Strangeness 02:57:16.480 : 11. Full Circle 03:23:18.324 : 12. Regretting it Later 03:42:22.905 : 13. Swat 03:58:15.620 : 14. The Purpose of the Adventure Society 04:16:04.969 : 15. Elven Storage Solutions 04:30:21.181 : 16. Disbanded 04:48:30.383 : 17. The Man Behind the Mouth 05:05:35.196 : 18. Search 05:26:22.177 : 19. Defiance 05:57:41.461 : 20. Hanging Around 06:14:31.738 : 21. What Doesn’t Kill You 06:37:39.269 : 22. Lingering Doubts 06:51:53.856 : 23. Scars 07:06:00.920 : 24. I Won’t Let Them Turn Me Into That 07:22:47.134 : 25. Putting the Band Back Together 07:36:49.949 : 26. Nothing Speaks Louder Than Power 07:53:58.778 : 27. My Name is Jason Asano 08:13:32.802 : 28. While They Watch Me Kill You 08:33:32.229 : 29. Inherently Corrupting 08:54:45.890 : 30. Beholden to No One 09:11:47.638 : 31. Evil Detector 09:32:58.489 : 32. The World Needs People Like You 09:53:41.430 : 33. I’m Very Big on Cowardice 10:13:48.728 : 34. More Powerful Than We Anticipated 10:29:40.329 : 35. Fate Can’t Wait to Kill Us All 10:43:28.329 : 36. Running Towards Something 10:59:34.349 : 37. Greenhouse Flowers 11:17:57.691 : 38. A Man Transformed 11:37:19.061 : 39. The Worst Possible Option 11:55:39.919 : 40. Brave Little Tailor 12:18:38.928 : 41. Terms of the Pact 12:36:34.407 : 42. Trading Safety Today For Death Tomorrow 12:55:13.191 : 43. Stalwart 13:19:14.616 : 44. I’m Sick of Fighting Magic Rocks 13:37:57.069 : 45. Crossing the Threshold 13:55:47.160 : 46. Anyone Can Be Useful 14:10:59.844 : 47. A Series of Familiar Powers 14:28:32.219 : 48. It’s Not About Killing Monsters 14:43:24.817 : 49. Sin Eater 14:59:25.426 : 50. The Most Dangerous Thing in the Dark 15:17:18.862 : 51. The Boss Comes to Town 15:38:50.704 : 52. It’s Very Complicated and You All Need to Go Away 15:55:32.691 : 53. Strong Foundations 16:14:49.858 : 54. A Valiant Death 16:30:09.275 : 55. Ambitions 16:45:21.192 : 56. Faith and Glory 17:02:50.363 : 57. Thadwick 17:25:42.500 : 58. The True Danger 17:47:05.193 : 59. Forsaken Place 18:13:21.782 : 60. Being What he Needs to Be 18:30:45.982 : 61. A Significantly More Dangerous Entity 18:47:30.710 : 62. Losing the Battle to Win the War 19:05:50.152 : 63. War of Adaptation 19:24:34.485 : 64. The Hero of This Story 19:45:00.406 : 65. Good News, Bad News 20:04:59.206 : 66. Here We Are 20:24:33.044 : 67. Outmatched 20:49:43.897 : 68. The Power of Friendship 21:14:37.312 : 69. A War of Stolen Moments 21:38:22.204 : Epilogue Chapter 1 21:55:11.669 : Epilogue Chapter 2 22:22:37.197 : Epilogue Chapter 3 22:49:28.941 : Epilogue Chapter 4 23:07:28.181 : Epilogue Chapter 5 23:27:23.776 : Epilogue Chapter 6 23:51:17.446 : Epilogue Chapter 7 24:08:30.200 : Epilogue Chapter 8 24:38:25.637 : Outro Menu #2 00:00:00.000 : Intro 00:00:18.227 : 1. A Question You Don’t Yet Know to Ask 00:25:26.177 : 2. Looking Forward 00:44:12.717 : 3. Adventurers Are People Too 00:59:31.670 : 4. Valkyrie 01:17:05.902 : 5. Departures 01:36:20.166 : 6. No Pot of Gold 01:49:47.710 : 7. The Glory of Success or the Price of Failure 02:12:24.150 : 8. Adequate 02:30:04.582 : 9. Trash Bonanza 02:45:30.826 : 10. Strangeness 02:57:16.480 : 11. Full Circle 03:23:18.324 : 12. Regretting it Later 03:42:22.905 : 13. Swat 03:58:15.620 : 14. The Purpose of the Adventure Society 04:16:04.969 : 15. Elven Storage Solutions 04:30:21.181 : 16. Disbanded 04:48:30.383 : 17. The Man Behind the Mouth 05:05:35.196 : 18. Search 05:26:22.177 : 19. Defiance 05:57:41.461 : 20. Hanging Around 06:14:31.738 : 21. What Doesn’t Kill You 06:37:39.269 : 22. Lingering Doubts 06:51:53.856 : 23. Scars 07:06:00.920 : 24. I Won’t Let Them Turn Me Into That 07:22:47.134 : 25. Putting the Band Back Together 07:36:49.949 : 26. Nothing Speaks Louder Than Power 07:53:58.778 : 27. My Name is Jason Asano 08:13:32.802 : 28. While They Watch Me Kill You 08:33:32.229 : 29. Inherently Corrupting 08:54:45.890 : 30. Beholden to No One 09:11:47.638 : 31. Evil Detector 09:32:58.489 : 32. The World Needs People Like You 09:53:41.430 : 33. I’m Very Big on Cowardice 10:13:48.728 : 34. More Powerful Than We Anticipated 10:29:40.329 : 35. Fate Can’t Wait to Kill Us All 10:43:28.329 : 36. Running Towards Something 10:59:34.349 : 37. Greenhouse Flowers 11:17:57.691 : 38. A Man Transformed 11:37:19.061 : 39. The Worst Possible Option 11:55:39.919 : 40. Brave Little Tailor 12:18:38.928 : 41. Terms of the Pact 12:36:34.407 : 42. Trading Safety Today For Death Tomorrow 12:55:13.191 : 43. Stalwart 13:19:14.616 : 44. I’m Sick of Fighting Magic Rocks 13:37:57.069 : 45. Crossing the Threshold 13:55:47.160 : 46. Anyone Can Be Useful 14:10:59.844 : 47. A Series of Familiar Powers 14:28:32.219 : 48. It’s Not About Killing Monsters 14:43:24.817 : 49. Sin Eater 14:59:25.426 : 50. The Most Dangerous Thing in the Dark 15:17:18.862 : 51. The Boss Comes to Town 15:38:50.704 : 52. It’s Very Complicated and You All Need to Go Away 15:55:32.691 : 53. Strong Foundations 16:14:49.858 : 54. A Valiant Death 16:30:09.275 : 55. Ambitions 16:45:21.192 : 56. Faith and Glory 17:02:50.363 : 57. Thadwick 17:25:42.500 : 58. The True Danger 17:47:05.193 : 59. Forsaken Place 18:13:21.782 : 60. Being What he Needs to Be 18:30:45.982 : 61. A Significantly More Dangerous Entity 18:47:30.710 : 62. Losing the Battle to Win the War 19:05:50.152 : 63. War of Adaptation 19:24:34.485 : 64. The Hero of This Story 19:45:00.406 : 65. Good News, Bad News 20:04:59.206 : 66. Here We Are 20:24:33.044 : 67. Outmatched 20:49:43.897 : 68. The Power of Friendship 21:14:37.312 : 69. A War of Stolen Moments 21:38:22.204 : Epilogue Chapter 1 21:55:11.669 : Epilogue Chapter 2 22:22:37.197 : Epilogue Chapter 3 22:49:28.941 : Epilogue Chapter 4 23:07:28.181 : Epilogue Chapter 5 23:27:23.776 : Epilogue Chapter 6 23:51:17.446 : Epilogue Chapter 7 24:08:30.200 : Epilogue Chapter 8 24:38:25.637 : Outro ``` </details> ## Screenshots <details> <summary>Metadata verification screenshots (click to expand)</summary> <img width="1040" height="721" alt="image" src="https://github.com/user-attachments/assets/6d978bc0-2b6f-4049-b145-2dfa11f6a777" /> <img width="1023" height="661" alt="image" src="https://github.com/user-attachments/assets/d6d7f279-7977-4118-8a60-078f0a7f052b" /> <img width="1022" height="665" alt="image" src="https://github.com/user-attachments/assets/c363dacd-c9a0-41df-b6a8-64b1c2116c38" /> </details> --- ## Acknowledgments Thanks to [@binyaminyblatt](https://github.com/binyaminyblatt) for the suggestion and for maintaining the Mp3tag Audible API standard, ensuring compatibility across the audiobook management ecosystem. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2026-04-25 00:19:32 +02:00
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 pull-request
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#4385
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?