Qwen3-Audiobook-Converter: batch turning ebooks into narrated mp3 files

The converter is a client for a local Qwen Gradio server

The architecture is simple enough to state in one line: this repository is not the speech model. It is a Python client that talks to a Qwen3 TTS instance you run yourself, over the Gradio API.

The dependency list shows how that works. gradio_client at 0.7.0 or later is the transport, and requests at 2.28.0 or later is the HTTP layer underneath it. The README's first prerequisite is a Qwen Voice Model running locally, obtained by downloading and running the Qwen3 TTS Gradio interface, with a one click install through Pinokio, and the server is expected to be reachable at http://127.0.0.1:7860. Step four of the setup is simply to run the Gradio interface and verify that address answers.

That boundary has consequences for evaluation. The quality of the narration is a property of the Qwen model you point it at, not of this script, and the script is responsible for the parts around it: getting text out of a file, deciding how much to send at a time, stitching audio together, remembering what has already been synthesised and cleaning up after itself.

The model side is fixed in one respect. The README states the converter always uses the 1.7B model, described as the highest quality model for best results, listed in the hardcoded settings as always the highest quality. There is no smaller model option in the settings table, so a machine that cannot hold the 1.7B model has no fallback path through this tool.

The system requirements are modest for a local inference box: Python 3.8 or higher, FFmpeg for audio processing, 4GB of RAM recommended, and roughly 100MB of storage per hour of audiobook.

Books go into a folder and mp3 files come out of another

The project layout is the user interface. The README documents the folders explicitly, and the same structure appears in the repository root.

The input folder is book_to_convert/, where you place the books. The output folder is audiobooks/, where the finished files are written with the source name preserved, so my_book.pdf becomes audiobooks/my_book.mp3. Between them sit chunks/, described as temporary processing files that are auto-cleaned, and cache/ with an audio_chunks/ subdirectory holding cached audio chunks, plus logs/ where a processing log is written as audiobook_YYYYMMDD.log.

The conversion is a batch operation over the whole input folder, which the README shows by copying several files in and running the converter once:

# Add multiple books
cp *.pdf book_to_convert/
cp *.epub book_to_convert/

# Convert all at once
python audiobook_converter.py

Running it with no arguments uses the default custom voice mode with the Ryan speaker and English, and the script is the entry point: audiobook_converter.py at the repository root, with a config.py beside it holding the settings.

The output is a single mp3 per book rather than a chaptered format, and there is no documentation of a manifest, a metadata file, or per-chapter splitting. For a long book that means one large file, assembled from chunks that were synthesised separately and then joined with pydub and FFmpeg.

Twelve hundred words per chunk, one worker, and a cache you can resume from

The processing settings table is where the engineering decisions are, and the values are conservative.

CHUNK_SIZE_WORDS is 1200, so text is split into chunks of about twelve hundred words with sentence boundary detection, which the feature list calls smart chunking. MAX_WORKERS is 1, and the description in the table is the interesting part: concurrent chunks, keep at 1 to avoid rate limiting. So the conversion is sequential by design. That is a deliberate trade, respecting a rate limit on the model server at the cost of throughput, and it means a book of several hundred thousand words is a long job.

MAX_RETRIES is 3, tied to the feature list entry for error handling, described as automatic retries and graceful failure recovery. A chunk that fails is retried rather than aborting the run, and the auto cleanup feature removes temporary files even on failure, so a crash does not leave the chunks/ directory littered.

The cache is the second of these mechanisms. Cached audio chunks live in cache/audio_chunks/, and the feature list calls this intelligent caching that avoids re-processing identical chunks. In practice this is what makes the tool survivable across a long book, because a rerun after a failure reuses the chunks that already succeeded.

The audio output is mp3 at a 128k bitrate, set through AUDIO_FORMAT and AUDIO_BITRATE. That is a modest bitrate for spoken word, and it is a large part of why the storage estimate is around 100MB per hour of audiobook. Progress is reported in real time with time estimates, which matters given the sequential worker and the long runtimes.

The one caveat is that the cache stores audio for identical chunks, and the README does not document how cache entries are invalidated. If you change the voice or the model settings in code, clear the cache/ directory before rerunning, otherwise you may hear the previous voice.

Voice cloning needs a WAV file and does the transcription for you

The second mode is voice cloning, and it is reached with two flags:

python audiobook_converter.py --voice-clone --voice-sample path/to/reference.wav

The reference audio is a WAV file, and the README is explicit that the audio is transcribed automatically so you do not need to provide the text, using Qwen's Whisper model. That is what makes the feature usable: you hand over a recording of a voice and the model works out the words, so a clip of someone speaking is enough input.

The quality note in the README is that higher quality reference audio gives better cloning results. There is no documented guidance on how long the reference should be, which sample rate it needs, or whether background noise is tolerated, and the transcription step is a separate model running inside the same server.

The alternative to this mode is the built-in speaker list. The README names nine pre-built speakers with short descriptions, and Ryan, described as a male, clear and professional narrator, is the default. The others are Serena, Aiden, Dylan, Eric, Ono_anna, Sohee, Uncle_fu and Vivian, each with a one line description of accent or tone, and the README notes they can be changed in code.

