# AIVA Demo Recording Pipeline
**Project**: ReceptionistAI Hero Video Voiceover
**Voice**: AIVA (Telnyx.NaturalHD.eucalyptus - Australian Female Premium HD)
**Target**: Website hero page video overlay audio
**Created**: 2026-02-15

---

## Executive Summary

Record AIVA reading the ReceptionistAI demo script (75 seconds) using Telnyx TTS API for overlay on website hero page video. Target: <500KB MP3, broadcast-quality audio optimized for web delivery.

---

## 1. Recording Method Analysis

### Option A: Telnyx TTS API (RECOMMENDED)
**Method**: POST text to Telnyx TTS endpoint, receive audio file
**Endpoint**: `https://api.telnyx.com/v2/text-to-speech`

**Pros**:
- ✅ Direct API access, fastest implementation
- ✅ No call minutes consumed
- ✅ High-quality audio output (22.05kHz default, up to 48kHz available)
- ✅ Full control over output format (MP3, WAV, OGG)
- ✅ Can adjust voice parameters (pitch, speed, pause duration)
- ✅ Repeatable with exact same quality

**Cons**:
- ❌ No real-time conversation dynamics (but not needed for pre-recorded script)

**Cost**: ~$0.06 per request (standard TTS pricing)

### Option B: Call Recording
**Method**: Dial AIVA's number, have her read script, record call
**Pros**: Natural conversation dynamics
**Cons**: Call quality dependent on network, harder to edit, consumes call minutes, less repeatable

### Option C: Streaming TTS
**Method**: Use Telnyx streaming endpoint for real-time generation
**Pros**: Can adjust on-the-fly
**Cons**: More complex integration, same quality as Option A

**DECISION**: Use Option A (Telnyx TTS API) for speed, quality, and repeatability.

---

## 2. Audio Format Optimization

### Target Constraints
- **Duration**: ~75 seconds
- **Target Size**: <500KB
- **Use Case**: Hero video overlay (autoplay, must load fast)
- **Quality**: Broadcast-quality speech (music quality not needed)

### Format Comparison

| Format | Codec | Bitrate | Size (75s) | Quality | Browser Support |
|--------|-------|---------|------------|---------|-----------------|
| **MP3** | MPEG-1 Layer 3 | 64 kbps | ~600KB | Good for speech | 100% |
| **MP3** | MPEG-1 Layer 3 | 48 kbps | ~450KB | Acceptable for speech | 100% |
| **WebM/Opus** | Opus | 32 kbps | ~300KB | Excellent for speech | 97%+ (not IE) |
| **AAC** | AAC-LC | 48 kbps | ~450KB | Very good | 98%+ |

### RECOMMENDATION: WebM/Opus (32 kbps) with MP3 (48 kbps) fallback

**Primary**: WebM/Opus at 32 kbps
- Modern codec optimized for speech
- ~300KB for 75 seconds
- Excellent quality at low bitrate
- Supported by Chrome, Firefox, Edge, Safari 14.1+

**Fallback**: MP3 at 48 kbps
- Universal compatibility
- ~450KB for 75 seconds
- Good speech quality
- Works everywhere including old browsers

**Implementation**:
```html
<audio>
  <source src="demo.opus" type="audio/webm; codecs=opus">
  <source src="demo.mp3" type="audio/mpeg">
</audio>
```

