# m4b-tool for merging and chapterizing audiobook libraries

> m4b-tool is a PHP command line wrapper around ffmpeg, mp4v2 and related audio tools for assembling, splitting and editing audiobook chapters. It suits library maintainers and audiobook producers, but its dependency-heavy setup and uneven release documentation require care.

**sandreas/m4b-tool** — m4b-tool is a command line utility to merge, split and chapterize audiobook files such as mp3, ogg, flac, m4a or m4b

- Repository: https://github.com/sandreas/m4b-tool
- Stars: 1,579 · Forks: 96
- Language: PHP
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/sandreas-m4b-tool

## What m4b-tool does to audiobook collections

m4b-tool addresses the repetitive filesystem work involved in turning a directory of audio files into one chaptered audiobook. Its `merge` command can collect files such as MP3 or AAC into an M4B output while retaining tags. If the source directory contains `cover.jpg`, `cover.jpeg`, `cover.png` or `description.txt`, the documentation says those files can also be embedded. Missing artwork or a missing description does not cause the merge to fail.

The tool also handles the inverse operation. Its `split` command can divide a single M4B into chapter-based MP3 files, retaining tags and creating a `cover.jpg` for the split directory when the M4B contains artwork. The documentation also mentions splitting a FLAC-encoded album into tracks through a cue sheet. This makes m4b-tool relevant to people converting personal audiobook rips, normalizing a series, or distributing books with navigational metadata, rather than merely transcoding one isolated sound file.

Chapter handling is a separate concern. Existing chapters can be adjusted through silence detection, chapters can be created from tagged input tracks, fixed chapter boundaries can be supplied in `chapters.txt`, and the `--max-chapter-length` option can subdivide chapters that would otherwise be too long. Its intended users therefore need both media operations and metadata control. Someone who only wants a basic audio converter will encounter more orchestration than necessary.

## Inside m4b-tool's ffmpeg and mp4v2 pipeline

The README calls m4b-tool a wrapper rather than a standalone codec implementation. Its media path depends on external programs: ffmpeg performs the audio work, while mp4v2 supplies the MP4-oriented tooling used for M4B output. The container definition reinforces this design. It copies `ff*` executables from `sandreas/ffmpeg:5.0.1-3`, `mp4*` executables and `libmp4v2*` libraries from `sandreas/mp4v2:2.1.1`, and `fdkaac` from `sandreas/fdkaac:2.0.1`.

The project itself is written in PHP, and the container installs a specific runtime set rather than only a standalone executable. Those packages include `php83-cli`, `php83-curl`, `php83-dom`, `php83-xml`, `php83-mbstring`, `php83-openssl`, `php83-phar`, `php83-simplexml`, `php83-tokenizer`, `php83-xmlwriter` and `php83-zip`. This dependency surface explains the README's warning that installation is not always a one-line operation when full tagging and encoding support is wanted.

Metadata travels alongside the audio. Chapter titles can be derived from input track `title` tags, explicit timestamps can come from `chapters.txt`, and existing chapter boundaries can be reconsidered using detected silence. The repository also includes a separate C# tool named `tone` in the Docker image. The README positions `tone` as an early alpha alternative for features that may have limitations in m4b-tool, rather than as proof that the PHP implementation has been replaced.

## Nix installation and a first merge

The documented installation path uses Nix with Flakes enabled. For a first real use, run the project directly from GitHub and confirm that the selected variant starts without missing executables. The default variant is the shorter build path; the `m4b-tool-libfdk` variant builds ffmpeg with `libfdk_aac`, which the README says will take longer.

Run m4b-tool directly through Nix:

```bash
nix run github:sandreas/m4b-tool
```

The command should expose the CLI without requiring a separate repository checkout. If the required AAC build capability matters, use this variant instead:

```bash
nix run github:sandreas/m4b-tool#m4b-tool-libfdk
```

For a reusable build, the README identifies the generated wrapper as `./result/bin/m4b-tool`:

```bash
nix build github:sandreas/m4b-tool
```

A practical first task is merging a prepared directory. Put the audio files in `data/my-audio-book`, optionally add recognized artwork and `description.txt`, then run:

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

The expected result is `data/merged.m4b`, with source tags retained and any recognized cover and description embedded. The README recommends organizing material by genre, author, series and part before merging. It also notes that a title containing an invalid path character such as `/` should use a dash in the directory name. This preparation does not itself change the command, but it avoids ambiguity in larger collections.

## Splitting M4B chapters into MP3 files

A reverse workflow is useful when a chaptered M4B must become smaller MP3 files. The documented split example sets the output codec, bitrate, channel count and sample rate, then supplies the source M4B. The output is written into `data/my-audio-book_splitted/`.

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

The choice in this example is deliberately modest: 96k bitrate, one channel and a 22050 sample rate. Those are explicit command options, not a claim about the appropriate quality for every audiobook. The tool retains tags according to the README, and it creates `data/my-audio-book_splitted/cover.jpg` when the M4B contains a cover.

This operation depends on the M4B already having useful chapter boundaries. If chapter markers are missing or misplaced, splitting alone cannot produce the intended chapter mapping. The next command adjusts existing chapters by looking for silence. Its input is the original M4B and its output is a separate destination:

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

That separation is useful because it preserves the source file. It does not mean silence detection will always infer literary chapter titles. The documented result is adjusted timing; meaningful chapter names still depend on existing metadata, explicit files, or another documented source such as MusicBrainz.

## Chapter metadata options and their limits

