m4b-tool

m4b-tool

m4b-tool is a is a wrapper for ffmpeg and mp4v2 to merge, split or and manipulate audiobook files with chapters. Although m4b-tool is designed to handle m4b files, nearly all audio formats should be supported, e.g. mp3, aac, ogg, alac and flac.

Support me via GitHub sponsors

If you are using any of my projects and find them helpful, please consider donating to support me. I plan to use the money to support other open source projects or charitable purposes. Thank you!

Current monthly sponsors >= 25.00$

Special thanks to all sponsors donating a monthly amount of >= 25.00$.

Become a sponsor

Usage with Nix

Get Nix and ensure that Flakes are enabled.

• Running: nix run github:sandreas/m4b-tool or nix run github:sandreas/m4b-tool#m4b-tool-libfdk
  • The latter will build FFMpeg using libfdk_aac, which will take longer.
• Building: nix build github:sandreas/m4b-tool or nix build github:sandreas/m4b-tool#m4b-tool-libfdk
  • Wrapper script is located at ./result/bin/m4b-tool
• Developing: Clone and nix develop
  • When done updating dependencies, run composer2nix --executable --composition=composer.nix to update the .nix files

Announcement

I started an experiment, that now has reached an early alpha level and can be tried out. The command line tool is written in C#, fully open source and is called tone. It already has a pretty decent feature set, so if you would like to try it, here it is:

https://github.com/sandreas/tone

This announcement does NOT mean, that m4b-tool is deprecated or will be soon. The development of m4b-tool will go on (at least until tone has a feature-set similar to m4b-tool). It's just to have an alternative tool for features, that may have limitations.

Have fun, can't wait to get your feedback.

❗❗❗Important Note❗❗❗

Unfortunately I am pretty busy at the moment, so m4b-tool 0.4.2 is very old. Since it is not planned to release a newer version without having complete documentation, there is only the latest pre-release getting bug fixes. It is already pretty stable, so if you are experiencing bugs with v0.4.2, please try the latest pre-release, if it has been already fixed there.

Thank you, sandreas

https://pilabor.com

Features

• merge a set of audio files (e.g. MP3 or AAC) into a single m4b file
• split a single m4b file into several output files by chapters or a flac encoded album into single tracks via cue sheet
• Add or adjust chapters for an existing m4b file via silence detection or musicbrainz

TL;DR - examples for the most common tasks

Merge multiple files

merge all audio files in directory data/my-audio-book into file data/merged.m4b (tags are retained and data/my-audio-book/cover.jpg and data/my-audio-book/description.txt are embedded, if available)

m4b-tool merge "data/my-audio-book/" --output-file="data/merged.m4b"

Split one file by chapters

split one big m4b file by chapters into multiple mp3 files at data/my-audio-book_splitted/ (tags are retained, data/my-audio-book_splitted/cover.jpg is created, if m4b contains a cover)

m4b-tool split --audio-format mp3 --audio-bitrate 96k --audio-channels 1 --audio-samplerate 22050 "data/my-audio-book.m4b"

Chapters adjustment of a file via silence detection

chapters can try to adjust existing chapters of an m4b by silence detection

m4b-tool chapters --adjust-by-silence -o "data/destination-with-adjusted-chapters.m4b" "data/source-with-misplaced-chapters.m4b"

Best practices

Since the most used subcommand of m4b-tool seems to be merge, lets talk about best practice...

Step 0 - Take a look at the docker image

Unfortunately m4b-tool has many dependencies. Not only one-liners, if you would like to get the best quality and tagging support, many dependencies have to be compiled manually with extra options. Thats why you should take a look at the docker image, which comes with all the bells and whistles of top audio quality, top tagging support and easy installation and has almost no disadvantages.

Note: If you are on windows, it might be difficult to make it work

Step 1 - Organizing your audiobooks in directories

When merging audiobooks, you should prepare them - the following directory structure helps a lot, even if you only merge one single audiobook:

input/<main genre>/<author>/<title>

or if it is a series

input/<main genre>/<author>/<series>/<series-part> - <title>

Examples:

input/Fantasy/J.K. Rowling/Quidditch Through the Ages/
input/Fantasy/J.K. Rowling/Harry Potter/1 - Harry Potter and the Philosopher's Stone/

Note: If your audiobook title contains invalid path characters like /, just replace them with a dash -.

Step 2 - add cover and a description

Now, because you almost always want a cover and a description for your audiobook, you should add the following files in the main directory:

• cover.jpg (or cover.jpeg or cover.png)
• description.txt (Be sure to use UTF-8 text file encoding for the contents)

Examples:

input/Fantasy/J.K. Rowling/Quidditch Through the Ages/cover.jpg
input/Fantasy/J.K. Rowling/Quidditch Through the Ages/description.txt

Note: m4b-tool will find and embed these files automatically but does not fail, if they are not present

Step 3 - chapters

Chapters are nice to add waypoints for your audiobook. They help to remember the last position and improve the experience in general.

fixed chapters

If you would like to adjust chapters manually, you can add a chapters.txt (same location as cover.jpg) with following contents (<chapter-start> <chapter-title>):