### Audio Specifications
- **Sample Rate**: 22.05kHz (ideal for speech, half of 44.1kHz)
- **Channels**: Mono (speech doesn't need stereo)
- **Bitrate**: 32 kbps (Opus) / 48 kbps (MP3)
- **Normalization**: -16 LUFS (web standard for voice)

---

## 3. Script Preparation

### Source Script
**File**: `/mnt/e/genesis-system/RECEPTIONISTAI/Receptionist AI Pre-Recording Demo Script.docx`

**Raw Text** (75 seconds):
```
Hello, I'm Maya from Receptionist AI, and I'm about to become your new receptionist. But here's something you should know upfront - I'm not a real person. I'm an AI voice agent, though I bet I sound pretty convincing, right?

Let me show you what I actually do. Every single day, I answer your business phones around the clock - morning calls, evening inquiries, even 3am emergencies. I never take a sick day, never go on holiday, and I'm never too busy to pick up.

When someone rings asking about your services, I've got the answers. Pricing questions? Handled. Booking an appointment? Done and confirmed. Want to know your opening hours or location? I've got it covered.

But here's where it gets interesting: after every conversation, I immediately text and email them a summary of what we discussed. Confirmation details, next steps, everything they need. No delays, no forgetting to follow up.

I can do something else that's pretty powerful - I'll work through your contact list and reconnect with people who showed interest months ago but never booked. Old quotes, abandoned inquiries, dead leads - I bring them back to life.

Want proof this works? I recently handled one business's phones for a day and secured 30 confirmed bookings before dinner time. Appointments they would've completely missed otherwise.

And it gets even better. I learn from every single interaction. Each conversation makes me smarter and more capable at understanding your customers and getting them to say yes.

Ready to see how I'd sound talking about YOUR specific business? Enter your website address below and I'll call you in the next 30 seconds with a personalized demonstration. You'll hear me discuss your actual services, your location, everything - like I'm already working for you.

Go ahead, enter your details. Let's see what I can do for your business.
```

### TTS Optimization

**Approach**: Telnyx TTS doesn't use SSML by default, but we can optimize text for natural pauses:

1. **Natural Pauses**: Use punctuation (commas, periods, question marks)
2. **Paragraph Breaks**: Use `\n\n` for longer pauses between sections
3. **Emphasis**: Capitalize key words (if voice supports)

**Cleaned Script** (same text, formatted for TTS):
```
Hello, I'm Maya from Receptionist AI, and I'm about to become your new receptionist. But here's something you should know upfront - I'm not a real person. I'm an AI voice agent, though I bet I sound pretty convincing, right?

Let me show you what I actually do. Every single day, I answer your business phones around the clock - morning calls, evening inquiries, even 3am emergencies. I never take a sick day, never go on holiday, and I'm never too busy to pick up.

When someone rings asking about your services, I've got the answers. Pricing questions? Handled. Booking an appointment? Done and confirmed. Want to know your opening hours or location? I've got it covered.

But here's where it gets interesting: after every conversation, I immediately text and email them a summary of what we discussed. Confirmation details, next steps, everything they need. No delays, no forgetting to follow up.

I can do something else that's pretty powerful - I'll work through your contact list and reconnect with people who showed interest months ago but never booked. Old quotes, abandoned inquiries, dead leads - I bring them back to life.

Want proof this works? I recently handled one business's phones for a day and secured 30 confirmed bookings before dinner time. Appointments they would've completely missed otherwise.

And it gets even better. I learn from every single interaction. Each conversation makes me smarter and more capable at understanding your customers and getting them to say yes.

Ready to see how I'd sound talking about YOUR specific business? Enter your website address below and I'll call you in the next 30 seconds with a personalized demonstration. You'll hear me discuss your actual services, your location, everything - like I'm already working for you.

Go ahead, enter your details. Let's see what I can do for your business.
```

**Segmentation**: Single continuous read (no segments needed - 75 seconds is within optimal range for single TTS call)

---

## 4. Recording Execution Plan

### Step 1: Telnyx TTS API Call
**Endpoint**: `POST https://api.telnyx.com/v2/text-to-speech`

**Headers**:
```json
{
  "Authorization": "Bearer KEY019BE7A3A2D749FCA8681CFF8448A7F0_vTMM1n77CtQxLDT2ra3P1z",
  "Content-Type": "application/json"
}
```

**Payload**:
```json
{
  "voice": "eucalyptus",
  "text": "[SCRIPT TEXT]",
  "audio_format": "wav",
  "sample_rate": 22050
}
```

**Response**: Binary audio data (WAV format, 22.05kHz)

### Step 2: Save Raw Audio
- Save response as `demo_raw.wav`
- Verify duration (~75 seconds)
- Check sample rate (22.05kHz)

### Step 3: Post-Processing (ffmpeg)

**Normalize Volume** (to -16 LUFS web standard):
```bash
ffmpeg -i demo_raw.wav -af loudnorm=I=-16:TP=-1.5:LRA=11 demo_normalized.wav
```

**Trim Silence** (remove leading/trailing silence):
```bash
ffmpeg -i demo_normalized.wav -af silenceremove=start_periods=1:start_silence=0.1:start_threshold=-50dB,areverse,silenceremove=start_periods=1:start_silence=0.1:start_threshold=-50dB,areverse demo_trimmed.wav
```

**Generate WebM/Opus** (primary format):
```bash
ffmpeg -i demo_trimmed.wav -c:a libopus -b:a 32k -vbr on -compression_level 10 demo.opus
```

**Generate MP3** (fallback):
```bash
ffmpeg -i demo_trimmed.wav -c:a libmp3lame -b:a 48k -ac 1 -ar 22050 demo.mp3
```

### Step 4: Verification
- ✅ Check file sizes (<500KB target)
- ✅ Listen to both formats for quality
- ✅ Verify duration matches expected (~75s)
- ✅ Test in multiple browsers

### Step 5: Deployment
- Upload `demo.opus` and `demo.mp3` to website assets
- Update hero video HTML with audio sources
- Test autoplay + user interaction scenarios

---

## 5. Python Execution Script

**Location**: `/mnt/e/genesis-system/RECEPTIONISTAI/scripts/record_demo.py`

**Features**:
- ✅ Reads demo script from docx file
- ✅ Calls Telnyx TTS API with eucalyptus voice
- ✅ Saves raw WAV file
- ✅ Post-processes with ffmpeg (normalize, trim, convert)
- ✅ Generates both WebM/Opus and MP3 outputs
- ✅ Verification checks on output files

**Usage**:
```bash
cd /mnt/e/genesis-system/RECEPTIONISTAI/scripts
python record_demo.py
```

**Output Files**:
```
/mnt/e/genesis-system/RECEPTIONISTAI/assets/audio/
├── demo_raw.wav          # Raw TTS output (22.05kHz WAV)
├── demo_normalized.wav   # Volume normalized
├── demo_trimmed.wav      # Silence removed
├── demo.opus             # Final WebM/Opus (32 kbps, ~300KB)
└── demo.mp3              # Final MP3 fallback (48 kbps, ~450KB)
```

---

## 6. Cost & Time Estimate

### API Costs
- **Telnyx TTS**: ~$0.06 per generation
- **Total**: <$1 for testing + final version

### Time Estimate
- **API Call**: ~5-10 seconds (depends on text length)
- **Post-Processing**: ~30 seconds (ffmpeg operations)
- **Total**: <1 minute end-to-end

### Resource Requirements
- Python 3.8+
- `python-docx` library
- `requests` library
- `ffmpeg` installed (for audio processing)

---

## 7. Alternative Approaches (Future Enhancements)

### Option 1: SSML Support (if available)
If Telnyx supports SSML in future:
- Add explicit `<break time="500ms"/>` for dramatic pauses
- Use `<emphasis>` tags for key phrases
- Add `<prosody rate="95%">` for slight slowdown on technical terms

### Option 2: Multi-Segment Recording
For longer scripts (>2 minutes):
- Break into logical segments
- Record each separately
- Stitch together with crossfades using ffmpeg

### Option 3: Voice Parameters
Test variations:
- **Pitch**: ±10% for A/B testing
- **Speed**: 90-110% for pacing tests
- **Volume**: Pre-normalization adjustments

---

## 8. Quality Checklist

Before deployment, verify:
- [ ] Audio is clear and intelligible
- [ ] No clipping or distortion
- [ ] Natural pacing (not too fast/slow)
- [ ] Consistent volume throughout
- [ ] No awkward pauses or cuts
- [ ] Opus file <350KB
- [ ] MP3 file <500KB
- [ ] Duration matches expected (~75 seconds)
- [ ] Tested in Chrome, Firefox, Safari, Edge
- [ ] Mobile playback verified (iOS + Android)

---

## 9. Rollout Plan

### Phase 1: Generate Audio (Today)
1. Run `record_demo.py`
2. Review output quality
3. Get Kinan approval on voice/pacing

### Phase 2: Website Integration (Next)
1. Upload audio files to website assets
2. Update hero video HTML
3. Test autoplay behavior (with mute fallback)
4. Verify mobile experience

### Phase 3: Optimization (Ongoing)
1. Monitor loading times (aim for <2s on 3G)
2. A/B test with/without audio
3. Track engagement metrics
4. Iterate on script based on conversion data

---

## 10. Risk Mitigation

### Risk: Audio doesn't sound natural
**Mitigation**: Generate multiple versions with slight variations, A/B test

### Risk: File size too large
**Mitigation**: Already using aggressive compression (32 kbps Opus), can reduce further to 24 kbps if needed

### Risk: Browser compatibility issues
**Mitigation**: MP3 fallback ensures 100% coverage

### Risk: Telnyx API limits
**Mitigation**: API key has no hard limits for TTS, rate limiting unlikely for single request

---

## Next Steps

1. **Execute** `record_demo.py` to generate audio files
2. **Review** output quality with Kinan
3. **Deploy** to ReceptionistAI website hero page
4. **Monitor** engagement and loading performance

---

**Status**: Ready for execution
**Owner**: Claude (orchestration) + Genesis Execution Layer
**Timeline**: <1 hour from approval to deployed audio

---

## Appendix A: Telnyx TTS API Reference

**Base URL**: `https://api.telnyx.com/v2/text-to-speech`
**Method**: POST
**Auth**: Bearer token in Authorization header

**Request Parameters**:
- `voice` (string, required): Voice identifier (e.g., "eucalyptus")
- `text` (string, required): Text to synthesize (max 5000 characters)
- `audio_format` (string, optional): "wav", "mp3", "ogg" (default: "wav")
- `sample_rate` (integer, optional): 8000, 16000, 22050, 24000, 48000 (default: 22050)

**Response**: Binary audio data with `Content-Type: audio/{format}`

**Rate Limits**: 100 requests/minute per API key

**Error Codes**:
- 400: Invalid parameters (check voice name, text length)
- 401: Invalid API key
- 429: Rate limit exceeded
- 500: Server error (retry with exponential backoff)

---

## Appendix B: ffmpeg Command Reference

**Install ffmpeg** (if not present):
```bash
# Ubuntu/WSL
sudo apt-get install ffmpeg

# macOS
brew install ffmpeg
```

**Check installed**:
```bash
ffmpeg -version
```

**Useful Commands**:
```bash
# Get audio info
ffprobe demo.wav

# Convert to MP3
ffmpeg -i input.wav -b:a 48k output.mp3

# Normalize volume
ffmpeg -i input.wav -af loudnorm=I=-16 output.wav

# Trim silence
ffmpeg -i input.wav -af silenceremove=start_threshold=-50dB output.wav

# Change speed (1.1 = 10% faster)
ffmpeg -i input.wav -af atempo=1.1 output.wav
```

---

**END OF PIPELINE DOCUMENT**
