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

[Bug]: Support "Auto-Embed Metadata" for M4A Format in AudioBookShelf #3066

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

Originally created by @carethink11 on GitHub (Nov 1, 2025).

What happened?

Request: Support "Auto-Embed Metadata" for M4A Format in AudioBookShelf

Issue Description:
The "Auto-Embed Metadata" feature in AudioBookShelf currently fails when processing M4A audio files. Logs show FFmpeg errors like "Invalid audio stream" and "Error opening output file" due to format incompatibility. Investigation reveals the root cause is missing adaptation for M4A metadata handling:

  1. Even if a file is actually M4A (AAC-encoded), if its extension is .mp3, the app still uses MP3’s ID3 tag logic to call FFmpeg, causing conflicts.
  2. For files with .m4a extension, the app likely lacks code to embed metadata using MP4 container tags (e.g., iTunes tags), so metadata can’t be written.

需求：在 AudioBookShelf 中支持 M4A 格式的“自动嵌入元数据”功能

问题描述：
当前 AudioBookShelf 的“自动嵌入元数据”功能处理 M4A 格式音频文件时会失败，日志显示 FFmpeg 因格式不兼容报错（如“Invalid audio stream”“Error opening output file”）。经排查，问题根源是软件未适配 M4A 格式的元数据处理：

  1. 就算文件实际是 M4A（AAC 编码），只要后缀名是 .mp3，软件仍会用 MP3 的 ID3 标签逻辑调用 FFmpeg，导致格式冲突。
  2. 对于 .m4a 后缀的文件，软件可能没有实现 MP4 容器标签（比如 iTunes 标签）的嵌入逻辑，元数据根本写不进去。

What did you expect to happen?

In practice, many audiobooks are distributed in M4A (especially high-quality content), so missing support for this format hurts user experience.

Feature Request:
Please add support for M4A in the "Auto-Embed Metadata" feature. Key logic suggestions:

  1. Auto-format detection: Identify files by their actual encoding (not just extension) using tools like FFmpeg or built-in libraries to check if it’s M4A/AAC.
  2. Format-specific tag handling:
    • Keep existing ID3 tag logic (e.g., TIT2 for title, TALB for album) for MP3 files.
    • For M4A, adapt to MP4 container tag standards (e.g., ©nam for title, ©alb for album, covr for cover art).
  3. Avoid forced format conversion: When processing M4A, only modify metadata without changing the encoding (keep output as M4A, just update tags).
  4. Support common variants: Work with common M4A encodings (e.g., AAC-LC, HE-AAC) and mainstream MP4 container versions.

Use Case:
Users managing M4A audiobooks in AudioBookShelf should be able to auto-embed metadata (cover art, title, author) without altering the original file’s encoding or quality, improving efficiency for multi-format audiobook libraries.

实际使用中，很多有声书都是 M4A 格式（尤其是高音质内容），不支持这个格式会影响用户体验。

功能需求：
希望开发团队给“自动嵌入元数据”功能加个 M4A 支持，核心逻辑建议如下：

  1. 自动识别格式：通过文件真实编码（别只看后缀名）来判断格式，比如用 FFmpeg 或内置库检测是不是 M4A/AAC。
  2. 按格式处理标签：
    • MP3 文件就保持现有的 ID3 标签逻辑（比如 TIT2 存标题、TALB 存专辑）。
    • M4A 文件要适配 MP4 容器的标签规范（比如 ©nam 存标题、©alb 存专辑、covr 存封面）。
  3. 别强制转格式：处理 M4A 时，只改元数据，别动编码（输入是 M4A，输出还得是 M4A，就更新下标签）。
  4. 支持常见变体：兼容 M4A 常用的编码（比��� AAC-LC、HE-AAC）和主流的 MP4 容器版本。

使用场景：
用户用 AudioBookShelf 管理 M4A 有声书时，能自动嵌入封面、标题、作者这些元数据，还不改变原文件的编码和音质，提升多格式有声书库的管理效率。

Steps to reproduce the issue

