TTS Dialogue Generator (Offline)

This is a local, offline text-to-speech tool for generating multiple-voice dialogues from text files, designed for classroom use (e.g., English role-playing for children).
It uses Piper TTS for offline neural voices and outputs both per-line WAVs and a merged MP3 for each lesson.

Features

• Multiple voices per dialogue (map speakers to voices in voices.yaml)
• Automatic processing of all dialogues in the dialogues/ folder
• Generates per-line WAV files and a merged MP3
• Customizable pause duration between lines
• Flags for selective processing and overwriting existing files

Project Structure

dialogue-generator/
├── dialogues/ # Text files with dialogues (one per lesson)
├── voices/ # Pretrained Piper voice models (.onnx + .json). Feel free to add more as necessary.
├── voices.yaml # Map speakers to voices
├── output/ # Generated audio (per lesson)
├── generate.py # Main Python script
├── helpers.py # functions to assist the main script
├── requirements.txt # Python dependencies
└── README.md

Installation and usage

Clone the repo

git clone git@github.com:RomanLeca/dialogue_generator.git
cd dialogue-app

Create a Python virtual environment

python3 -m venv venv
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Install ffmpeg (required by pydub)

macOS:

brew install ffmpeg

Ubuntu / Debian

sudo apt install ffmpeg

Setting up voices

• Download pretrained Piper voices from rhasspy/piper-voices.
• Place .onnx and .json files in the voices/ folder.
• Map each speaker in voices.yaml

Preparing dialogues

• Create .txt files in the dialogues/ folder. Filenames in dialogues/ should avoid spaces or special characters; only letters, numbers, and underscores _ are recommended.
• Format (colon : is mandatory.):

  Speaker1: Hello, how are you?
  Speaker2: I’m fine, thanks!
  Speaker1: Let’s play together.
  

• One speaker per line
• Filename without extension becomes the lesson name (this is useful for CLI calls later)

Usage

python generate.py [OPTIONS]

Options

Flag	Description
--only LESSON_NAME	Process only the specified lesson (filename without .txt)
--overwrite	Overwrite all existing audio files
--skip-existing	Skip lessons that have already been generated (default)
--pause-ms N	Pause duration between lines in milliseconds (default 400)

Examples

Generate all lessons (skip existing)

python generate.py

Generate file only from the dialogue lesson.txt

python generate.py --only lesson_01

Force overwrite all outputs

python generate.py --overwrite

Set a longer pause (600ms)

python generate.py --pause-ms 600

macOS Web App (double-click usage)

This project can be run as a local web app for non-technical users.

One-time setup on a new laptop

• Install brew
• Install Python 3.11

  brew install python@3.11

• Install ffmpeg (required for audio processing):

  brew install ffmpeg

Running the app

Copy the project folder to laptop (without the venv). Double-click: Start.command

What happens:

• A local server starts automatically
• Your browser opens to: http://127.0.0.1:8000/
• You can paste a dialogue and export MP3 files.
• To stop the app close the Terminal window (or press Ctrl+C).

License

This project is licensed under the MIT License.
You are free to use, modify, and distribute this software for personal, educational, or classroom use.

Important Note on Voices

This project uses Piper TTS pretrained voices, which are provided under their own license.
Please refer to Piper Voices License for terms regarding voice models.

When sharing or distributing this project, please include this LICENSE section and the original copyright notice.