m4b-tool offers several ways to define chapter boundaries, but each has a different prerequisite. Tagged input files can produce chapter metadata from each file's `title`, which is convenient when every source track already represents a meaningful chapter. For manual control, `chapters.txt` places a timestamp and title on each line. The README gives entries in `HH:MM:SS.mmm Title` form, such as an Intro at the beginning and subsequent titled waypoints.

The `chapters.txt` file must be located alongside `cover.jpg` in the audiobook's main directory. The documentation treats it as optional, as it does the cover and description. For long input segments, `--max-chapter-length` adds sub-chapters automatically. This addresses a navigation problem, not a content-detection problem: dividing a long file into shorter intervals makes chapter stepping more convenient, but it cannot determine that a new literary chapter begins without a signal such as metadata, silence detection or an external source.

Silence detection can adjust boundaries on an existing M4B, while MusicBrainz is listed as another way to add or adjust chapters. The README does not provide a complete command reference for MusicBrainz matching, authentication, edition selection, or conflict handling. It also does not document rollback for a chapter-editing operation. The safe operational distinction is clear from the documented output option: the silence command writes to a named destination file rather than modifying the named source in place.

## Dependencies, release status and upgrade cost

The maintenance picture is mixed. The repository is not archived, and its last push was on 2026-04-18. The listed releases are `v0.5.2` from 2025-02-13, `v0.5.1` from 2025-01-14 and `v0.5.0` from 2025-01-03. That release history postdates the README section warning that version 0.4.2 was old and that only a latest pre-release was receiving bug fixes.

The README is therefore not a complete account of current releases. Its version warning describes an earlier situation and should not be used to conclude that the listed `v0.5.x` releases do not exist. An evaluator needs to distinguish the documented advice about the old `0.4.2` line from the release list. It would also be wrong to claim an active maintenance policy from push activity alone. The confirmed fact is the last push date, not a promise of future releases or compatibility.

Upgrades carry a dependency cost because m4b-tool coordinates PHP, ffmpeg, mp4v2 and optional or companion media tooling. The Docker definition pins its own base images, including ffmpeg 5.0.1-3, mp4v2 2.1.1 and fdkaac 2.0.1, while the application archive is downloaded from the latest release URL by default. Changing one component may therefore require rebuilding the surrounding environment rather than replacing a self-contained binary.

The project uses the MIT license. That permits use and modification under the license's conditions, but operators still need to account for the licenses of ffmpeg, mp4v2, fdkaac and other packages in their own distribution. The repository documents no separate support commitment, compatibility matrix, or migration procedure for each release.

## Where m4b-tool is the wrong choice

The clearest alternative named by the project is `tone`, a fully open source C# command line tool that the README describes as an early alpha experiment. Its purpose overlaps with m4b-tool in audio processing, but its implementation and stated feature set differ. The README says it can be tried for features that may have limitations in m4b-tool, while also stating that m4b-tool development would continue until tone reached a comparable feature set. That makes tone an alternative to evaluate, not a documented drop-in replacement.

m4b-tool is also the wrong choice for a minimal local installation if the user expects one binary with no surrounding runtime. Its PHP CLI requirements and media dependencies make container or Nix packaging more predictable than an unsupported manual assembly. On Windows, the README specifically warns that making the full dependency setup work may be difficult.

The Docker image deserves scrutiny before adoption. It installs the m4b-tool archive at `/usr/local/bin/m4b-tool`, copies ffmpeg and mp4v2 executables, and also includes `tone` at `/usr/local/bin/tone`. It sets `WORKDIR` to `/mnt/` and `M4BTOOL_TMP_DIR` to `/tmp/m4b-tool/`, then declares `CMD ["list"]` with `m4b-tool` as the entrypoint. The development Compose file instead builds `Dockerfile.dev` and mounts the repository at `/m4b-tool`. These are different operational shapes, so a container user should verify which image and working directory are actually being used before running a merge.

## Conclusion

Adopt m4b-tool when you need repeatable command line workflows that preserve tags, cover art, descriptions and chapter metadata across common audiobook formats. Do not choose it when you need a minimal binary with no PHP, ffmpeg or mp4v2 dependency burden, or when you need coverage not confirmed by the documentation. Verify executable discovery first, then confirm that your chosen Nix package or container exposes ffmpeg, mp4v2, tone and the required PHP extensions before processing valuable source files.

## FAQ

### How do I install m4b-tool with Nix?

Enable Nix Flakes, then run `nix run github:sandreas/m4b-tool` for direct execution. The README also documents a `m4b-tool-libfdk` variant that builds ffmpeg with `libfdk_aac`, which takes longer.

### How do I merge several audiobook files into one M4B?

Place the files in one directory and run `m4b-tool merge "data/my-audio-book/" --output-file="data/merged.m4b"`. Tags are retained, and recognized cover and description files are embedded when available.

### Can m4b-tool split an M4B by chapters?

Yes. The README gives a `split` example with `--audio-format mp3`, bitrate, channel and sample-rate options. The command creates chapter-based MP3 outputs and retains tags, with artwork copied when the source contains a cover.

## Sources

- [Issues](https://github.com/sandreas/m4b-tool/issues)
- [License: MIT](https://github.com/sandreas/m4b-tool/blob/master/LICENSE)
- [README](https://github.com/sandreas/m4b-tool/blob/master/README.md)
- [Releases](https://github.com/sandreas/m4b-tool/releases)
- [sandreas/m4b-tool on GitHub](https://github.com/sandreas/m4b-tool)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sandreas-m4b-tool