feat: Add Piper TTS integration with pitch control support

- Created PiperTTSService with pitch shifting (-12 to +12 semitones) - Created UnifiedTTSService to manage multiple TTS engines - Added engine selection endpoints (GET/POST /api/tts/engines) - Added voices listing endpoint (GET /api/tts/voices) - Added pitch_adjustments parameter to TTS generation - Created install_piper.sh for easy Piper installation - Updated backend README with multi-engine documentation - Created comprehensive PIPER_TTS_GUIDE.md - Added TTS_ENGINE environment variable for engine selection - Updated requirements.txt with piper-tts and pydub This allows users to choose between Kokoro (high quality) and Piper (fast with pitch control) TTS engines at runtime.
2025-12-09 14:45:18 +00:00
parent b5c53604a6
commit bfdcc94b24
8 changed files with 1128 additions and 8 deletions
--- a/backend/README.md
+++ b/backend/README.md
@@ -13,6 +13,7 @@ The backend provides REST API endpoints for:

 - Python 3.10 or higher
 - espeak-ng (system dependency for grapheme-to-phoneme conversion)
+- Piper TTS (optional, for alternative TTS engine with pitch control)
 - Docker (optional, for containerized deployment)

 ## Local Development Setup
@@ -62,7 +63,33 @@ pip install --upgrade pip
 pip install -r requirements.txt
 ```

-### 3. Ollama Setup (Optional but Recommended)
+### 3. Piper TTS Setup (Optional)
+
+For an alternative TTS engine with pitch control support:
+
+**Installation:**
+```bash
+# Run the installation script
+./install_piper.sh
+```
+
+Or install manually:
+- Visit [Piper releases](https://github.com/rhasspy/piper/releases)
+- Download the appropriate binary for your platform
+- Extract and place in your PATH
+
+**Verify installation:**
+```bash
+piper --version
+```
+
+**Benefits of Piper TTS:**
+- ✨ Pitch shifting support (-12 to +12 semitones per role)
+- ✨ Fast, lightweight neural TTS
+- ✨ Multiple voice models available
+- ✨ Lower resource usage than Kokoro
+
+### 4. Ollama Setup (Optional but Recommended)

 For AI-powered speaker detection and text segmentation, install Ollama:

@@ -98,7 +125,7 @@ curl http://localhost:11434/api/tags
 - ✨ Handles narrative text without explicit role markers
 - ✨ Falls back to pattern matching if unavailable

-### 4. Environment Configuration
+### 5. Environment Configuration

 ```bash
 cp .env.example .env
@@ -109,9 +136,10 @@ Edit `.env` if needed:
 PORT=8000
 LOG_LEVEL=info
 OLLAMA_BASE_URL=http://localhost:11434  # Optional: Ollama API URL
+TTS_ENGINE=kokoro  # Options: kokoro, piper (default: kokoro)
 ```

-### 5. Run the Server
+### 6. Run the Server

 ```bash
 uvicorn main:app --reload --host 0.0.0.0 --port 8000
@@ -179,6 +207,43 @@ The Dockerfile includes:
 - Storage: ~500MB for Kokoro models
 - CPU: Multi-core recommended

+## TTS Engine Selection
+
+The backend now supports multiple TTS engines that can be selected at runtime:
+
+### Available Engines
+
+1. **Kokoro TTS** (default)
+   - High-quality neural TTS
+   - Multiple voices per language
+   - No pitch control
+   - ~500MB model size
+
+2. **Piper TTS**
+   - Fast, lightweight neural TTS
+   - Pitch shifting support (-12 to +12 semitones)
+   - Multiple voice models
+   - Lower resource usage
+
+### Switching Engines
+
+**Via Environment Variable:**
+```bash
+export TTS_ENGINE=piper  # or kokoro
+uvicorn main:app --reload
+```
+
+**Via API:**
+```bash
+# Get available engines
+curl http://localhost:8000/api/tts/engines
+
+# Set active engine
+curl -X POST http://localhost:8000/api/tts/engines \
+  -H "Content-Type: application/json" \
+  -d '{"engine": "piper"}'
+```
+
 ## API Endpoints

 ### GET /api/health
@@ -243,6 +308,71 @@ curl -X POST http://localhost:8000/api/tts/roles \
  -d '{"text":"Alice: Hello!\nBob: Hi there!"}'
 ```

+### GET /api/tts/engines
+
+Get list of available TTS engines and current selection.
+
+**Response:**
+```json
+{
+  "engines": [
+    {"name": "kokoro", "active": true},
+    {"name": "piper", "active": false}
+  ],
+  "current": "kokoro"
+}
+```
+
+**Example:**
+```bash
+curl http://localhost:8000/api/tts/engines
+```
+
+### POST /api/tts/engines
+
+Set the active TTS engine.
+
+**Request Body:**
+```json
+{
+  "engine": "piper"
+}
+```
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "engine": "piper"
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/api/tts/engines \
+  -H "Content-Type: application/json" \
+  -d '{"engine": "piper"}'
+```
+
+### GET /api/tts/voices
+
+Get available voices for all TTS engines.
+
+**Response:**
+```json
+{
+  "voices": {
+    "kokoro": ["af_bella", "af_sarah", "am_adam", "am_michael", ...],
+    "piper": ["en_US-lessac-medium", "en_US-amy-medium", ...]
+  }
+}
+```
+
+**Example:**
+```bash
+curl http://localhost:8000/api/tts/voices
+```
+
 ### POST /api/tts

 Generate multi-voice audiobook with AI-powered text segmentation.
@@ -271,6 +401,7 @@ When Ollama is available, the system uses AI to intelligently split text and ass
 - `lang` (required): Language code (a=American English, b=British English, f=French, j=Japanese)
 - `roles` (required): Array of role-to-voice mappings
 - `speed` (optional): Playback speed (0.5-1.5, default: 1.0)
+- `pitch_adjustments` (optional): Array of role-to-pitch mappings (Piper only, -12 to +12 semitones)

 **Response:**
 - Content-Type: `audio/wav`
@@ -285,7 +416,7 @@ When Ollama is available, the system uses AI to intelligently split text and ass
 - Content-Disposition: `attachment; filename="audiobook.wav"`
 - Body: Audio file bytes

-**Example:**
+**Example (Kokoro):**
 ```bash
 curl -X POST http://localhost:8000/api/tts \
  -H "Content-Type: application/json" \
@@ -301,6 +432,26 @@ curl -X POST http://localhost:8000/api/tts \
  --output audiobook.wav
 ```

+**Example (Piper with pitch control):**
+```bash
+curl -X POST http://localhost:8000/api/tts \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Alice: Hello!\nBob: Hi!",
+    "lang": "a",
+    "roles": [
+      {"id": "Alice", "voice": "en_US-amy-medium"},
+      {"id": "Bob", "voice": "en_US-lessac-medium"}
+    ],
+    "speed": 1.0,
+    "pitch_adjustments": [
+      {"id": "Alice", "pitch": 3},
+      {"id": "Bob", "pitch": -2}
+    ]
+  }' \
+  --output audiobook.wav
+```
+
 ## Kokoro TTS Configuration

 ### Supported Languages