Additional Info:

  • Key error log snippet: [mp3 @ ...] Invalid audio stream. Exactly one MP3 audio stream is required
  • Test file details: M4A format (AAC-encoded); error triggers when extension is .mp3; verify real format via mediainfo or ffprobe.

补充信息：

  • 关键错误日志片段：[mp3 @ ...] Invalid audio stream. Exactly one MP3 audio stream is required
  • 测试文件信息：M4A 格式（AAC 编码），后缀为 .mp3 时会触发错误，可通过 mediainfo 或 ffprobe 验证真实格式。

Audiobookshelf version

2.30.0

How are you running audiobookshelf?

Docker

What OS is your Audiobookshelf server hosted from?

Linux

If the issue is being seen in the UI, what browsers are you seeing the problem on?

Safari

Logs

[2025-11-01 17:09:51.827] INFO: [AudioMetadataManager] Starting metadata embed task Embedding metadata in audiobook "凡人修仙传|下部|桑梓单播版本".
[2025-11-01 17:09:51.912] ERROR: Error adding cover image and metadata: Error: ffmpeg exited with code 234: Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3.
Error opening output files: Invalid argument

    at ChildProcess.<anonymous> (/app/server/libs/fluentFfmpeg/processor.js:178:22)
    at ChildProcess.emit (node:events:524:28)
    at ChildProcess._handle.onexit (node:internal/child_process:293:12)
[2025-11-01 17:09:51.913] ERROR: ffmpeg stdout: 
[2025-11-01 17:09:51.913] ERROR: ffmpeg stderr: ffmpeg version 6.1.2 Copyright (c) 2000-2024 the FFmpeg developers
  built with gcc 14.2.0 (Alpine 14.2.0)
  configuration: --prefix=/usr --disable-librtmp --disable-lzma --disable-static --disable-stripping --enable-avfilter --enable-gpl --enable-ladspa --enable-libaom --enable-libass --enable-libbluray --enable-libdav1d --enable-libdrm --enable-libfontconfig --enable-libfreetype --enable-libfribidi --enable-libharfbuzz --enable-libmp3lame --enable-libopenmpt --enable-libopus --enable-libplacebo --enable-libpulse --enable-librav1e --enable-librist --enable-libsoxr --enable-libsrt --enable-libssh --enable-libtheora --enable-libv4l2 --enable-libvidstab --enable-libvorbis --enable-libvpx --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxcb --enable-libxml2 --enable-libxvid --enable-libzimg --enable-libzmq --enable-lto=auto --enable-lv2 --enable-openssl --enable-pic --enable-postproc --enable-pthreads --enable-shared --enable-vaapi --enable-vdpau --enable-version3 --enable-vulkan --optflags=-O3 --enable-libjxl --enable-libsvtav1
  libavutil      58. 29.100 / 58. 29.100
  libavcodec     60. 31.102 / 60. 31.102
  libavformat    60. 16.100 / 60. 16.100
  libavdevice    60.  3.100 / 60.  3.100
  libavfilter     9. 12.100 /  9. 12.100
  libswscale      7.  5.100 /  7.  5.100
  libswresample   4. 12.100 /  4. 12.100
  libpostproc    57.  3.100 / 57.  3.100
Input #0, mov,mp4,m4a,3gp,3g2,mj2, from '/audiobooks/凡人修仙传/0001-wpfx.org.mp3':
  Metadata:
    major_brand     : M4A 
    minor_version   : 1
    compatible_brands: isomiso2M4A mp42
    encoder         : Lavf58.20.100
  Duration: 00:20:44.45, start: 0.000000, bitrate: 129 kb/s
  Stream #0:0[0x1](und): Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 128 kb/s (default)
    Metadata:
      handler_name    : SoundHandler
      vendor_id       : [0][0][0][0]