That last phrase is the important one for anyone planning to use this seriously. The speaker list is not exposed on the command line, the language is fixed at English in the hardcoded settings, and the model size is always 1.7B. Changing any of it means editing config.py and the script, so treat this as a script to adapt rather than a tool to configure.

Text extraction depends on a different library per format

Five input formats are supported and each pulls in a different extraction library, which is where the real fragility of a converter like this lives.

Plain text is the trivial case. PDF is handled with PyPDF2 at 3.0.0 or later, EPUB with ebooklib at 0.18 or later. Word documents come in two flavours, and the README is honest that they need different tools: .docx requires python-docx at 0.8.11 or later and .doc requires docx2txt at 0.8 or later. beautifulsoup4 at 4.11.0 or later is also on the list, which points at HTML content inside EPUB files.

All of these are optional in the strict sense that the requirements file groups python-docx, docx2txt and beautifulsoup4 under a comment marking them as optional dependencies for additional format support, while gradio_client, requests, PyPDF2, ebooklib and pydub sit in the core block.

Audio assembly is pydub, and the requirements file carries a note that ffmpeg is required for pydub audio processing and should be installed separately from ffmpeg.org. That dependency is easy to miss because pip will happily install pydub without it, and the failure appears later, in the audio step rather than at import time.

What the documentation does not cover is the quality of the extraction itself. A PDF that is a scan of images, a document with a table of contents that you want honoured, or a file with a non-standard column layout will all produce text of varying quality, and the README does not describe any post-extraction cleanup, chapter detection, or table of contents handling. The chunking is aware of sentence boundaries, but sentence boundaries are the end of the story as far as structure goes.

Setting it up takes a local model, pip and ffmpeg

The quick start is a fixed sequence, and the order matters because the first step is outside this repository.

You need the Qwen Voice Model running locally first, with the Gradio interface available at http://127.0.0.1:7860. Then clone and install:

git clone https://github.com/WhiskeyCoder/Qwen3-Audiobook-Converter.git
cd Qwen3-Audiobook-Converter

pip install -r requirements.txt

FFmpeg comes next, and the README gives one command per platform:

choco install ffmpeg

sudo apt-get install ffmpeg

brew install ffmpeg

With the model server up and ffmpeg present, you drop a book into the input folder:

# Place your books in the book_to_convert folder
cp your_book.pdf book_to_convert/

and run the converter:

# Default: Custom Voice mode (Ryan speaker, English)
python audiobook_converter.py

The repository also ships a QUICKSTART.md next to the README, and a sample/ directory with a test mp3 and a matching text file, so you can hear the expected output format before committing a full book to the pipeline. The audio is a raw mp3 file rather than an embedded player, and the README explains that GitHub cannot embed audio in a readme, which is a small illustration of how little the project assumes about a preview.

MIT licensed, no releases, and a last push in April

The licence is MIT, stated in the README badge and in the LICENSE file at the repository root, with the project structure listing the same file. The repository root holds the LICENSE, QUICKSTART.md, README.md, audiobook_converter.py, the audiobooks/, book_to_convert/ and sample/ directories, config.py and requirements.txt. There is no test directory, no CI configuration in the listing and no packaging metadata, so the project is a script repository rather than an installable package.

That also means no version to pin. The repository publishes no GitHub releases, and the README carries no version badge for the converter itself. The maintenance record is a single fact: the last push was on 2026-04-07, more than six months before this review, and the repository is not archived. The project is a script sitting on a fixed set of assumptions about a Qwen server, a 1.7B model and a Gradio API, and it is worth checking the README against the current Qwen3-TTS interface before relying on it.

Two things to weigh before adopting. The first is the hardcoded configuration, which is a genuine friction point for anything beyond a one-off personal use, since the speaker, the language, the model size, the input folder and the output folder all live in code rather than in arguments. The second is the sequential worker, which caps throughput at one chunk in flight to avoid rate limiting the local server.

Against that, the tool does something the alternative does not do for you. Driving the Gradio interface by hand means converting chunk by chunk, with no cache to resume from, no retry policy, no cleanup of partial files and no batching across books. The script is thin, but it is thin in the direction of the tedious parts, and every part of it that is not the model server is the part you would otherwise have to write.

Editorial conclusion

Adopt Qwen3-Audiobook-Converter if you already run the Qwen3 TTS Gradio interface locally, you want whole books turned into narrated audio without a hosted service, and you are prepared to edit the script when you want a different speaker, language or model size, because the configuration is hardcoded in config.py. Do not adopt it if you need a supported command line interface, parallel conversion, or a versioned release you can pin, since the repository publishes no GitHub releases and the last push was on 2026-04-07. Before using it on a long book, copy the book into book_to_convert/, confirm the model server answers at http://127.0.0.1:7860, and check the audiobooks/ output and the cache/ directory for leftovers from a previous run.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. WhiskeyCoder/Qwen3-Audiobook-Converter on GitHub