renatoxsr/m4b
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Atualizar README.md

Browse Source
This commit is contained in:
renatoxsr
2026-08-27 12:09:32 -03:00
parent fa73f423e8
commit b4bcbabeaa
1 changed files with 16 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+16 -144
View File
@@ -1,24 +1,9 @@
# MP3-to-M4B Converter
# m4binder
A Python CLI script that converts folder(s) of MP3 chapters into an M4B audiobook, optionally embedding chapter metadata and cover art. It can also fetch metadata from Open Library (e.g., title, author, cover). This script supports two modes:
A Python CLI script that converts EPUB files with audio content (media overlay) into a single M4B audiobook, optionally embedding chapter metadata and cover art. It can also fetch metadata from Open Library (e.g., title, author, cover).
1. **Single** – Convert all MP3 files in **one folder** into a single M4B.
2. **Multiple** – For each **subfolder** in the input folder, convert MP3 files within that subfolder into its own M4B.
Forked from [patricker/m4binder@6b3461a](https://github.com/RenatoXSR/m4binder/commit/6b3461a8b31880849d80fb7ad3565be3ca70c751) and relicensed to BSD-3-Clause-Clear.
---
## Table of Contents
- [MP3-to-M4B Converter](#mp3-to-m4b-converter)
- [Table of Contents](#table-of-contents)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Single Mode Example](#single-mode-example)
- [Multiple Mode Example](#multiple-mode-example)
- [Metadata Source](#metadata-source)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [License](#license)
---
@@ -27,139 +12,22 @@ A Python CLI script that converts folder(s) of MP3 chapters into an M4B audioboo
1. **FFmpeg**
You must have [FFmpeg](https://www.ffmpeg.org/download.html) installed and in your system’s PATH. This script relies on FFmpeg for audio processing (encoding, merging, adding metadata).
2. **Python 3.7+**
2. **Python 3.13+**
- If you don’t already have Python, install it from [python.org/download/releases/](https://www.python.org/download/releases/).
3. **Pip & Requirements**
The script has some Python dependencies, so you’ll want to install them from `requirements.txt`.
The script has some Python dependencies (namely, mutagen).
---
## Installation
1. **Install FFmpeg**
Follow the [official FFmpeg download guide](https://www.ffmpeg.org/download.html) for your operating system (Windows, macOS, Linux).
- Once installed, confirm `ffmpeg` is accessible by running:
```bash
ffmpeg -version
```
- If FFmpeg is not found, ensure your environment variables are set so that the `ffmpeg` command is recognized.
2. **Install Python 3.7+**
- If you need Python, go to [python.org/download/releases/](https://www.python.org/download/releases/) and download/install the latest version.
3. **Clone or Download This Repository**
- If you have Git:
```bash
git clone https://github.com/your_username/mp3-to-m4b-converter.git
```
- Or simply download the ZIP and extract.
4. **Install Python Dependencies**
In the project directory, run:
```bash
pip install -r requirements.txt
```
---
## Usage
Run the script directly from your terminal using Python:
```bash
python m4binder.py [OPTIONS]
```sh
pip install -e .
python -m m4binder --help
```
Key arguments:
| Argument | Description |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--mode` | **single** (default) or **multiple**. In single mode, converts all MP3s in one folder into **one** M4B. In multiple mode, each subfolder is treated as a separate book. |
| `--input-folder` | The folder containing MP3 files (in **single** mode) or subfolders containing MP3 files (in **multiple** mode). |
| `--output-file` | **(Single mode)** The M4B filename to create. Required in single mode. |
| `--output-folder` | **(Multiple mode)** Where to place all final M4B files. If not specified, defaults to placing them in the same `--input-folder`. |
| `--metadata-source` | Source to fetch book metadata: **`openlibrary`** or **`none`**. |
| `--title` / `--author` | Used for metadata lookup if you choose `--metadata-source openlibrary`. If not provided, the script attempts to read ID3 tags from the first MP3 file. |
### Single Mode Example
You have a folder containing MP3 files for “My Book.” Run:
```bash
python m4binder.py \
--mode single \
--input-folder /path/to/mybook_mp3s \
--output-file /path/to/output/mybook.m4b \
--metadata-source openlibrary \
--title "My Book Title" \
--author "John Doe"
```
- **`--mode single`** indicates we’re converting one folder of MP3s into one M4B.
- **`--title`** and **`--author`** (optional) help fetch metadata, including cover art, from Open Library.
### Multiple Mode Example
You have a folder containing multiple subfolders, each with its own set of MP3 files. For example:
```
/path/to/audiobooks/
├── Book1/
│ ├── 01.mp3
│ ├── 02.mp3
│ └── ...
├── Book2/
│ ├── 01.mp3
│ ├── 02.mp3
│ └── ...
└── Book3/
├── 01.mp3
├── 02.mp3
└── ...
```
To convert **each** of these subfolders into a separate `.m4b`, run:
```bash
python m4binder.py \
--mode multiple \
--input-folder /path/to/audiobooks \
--output-folder /path/to/converted_audiobooks \
--metadata-source openlibrary
```
- Each subfolder (Book1, Book2, Book3) will be processed into its own `.m4b` in `/path/to/converted_audiobooks`.
---
## Metadata Source
- **`openlibrary`**: Attempts to fetch official metadata (title, authors, cover art, etc.) from Open Library.
- **`none`**: Skips online metadata. The script will attempt to read embedded ID3 tags (like cover art) from the first MP3 file in each set. If no tags are found, it’ll default to generic placeholders.
> **Note**: If you omit `--title` and/or `--author`, the script will try to read those values from the **first MP3** file’s ID3 tags.
---
## Examples
1. **Quick Single-Folder Conversion Without Metadata**
```bash
python m4binder.py \
--mode single \
--metadata-source none \
--input-folder /path/to/book_mp3s \
--output-file /path/to/output/book.m4b
```
2. **Multiple-Folder Conversion with OpenLibrary**
```bash
python m4binder.py \
--mode multiple \
--input-folder /path/to/audiobooks \
--output-folder /path/to/final_m4bs \
--metadata-source openlibrary
```
If `--title` and `--author` are the same for all subfolders, the script will attempt to find metadata for each subfolder. If subfolders differ significantly, you may rely on each MP3’s ID3 tags or let Open Library do partial matching.
---
@@ -168,17 +36,21 @@ python m4binder.py \
1. **FFmpeg Not Found**
- Ensure `ffmpeg` is installed and on your system’s PATH. You can verify by running `ffmpeg -version`.
2. **No MP3 Files Detected**
- Double-check your input folder paths. Make sure files actually have the `.mp3` extension.
2. **No Audio Files Detected**
- Double-check your input folder paths. Make sure files actually have a supported extension.
3. **Metadata Not Found / Covers Missing**
- Open Library may not have an entry for your exact title/author. Ensure you’ve spelled them correctly, or use `--metadata-source none` to rely on embedded cover art.
4. **High CPU Usage**
- By default, the script parallelizes conversion of MP3 files (for faster performance).
- By default, the script parallelizes conversion of audio files (for faster performance).
---
## License
This project is provided under the [MIT License](./LICENSE) (or whichever license you apply). Feel free to modify and distribute it according to your needs.
Current: See [LICENSE](./LICENSE)
Previouse license:
"This project is provided under the [MIT License](./LICENSE) (or whichever license you apply). Feel free to modify and distribute it according to your needs."
See: [README.md](https://github.com/patricker/m4binder/tree/6b3461a8b31880849d80fb7ad3565be3ca70c751)