00:00:00.000 Intro
00:04:19.153 This is
00:09:24.078 A way to add
00:14:34.500 Chapters manually

by tag

If your input files are tagged, these tags will be used to create the chapter metadata by its title. So if you tag your input files with valid chapter names as track title, this will result in a nice and clean m4b-file with valid chapter names.

by length

Another great feature since m4b-tool v.0.4.0 is the --max-chapter-length parameter. Often the individual input files are too big which results in chapters with a very long duration. This can be annoying, if you would like to jump to a certain point, since you have to rewind or fast-forward and hold the button for a long time, instead of just tipping previous or next a few times. To automatically add sub-chapters, you could provide:

--max-chapter-length=300,900

This will cause m4b-tool

• Trying to preserve original chapters as long as they are not longer than 15 minutes (900 seconds)
• If a track is longer than 15 minutes
  • Perform a silence detection and try to add sub-chapters at every silence between 5 minutes (300 seconds) and 15 minutes (900 seconds)
  • If no silence is detected, add a hard cut sub-chapter every 5 minutes

Sub-chapters are named like the original and get an additional index. This is a nice way to keep the real names but not having chapters with a too long duration.

Step 4 (optional) - for iPod owners

If you own an iPod, there might be a problem with too long audiobooks, since iPods only support 32bit sampling rates. If your audiobook is longer than 27 hours with 22050Hz sampling rate, you could provide --adjust-for-ipod, to automatically downsample your audiobook, which results in lower quality, but at least its working on your good old iPod...

Step 5 (optional) - more cpu cores, faster conversion

m4b-tool supports multiple conversion tasks in parallel with the --jobs parameter (e.g. --jobs=2). If you have to convert more than one file, which is the common case, you nearly double the merge speed by providing the --jobs=2 parameter (or quadruplicate with --jobs=4, if you have a quad core system, etc.). Don't provide a number higher than the number of cores on your system - this will slow down the merge...

Note: If you run the conversion on all your cores, it will result in almost 100% CPU usage, which may lead to slower system performance

Step 6 - Use the --batch-pattern feature

In m4b-tool v.0.4.0 the --batch-pattern feature was added. It can be used to batch-convert multiple audiobooks at once, but also to just convert one single audiobook - because you can create tags from an existing directory structure.

Hint: The output-file parameter has to be a directory, when using --batch-pattern.

Even multiple --batch-pattern parameters are supported, while the first match will be used first. So if you created the directory structure as described above, the final command to merge input/Fantasy/Harry Potter/1 - Harry Potter and the Philosopher's Stone/ to output/Fantasy/Harry Potter/1 - Harry Potter and the Philosopher's Stone.m4b would look like this:

m4b-tool merge -v --jobs=2 --output-file="output/" --max-chapter-length=300,900 --adjust-for-ipod --batch-pattern="input/%g/%a/%s/%p - %n/"  --batch-pattern="input/%g/%a/%n/" "input/"

In --batch-pattern mode, existing files are skipped by default

Result

If you performed the above steps with the docker image or installed and compiled all dependencies, you should get the following result:

• Top quality audio by using libfdk_aac encoder
• Series and single audiobooks have valid tags for genre, author, title, sorttitle, etc. from --batch-pattern usage
• If the files cover.jpg (or cover.jpeg or cover.png) and description.txt exist in the main directories, a cover, a description and a longdesc are embedded
• If you tagged the input files, real chapter names should appear in your player
• No more chapters longer than 15 minutes
• Working iPod versions for audiobooks longer than 27 hours

Installation

Docker

To use docker with m4b-tool, you first have to

• pull the official docker image (recommended)
• or build the Dockerfile in the main directory

Official image

The official docker images are available on DockerHub. They are somewhat experimental, but have proven to work well. The latest tag is considered as way to go with the bleeding edge features and fixes. Every now and then a dated tag is published (e.g. sandreas/m4b-tool:2022-09-25), that is considered as pretty stable, to ensure a broken latest image will not break your whole setup.

# pull the image
docker pull sandreas/m4b-tool:latest

# create an alias for m4b-tool running docker
alias m4b-tool='docker run -it --rm -u $(id -u):$(id -g) -v "$(pwd)":/mnt sandreas/m4b-tool:latest'

# testing the command
m4b-tool --version

Note: If you use the alias above, keep in mind that you cannot use absolute paths (e.g. /tmp/data/audiobooks/harry potter 1) or symlinks. You must change into the directory and use relative paths (e.g. cd /tmp/data && m4b-tool merge "audiobooks/harry potter 1" --output-file harry.m4b)

Build manually or use a specific release version

To manually build a docker container for a specific m4b-tool release, it is required to provide an extra parameter for downloading a specific version into the image, e.g. for v.0.4.1:

# clone m4b-tool repository
git clone https://github.com/sandreas/m4b-tool.git

# change directory
cd m4b-tool

# build docker image - this will take a while
docker build . -t m4b-tool

# create an alias for m4b-tool running docker
alias m4b-tool='docker run -it --rm -u $(id -u):$(id -g) -v "$(pwd)":/mnt m4b-tool