readme

1 files changed, 29 insertions, 42 deletions

diff --git a/README.md b/README.md
index a5775af..63e78db 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 Convert TXT, PDF, and EPUB files into audiobooks using the Qwen3-TTS voice model.
 
-This builds upon [WhiskeyCoder/Qwen3-Audiobook-Converter](https://github.com/WhiskeyCoder/Qwen3-Audiobook-Converter) adding more output files, metadata, generated cover art, transcription/speed options, better text cleanup, and clearer instructions. It also expects the qwen-tts server to be on different ports per model, so two server processes can run at once.
+This builds upon [WhiskeyCoder/Qwen3-Audiobook-Converter](https://github.com/WhiskeyCoder/Qwen3-Audiobook-Converter) adding more output files, metadata, generated cover art, transcription/speed/language options, better text cleanup, and clearer instructions. It also expects the qwen-tts server to be on different ports per model, so two server processes can run at once.
 
 ## Overview
 
@@ -24,7 +24,7 @@ The converter sends text extracted from your books to a locally running Qwen3-TT
 
 ## Installation
 
-Install ffmpeg and conda, e.g.
+Install ffmpeg and your python environment of choice, e.g. conda.
 
 ```bash
 sudo pacman -S conda ffmpeg   #Arch Linux
@@ -49,14 +49,9 @@ pip install -r requirements.txt
 
 ## Running the Qwen-TTS server
 
-The converter script talks to a Qwen3-TTS Gradio server that is run using `qwen-tts-demo`. Add `--no-flash-attn` if FlashAttention isn't installed (see below). The script expects the custom voice model and base model to be on different ports depending on which you're using. The model(s) will automatically download.
+The converter script talks to a Qwen3-TTS Gradio server that is run using `qwen-tts-demo`. Add `--no-flash-attn` if FlashAttention isn't installed (see below). The script expects the custom voice model and base model to be on different ports depending on which you're using. The Qwen model(s) will automatically download.
 
-### Custom voice
-
-```bash
-conda activate qwen3-tts
-qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 127.0.0.1 --port 7860
-```
+Put your book files (epub, etc.) in the `input/` folder. Then run the script. The output goes to `output/`.
 
 ### Voice clone
 
@@ -65,53 +60,43 @@ conda activate qwen3-tts
 qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-Base --ip 127.0.0.1 --port 7861
 ```
 
-## Converting books
-
-Put your book files (epub, etc.) in the `input/` folder. Then run the script. The output goes to `output/`.
-
-### Custom voice
+Then in another terminal:
 
 ```bash
-python audiobook.py
+python audiobook.py --clone reference.wav
 ```
 
-Edit `converter/config.py` to change which built-in voice is used.
+The reference `.wav` should be ~10-15 seconds (3 second minimum, 60 second maximum; ~15 seconds is ideal). Longer is **not** better.
 
-```
-CUSTOM_VOICE_SPEAKER = "Vivian"   # Serena, Vivian, Uncle_Fu, Aiden, Ono_Anna, Sohee, Eric, Dylan
-CUSTOM_VOICE_LANGUAGE = "English"
-CUSTOM_VOICE_INSTRUCT = "Speak naturally and clearly, as if reading a dramatic book to an adult audience."
-```
+Whisper (`faster_whisper` or `whisper`) is used automatically to transcribe the reference audio. Without a Whisper backend it falls back to x-vector-only cloning. Override with `--transcription "What the .wav says"` or skip transcription with `--no-transcription`.
 
-### Voice clone
+
+### Custom voice (i.e. built-in voice)
 
 ```bash
-python audiobook.py --clone path/to/reference.wav
+conda activate qwen3-tts
+qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 127.0.0.1 --port 7860
 ```
 
-The reference `.wav` should be ~10-15 seconds (3 second minimum, 60 second maximum; ~15 seconds is ideal). Longer is **not** better.
+```bash
+python audiobook.py
+```
 
-Whisper (`faster_whisper` or `whisper`) is used automatically to transcribe the reference audio. Without a Whisper backend it falls back to x-vector-only cloning. Override with `--transcription "..."` or skip transcription with `--no-transcription`.
+Edit `converter/config.py` to change which built-in voice is used.
 
 ## Options
 
-| Flag                          | Description                                                                                |
-| ----------------------------- | ------------------------------------------------------------------------------------------ |
-| `--clone <path>`              | Reference audio (WAV) for voice cloning. Passing this flag switches to voice clone mode.   |
-| `--transcription "..."`       | Override whisper auto-transcription with your own manual reference audio transcript.       |
-| `--no-transcription`          | Skip auto-transcription of the reference audio.                                            |
-| `--speed <n>`                 | Playback speed, pitch-preserving (`1.0` = normal). A normal-speed copy is also output.     |
-| `--format {mp3,m4b,ogg,flac}` | Output format (default `m4b`). `m4b` uses AAC audio and has built-in chapters.             |
-| `--single-file`               | Not m4b: Merge all chapters into a single file (default: one file per chapter).            |
-| `--language <lang>`           | Output language for the synthesized speech. Can add an accent even if the text is English. |
+| Flag                          | Description                                                                                      |
+| ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `--format {mp3,m4b,ogg,flac}` | Output format (default `m4b`). `m4b` uses AAC audio and has built-in chapters.                   |
+| `--clone <path>`              | Reference audio (`wav`) for voice cloning.                                                       |
+| `--transcription "..."`       | Override whisper auto-transcription with manual audio transcript.                                |
+| `--no-transcription`          | Skip auto-transcription of the reference audio.                                                  |
+| `--speed <n>`                 | Playback speed, pitch-preserving (`1.0` = normal). A normal-speed copy is also output.           |
+| `--single-file`               | Merge all chapters into a single file (default: one file per chapter). `m4b` is always one file. |
+| `--language <lang>`           | Output language for the synthesized speech. Can add an accent even if the text is English.       |
 
-## Running tests
-
-```bash
-python -m unittest discover -s tests -t .
-```
-
-## FlashAttention (optional)
+## FlashAttention for qwen-tts-demo server (optional)
 
 The server tries to use FlashAttention 2 by default, but `--no-flash-attn` works without it. On supported GPUs FlashAttention can give a modest speedup.
 
@@ -135,12 +120,14 @@ Third-party wheels: https://mjunya.com/flash-attention-prebuild-wheels/ (hosted
 
 ## Tips
 
-Transcription affects the output a lot. Whisper is okay, but does not give perfect transcription. A manual transcription passed `--transcription` is usually better.
+Transcription affects the output a lot. Whisper is okay, but does not give perfect transcription. A manual transcription passed via `--transcription` is usually better.
 
 Manual transcription, imperfect whisper transcription, and `--no-transcription` each provide different results. Usually the most accurate transcription is the best, but sometimes `--no-transcription` can produce a flat tone that might be preferable for certain voices.
 
 Setting `--language` to the "wrong" language for English text can produce an accent. It is not as strong as cloning a voice with the desired accent.
 
+The built-in "custom" voices are mediocre. I get *much* better results cloning anything.
+
 ## License
 
 MIT