Input #1, ffmetadata, from '/metadata/cache/items/d44914cb-a3a0-44d0-8c69-4e1700fca5de/ffmetadata.txt':
  Metadata:
    title           : 凡人修仙传|下部|桑梓单播版本
    album           : 凡人修仙传|下部|桑梓单播版本: 山村小子如何笑傲三界
    TIT3            : 山村小子如何笑傲三界
    genre           : 有声书
    date            : 2018
    comment         : <p><strong>《凡人修仙传》上部和下部都已加入VIP，会员</strong><strong>戳<a href="https://m.ximalaya.com/youshengshu/3290982/">《凡人修仙传（上）｜ 桑梓演播》</a>免费听上部哦~</strong></p><p>【内容简介】</p><p>
    description     : <p><strong>《凡人修仙传》上部和下部都已加入VIP，会员</strong><strong>戳<a href="https://m.ximalaya.com/youshengshu/3290982/">《凡人修仙传（上）｜ 桑梓演播》</a>免费听上部哦~</strong></p><p>【内容简介】</p><p>
    composer        : 桑梓讲故事
    copyright       : 喜马拉雅
    publisher       : 喜马拉雅
    TRACKTOTAL      : 20
  Duration: N/A, start: 0.000000, bitrate: N/A
Input #2, image2, from '/metadata/items/d44914cb-a3a0-44d0-8c69-4e1700fca5de/cover.jpg':
  Duration: 00:00:00.04, start: 0.000000, bitrate: 38017 kb/s
  Stream #2:0: Video: mjpeg (Baseline), yuvj444p(pc, bt470bg/unknown/unknown), 640x640, 25 fps, 25 tbr, 25 tbn
