From 124d7d110c29c5134b4814fcb88fd6f1ea4dc9ac Mon Sep 17 00:00:00 2001
From: LUIS NOVO <lfnovo@gmail.com>
Date: Sun, 14 Sep 2025 11:05:34 -0300
Subject: [PATCH] docs: TTS_BATCH_SIZE

---
 .env.example              |  6 ++++++
 docs/features/podcasts.md | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/.env.example b/.env.example
index 1b4b08a..eb4ceb1 100644
--- a/.env.example
+++ b/.env.example
@@ -42,6 +42,12 @@
 # Used only by the podcast feature
 # ELEVENLABS_API_KEY=
 
+# TTS BATCH SIZE
+# Controls concurrent TTS requests for podcast generation (default: 5)
+# Lower values reduce provider load but increase generation time
+# Recommended: OpenAI=5, ElevenLabs=2, Google=4, Custom=1
+# TTS_BATCH_SIZE=2
+
 # VOYAGE AI
 # VOYAGE_API_KEY=
 
diff --git a/docs/features/podcasts.md b/docs/features/podcasts.md
index aad3e5f..e0288da 100644
--- a/docs/features/podcasts.md
+++ b/docs/features/podcasts.md
@@ -197,11 +197,32 @@ Each speaker profile includes:
 - **Batch Processing**: Automated generation workflows
 
 ### Advanced Configurations
+
+#### **Performance Tuning**
 - **Segment Structure**: Custom conversation organization
 - **Timing Control**: Precise episode length management
 - **Topic Weighting**: Emphasis on specific content areas
 - **Personality Mixing**: Complex speaker interaction patterns
 
+#### **TTS Concurrency Control**
+Configure parallel audio generation to optimize performance and avoid provider rate limits:
+
+```bash
+# Environment variable configuration
+export TTS_BATCH_SIZE=3  # Number of concurrent TTS requests (default: 5)
+```
+
+**Recommended Settings by Provider:**
+- **OpenAI TTS**: `TTS_BATCH_SIZE=5` (default, handles high concurrency well)
+- **ElevenLabs**: `TTS_BATCH_SIZE=2` (strict rate limits, reduce for stability)
+- **Google TTS**: `TTS_BATCH_SIZE=4` (moderate concurrency tolerance)
+- **Custom/Local TTS**: `TTS_BATCH_SIZE=1` (depends on hardware/setup)
+
+**Performance Trade-offs:**
+- **Higher values (4-5)**: Faster podcast generation, higher provider load
+- **Lower values (1-2)**: Slower generation, more reliable for rate-limited providers
+- **Optimal setting**: Balance between speed and provider stability
+
 ## 🛠️ Troubleshooting Common Issues
 
 ### Generation Failures
@@ -215,6 +236,18 @@ Each speaker profile includes:
 - **Solution**: Check API quotas and upgrade plans if needed
 - **Prevention**: Monitor usage and set up billing alerts
 
+#### **TTS Concurrency Issues**
+- **Problem**: TTS provider rate limiting or concurrent request failures
+- **Solution**: Configure TTS batch size to reduce parallel audio generation
+- **Environment Variable**: `TTS_BATCH_SIZE=2` (default: 5)
+- **Usage**: Lower values reduce provider load but increase generation time
+```bash
+# Reduce concurrent TTS requests for providers with strict limits
+export TTS_BATCH_SIZE=2
+# or
+export TTS_BATCH_SIZE=1  # Most conservative, slowest
+```
+
 #### **Voice Configuration Errors**
 - **Problem**: Specific voice not available or misconfigured
 - **Solution**: Verify TTS provider settings and voice availability