[mp3 @ 0xffffb9a5b9c0] Invalid audio stream. Exactly one MP3 audio stream is required.
[out#0/mp3 @ 0xffffb9d8de60] Could not write header (incorrect codec parameters ?): Invalid argument
Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3.
Error opening output files: Invalid argument

[2025-11-01 17:09:51.913] ERROR: [AudioMetadataManager] Failed to tag audio file "/audiobooks/凡人修仙传/0001-wpfx.org.mp3" Error: ffmpeg exited with code 234: Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3.
Error opening output files: Invalid argument

    at ChildProcess.<anonymous> (/app/server/libs/fluentFfmpeg/processor.js:178:22)
    at ChildProcess.emit (node:events:524:28)
    at ChildProcess._handle.onexit (node:internal/child_process:293:12)

Additional Notes

No response

Originally created by @carethink11 on GitHub (Nov 1, 2025). ### What happened? # Request: Support "Auto-Embed Metadata" for M4A Format in AudioBookShelf **Issue Description**: The "Auto-Embed Metadata" feature in AudioBookShelf currently fails when processing M4A audio files. Logs show FFmpeg errors like "Invalid audio stream" and "Error opening output file" due to format incompatibility. Investigation reveals the root cause is missing adaptation for M4A metadata handling: 1. Even if a file is actually M4A (AAC-encoded), if its extension is `.mp3`, the app still uses MP3’s ID3 tag logic to call FFmpeg, causing conflicts. 2. For files with `.m4a` extension, the app likely lacks code to embed metadata using MP4 container tags (e.g., iTunes tags), so metadata can’t be written. # 需求：在 AudioBookShelf 中支持 M4A 格式的“自动嵌入元数据”功能 **问题描述**： 当前 AudioBookShelf 的“自动嵌入元数据”功能处理 M4A 格式音频文件时会失败，日志显示 FFmpeg 因格式不兼容报错（如“Invalid audio stream”“Error opening output file”）。经排查，问题根源是软件未适配 M4A 格式的元数据处理： 1. 就算文件实际是 M4A（AAC 编码），只要后缀名是 `.mp3`，软件仍会用 MP3 的 ID3 标签逻辑调用 FFmpeg，导致格式冲突。 2. 对于 `.m4a` 后缀的文件，软件可能没有实现 MP4 容器标签（比如 iTunes 标签）的嵌入逻辑，元数据根本写不进去。 ### What did you expect to happen? In practice, many audiobooks are distributed in M4A (especially high-quality content), so missing support for this format hurts user experience. **Feature Request**: Please add support for M4A in the "Auto-Embed Metadata" feature. Key logic suggestions: 1. **Auto-format detection**: Identify files by their actual encoding (not just extension) using tools like FFmpeg or built-in libraries to check if it’s M4A/AAC. 2. **Format-specific tag handling**: - Keep existing ID3 tag logic (e.g., `TIT2` for title, `TALB` for album) for MP3 files. - For M4A, adapt to MP4 container tag standards (e.g., `©nam` for title, `©alb` for album, `covr` for cover art). 3. **Avoid forced format conversion**: When processing M4A, only modify metadata without changing the encoding (keep output as M4A, just update tags). 4. **Support common variants**: Work with common M4A encodings (e.g., AAC-LC, HE-AAC) and mainstream MP4 container versions. **Use Case**: Users managing M4A audiobooks in AudioBookShelf should be able to auto-embed metadata (cover art, title, author) without altering the original file’s encoding or quality, improving efficiency for multi-format audiobook libraries. 实际使用中，很多有声书都是 M4A 格式（尤其是高音质内容），不支持这个格式会影响用户体验。 **功能需求**： 希望开发团队给“自动嵌入元数据”功能加个 M4A 支持，核心逻辑建议如下： 1. **自动识别格式**：通过文件真实编码（别只看后缀名）来判断格式，比如用 FFmpeg 或内置库检测是不是 M4A/AAC。 2. **按格式处理标签**： - MP3 文件就保持现有的 ID3 标签逻辑（比如 `TIT2` 存标题、`TALB` 存专辑）。 - M4A 文件要适配 MP4 容器的标签规范（比如 `©nam` 存标题、`©alb` 存专辑、`covr` 存封面）。 3. **别强制转格式**：处理 M4A 时，只改元数据，别动编码（输入是 M4A，输出还得是 M4A，就更新下标签）。 4. **支持常见变体**：兼容 M4A 常用的编码（比��� AAC-LC、HE-AAC）和主流的 MP4 容器版本。 **使用场景**： 用户用 AudioBookShelf 管理 M4A 有声书时，能自动嵌入封面、标题、作者这些元数据，还不改变原文件的编码和音质，提升多格式有声书库的管理效率。 ### Steps to reproduce the issue **Additional Info**: - Key error log snippet: `[mp3 @ ...] Invalid audio stream. Exactly one MP3 audio stream is required` - Test file details: M4A format (AAC-encoded); error triggers when extension is `.mp3`; verify real format via `mediainfo` or `ffprobe`. **补充信息**： - 关键错误日志片段：`[mp3 @ ...] Invalid audio stream. Exactly one MP3 audio stream is required` - 测试文件信息：M4A 格式（AAC 编码），后缀为 `.mp3` 时会触发错误，可通过 `mediainfo` 或 `ffprobe` 验证真实格式。 ### Audiobookshelf version 2.30.0 ### How are you running audiobookshelf? Docker ### What OS is your Audiobookshelf server hosted from? Linux ### If the issue is being seen in the UI, what browsers are you seeing the problem on? Safari ### Logs ```shell [2025-11-01 17:09:51.827] INFO: [AudioMetadataManager] Starting metadata embed task Embedding metadata in audiobook "凡人修仙传|下部|桑梓单播版本". [2025-11-01 17:09:51.912] ERROR: Error adding cover image and metadata: Error: ffmpeg exited with code 234: Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3. Error opening output files: Invalid argument at ChildProcess.<anonymous> (/app/server/libs/fluentFfmpeg/processor.js:178:22) at ChildProcess.emit (node:events:524:28) at ChildProcess._handle.onexit (node:internal/child_process:293:12) [2025-11-01 17:09:51.913] ERROR: ffmpeg stdout: [2025-11-01 17:09:51.913] ERROR: ffmpeg stderr: ffmpeg version 6.1.2 Copyright (c) 2000-2024 the FFmpeg developers built with gcc 14.2.0 (Alpine 14.2.0) configuration: --prefix=/usr --disable-librtmp --disable-lzma --disable-static --disable-stripping --enable-avfilter --enable-gpl --enable-ladspa --enable-libaom --enable-libass --enable-libbluray --enable-libdav1d --enable-libdrm --enable-libfontconfig --enable-libfreetype --enable-libfribidi --enable-libharfbuzz --enable-libmp3lame --enable-libopenmpt --enable-libopus --enable-libplacebo --enable-libpulse --enable-librav1e --enable-librist --enable-libsoxr --enable-libsrt --enable-libssh --enable-libtheora --enable-libv4l2 --enable-libvidstab --enable-libvorbis --enable-libvpx --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxcb --enable-libxml2 --enable-libxvid --enable-libzimg --enable-libzmq --enable-lto=auto --enable-lv2 --enable-openssl --enable-pic --enable-postproc --enable-pthreads --enable-shared --enable-vaapi --enable-vdpau --enable-version3 --enable-vulkan --optflags=-O3 --enable-libjxl --enable-libsvtav1 libavutil 58. 29.100 / 58. 29.100 libavcodec 60. 31.102 / 60. 31.102 libavformat 60. 16.100 / 60. 16.100 libavdevice 60. 3.100 / 60. 3.100 libavfilter 9. 12.100 / 9. 12.100 libswscale 7. 5.100 / 7. 5.100 libswresample 4. 12.100 / 4. 12.100 libpostproc 57. 3.100 / 57. 3.100 Input #0, mov,mp4,m4a,3gp,3g2,mj2, from '/audiobooks/凡人修仙传/0001-wpfx.org.mp3': Metadata: major_brand : M4A minor_version : 1 compatible_brands: isomiso2M4A mp42 encoder : Lavf58.20.100 Duration: 00:20:44.45, start: 0.000000, bitrate: 129 kb/s Stream #0:0[0x1](und): Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 128 kb/s (default) Metadata: handler_name : SoundHandler vendor_id : [0][0][0][0] Input #1, ffmetadata, from '/metadata/cache/items/d44914cb-a3a0-44d0-8c69-4e1700fca5de/ffmetadata.txt': Metadata: title : 凡人修仙传|下部|桑梓单播版本 album : 凡人修仙传|下部|桑梓单播版本: 山村小子如何笑傲三界 TIT3 : 山村小子如何笑傲三界 genre : 有声书 date : 2018 comment : <p><strong>《凡人修仙传》上部和下部都已加入VIP，会员</strong><strong>戳<a href="https://m.ximalaya.com/youshengshu/3290982/">《凡人修仙传（上）｜ 桑梓演播》</a>免费听上部哦~</strong></p><p>【内容简介】</p><p> description : <p><strong>《凡人修仙传》上部和下部都已加入VIP，会员</strong><strong>戳<a href="https://m.ximalaya.com/youshengshu/3290982/">《凡人修仙传（上）｜ 桑梓演播》</a>免费听上部哦~</strong></p><p>【内容简介】</p><p> composer : 桑梓讲故事 copyright : 喜马拉雅 publisher : 喜马拉雅 TRACKTOTAL : 20 Duration: N/A, start: 0.000000, bitrate: N/A Input #2, image2, from '/metadata/items/d44914cb-a3a0-44d0-8c69-4e1700fca5de/cover.jpg': Duration: 00:00:00.04, start: 0.000000, bitrate: 38017 kb/s Stream #2:0: Video: mjpeg (Baseline), yuvj444p(pc, bt470bg/unknown/unknown), 640x640, 25 fps, 25 tbr, 25 tbn [mp3 @ 0xffffb9a5b9c0] Invalid audio stream. Exactly one MP3 audio stream is required. [out#0/mp3 @ 0xffffb9d8de60] Could not write header (incorrect codec parameters ?): Invalid argument Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3. Error opening output files: Invalid argument [2025-11-01 17:09:51.913] ERROR: [AudioMetadataManager] Failed to tag audio file "/audiobooks/凡人修仙传/0001-wpfx.org.mp3" Error: ffmpeg exited with code 234: Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3. Error opening output files: Invalid argument at ChildProcess.<anonymous> (/app/server/libs/fluentFfmpeg/processor.js:178:22) at ChildProcess.emit (node:events:524:28) at ChildProcess._handle.onexit (node:internal/child_process:293:12) ``` ### Additional Notes _No response_
adam added the bug label 2026-04-25 00:13:22 +02:00
adam closed this issue 2026-04-25 00:13:22 +02:00
adam commented 2026-04-25 00:13:22 +02:00
Author
Owner
Copy Link
Copy Source

@thatguy7 commented on GitHub (Nov 3, 2025):

You seem to confuse codec and container format.

The codec is the format of the audio-stream. It's the way the audio signal is represented digitally. Typical codecs are AAC, mp3 and opus.

The container is the layout of the audio file as a whole, e.i. a convenvention where in the file the audio stream is stored and where the tags and cover image is. Examples of this is m4a/m4b (which both are mp4), mp3 (confusingly named the same as the codec), ogg, ...

What you are trying to do is put a AAC audio stream in a .mp3 container. I do not think this is supported by the mp3 audio container specification. It certainly is not supported by ffmpeg, which ABS uses - so there is nothing that can be done about that on the ABS side.

Your options are either to use a different container format, like .m4a/.m4b - or transcode your audio to mp3 codec and put that in a .mp3 container.

@thatguy7 commented on GitHub (Nov 3, 2025): You seem to confuse codec and container format. The **codec** is the format of the audio-stream. It's the way the audio signal is represented digitally. Typical codecs are AAC, mp3 and opus. The **container** is the layout of the audio file as a whole, e.i. a convenvention where in the file the audio stream is stored and where the tags and cover image is. Examples of this is m4a/m4b (which both are mp4), mp3 (confusingly named the same as the codec), ogg, ... What you are trying to do is put a AAC audio stream in a .mp3 container. I do not think this is supported by the mp3 audio container specification. It certainly is not supported by ffmpeg, which ABS uses - so there is nothing that can be done about that on the ABS side. Your options are either to use a different container format, like .m4a/.m4b - or transcode your audio to mp3 codec and put that in a .mp3 container.
adam commented 2026-04-25 00:13:23 +02:00
Author
Owner
Copy Link
Copy Source

@carethink11 commented on GitHub (Nov 3, 2025):

I didn't express myself clearly.

Actually, I encountered a "failure to embed metadata" when processing AAC-encoded audio in m4a format.
Additionally, I also get a "failure to embed metadata" when processing AAC-encoded audio with an mp3 extension (which should actually be m4a, but the extension was changed to mp3).

是我表述的不清晰，实际上，我是在处理aac编码的m4a格式音频时发生了"嵌入元数据失败"。另外我在在处理aac编码的mp3扩展名的音频(实际上应该是m4a，只不过扩展名被改成了mp3)时，也会发生 "嵌入元数据失败"

@carethink11 commented on GitHub (Nov 3, 2025): I didn't express myself clearly. Actually, I encountered a "failure to embed metadata" when processing AAC-encoded audio in m4a format. Additionally, I also get a "failure to embed metadata" when processing AAC-encoded audio with an mp3 extension (which should actually be m4a, but the extension was changed to mp3). 是我表述的不清晰，实际上，我是在处理aac编码的m4a格式音频时发生了"嵌入元数据失败"。另外我在在处理aac编码的mp3扩展名的音频(实际上应该是m4a，只不过扩展名被改成了mp3)时，也会发生 "嵌入元数据失败"
adam commented 2026-04-25 00:13:23 +02:00
Author
Owner
Copy Link
Copy Source

@thatguy7 commented on GitHub (Nov 3, 2025):

Embedding metadata in m4a files works fine. I do it all the time. The only problem there is that when you have your book split by chapters in multiple files, the title of all files will be set to "book title" instead of chapter title.

According to your logs:

Input #0, mov,mp4,m4a,3gp,3g2,mj2, from '/audiobooks/凡人修仙传/0001-wpfx.org.mp3':
  Metadata:
    major_brand     : M4A 
    minor_version   : 1
    compatible_brands: isomiso2M4A mp42
    encoder         : Lavf58.20.100
  Duration: 00:20:44.45, start: 0.000000, bitrate: 129 kb/s
  Stream #0:0[0x1](und): Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 128 kb/s (default)
    Metadata:
      handler_name    : SoundHandler
      vendor_id       : [0][0][0][0]

The file that is to be tagged is /audiobooks/凡人修仙传/0001-wpfx.org.mp3. It seems to be a .m4a container with a AAC stream in it, just named incorrectly .mp3. When ABS embeds tags in a file, it will use ffmpeg to build a completely new file from the input files with the correct tags embedded. In your case that new file is:

Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3

Since the output file end with .mp3, ffmpeg will write a proper mp3 file. Since there is no mp3-stream to put into the .mp3 file, that fails.

[mp3 @ 0xffffb9a5b9c0] Invalid audio stream. Exactly one MP3 audio stream is required.

ffmpeg will read your mislabeled files correctly, but it will not write an incorrect .mp3 file for you.

So again, your options are:

  • reencode your files to actually be proper .mp3 files
  • use a .mp4 container by properly naming your files as .m4a/.m4b

You can't rename a .pdf to .png and expect for things to just work. ABS does the correct thing here. Your file names are messed up.

@thatguy7 commented on GitHub (Nov 3, 2025): Embedding metadata in m4a files works fine. I do it all the time. The only problem there is that when you have your book split by chapters in multiple files, the title of all files will be set to "book title" instead of chapter title. According to your logs: ``` Input #0, mov,mp4,m4a,3gp,3g2,mj2, from '/audiobooks/凡人修仙传/0001-wpfx.org.mp3': Metadata: major_brand : M4A minor_version : 1 compatible_brands: isomiso2M4A mp42 encoder : Lavf58.20.100 Duration: 00:20:44.45, start: 0.000000, bitrate: 129 kb/s Stream #0:0[0x1](und): Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 128 kb/s (default) Metadata: handler_name : SoundHandler vendor_id : [0][0][0][0] ``` The file that is to be tagged is `/audiobooks/凡人修仙传/0001-wpfx.org.mp3`. It seems to be a .m4a container with a AAC stream in it, just named incorrectly `.mp3`. When ABS embeds tags in a file, it will use ffmpeg to build a completely new file from the input files with the correct tags embedded. In your case that new file is: ``` Error opening output file /audiobooks/凡人修仙传/0001-wpfx.org.tmp.mp3 ``` Since the output file end with `.mp3`, ffmpeg will write a proper mp3 file. Since there is no mp3-stream to put into the .mp3 file, that fails. ``` [mp3 @ 0xffffb9a5b9c0] Invalid audio stream. Exactly one MP3 audio stream is required. ``` ffmpeg will read your mislabeled files correctly, but it will not write an incorrect .mp3 file for you. So again, your options are: * reencode your files to actually be proper .mp3 files * use a .mp4 container by properly naming your files as .m4a/.m4b You can't rename a .pdf to .png and expect for things to just work. ABS does the correct thing here. Your file names are messed up.
adam commented 2026-04-25 00:13:23 +02:00
Author
Owner
Copy Link
Copy Source

@carethink11 commented on GitHub (Nov 3, 2025):

Image

Wow, your analysis is totally spot-on! I finally get it now. That’s exactly the problem I was having—thanks so much for sorting it out for me. The cause must be that the audio file I downloaded had its extension incorrectly changed by the uploader. I’ll be more careful from now on, and I really appreciate your help. Your tech skills are awesome!

@carethink11 commented on GitHub (Nov 3, 2025): <img width="1038" height="459" alt="Image" src="https://github.com/user-attachments/assets/05d829ad-9ce6-41db-8fa0-fdccef5bd872" /> Wow, your analysis is totally spot-on! I finally get it now. That’s exactly the problem I was having—thanks so much for sorting it out for me. The cause must be that the audio file I downloaded had its extension incorrectly changed by the uploader. I’ll be more careful from now on, and I really appreciate your help. Your tech skills are awesome!
adam commented 2026-04-25 00:13:24 +02:00
Author
Owner
Copy Link
Copy Source

@thatguy7 commented on GitHub (Nov 4, 2025):

Glad I could help. Close this issue if the problem is resolved.

@thatguy7 commented on GitHub (Nov 4, 2025): Glad I could help. Close this issue if the problem is resolved.
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 bug
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#3066
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?