# Voice Design Guide

This guide covers designing and configuring voices for meditation, spiritual content, and other audio experiences.

## Overview

Voice design involves defining:
- Voice characteristics (pitch, pace, timbre)
- Personality traits and speaking style
- Tradition-specific voice profiles
- Prosody and emotional expression
- Model and settings selection

## Voice Characteristics

### Core Parameters

```typescript
interface VoiceCharacteristics {
  gender: VoiceGender;      // 'male' | 'female' | 'neutral' | 'androgynous'
  age: VoiceAge;            // 'young' | 'young_adult' | 'middle_aged' | 'mature' | 'elderly'
  pitch: VoicePitch;        // 'very_low' to 'very_high'
  pace: VoicePace;          // 'very_slow' to 'very_fast'
  timbre: VoiceTimbre;      // 'warm' | 'bright' | 'dark' | 'resonant' | etc.
  energy: VoiceEnergy;      // 'calm' | 'relaxed' | 'neutral' | 'engaged' | etc.
  warmth: number;           // 0-1
  clarity: number;          // 0-1
  breathiness: number;      // 0-1
  resonance: number;        // 0-1
  expressiveness: number;   // 0-1
}
```

### Gender Options

| Gender | Description | Best For |
|--------|-------------|----------|
| `male` | Masculine voice | Wide range of content |
| `female` | Feminine voice | Wide range of content |
| `neutral` | Neither strongly masculine nor feminine | Inclusive content |
| `androgynous` | Balanced masculine/feminine | Spiritual, non-gendered |

### Age Characteristics

| Age | Typical Qualities | Content Match |
|-----|-------------------|---------------|
| `young` | Bright, energetic, clear | Kids content, energizing |
| `young_adult` | Fresh, dynamic | Motivational, fitness |
| `middle_aged` | Balanced, authoritative | General content |
| `mature` | Warm, experienced | Wisdom, meditation |
| `elderly` | Deep, wise, measured | Elder wisdom, traditions |

### Pitch Settings

| Pitch | Description | Use Cases |
|-------|-------------|-----------|
| `very_low` | Deep bass | Grounding, masculine |
| `low` | Lower register | Authority, calm |
| `medium_low` | Slightly low | Natural, settled |
| `medium` | Middle range | Neutral, versatile |
| `medium_high` | Slightly high | Engaging, friendly |
| `high` | Higher register | Light, feminine |
| `very_high` | Upper range | Children, energetic |

### Pace Guidelines

| Pace | Words/Min | Best For |
|------|-----------|----------|
| `very_slow` | ~80 | Deep meditation, sleep |
| `slow` | ~100 | Meditation, relaxation |
| `measured` | ~120 | Contemplation |
| `medium` | ~140 | General content |
| `moderate` | ~160 | Conversational |
| `fast` | ~180 | Energizing, excitement |
| `very_fast` | ~200+ | Urgency (rare) |

### Timbre Qualities

| Timbre | Character | Emotion |
|--------|-----------|---------|
| `warm` | Friendly, comforting | Safety, nurturing |
| `bright` | Clear, uplifting | Joy, energy |
| `dark` | Deep, mysterious | Depth, gravitas |
| `resonant` | Full, ringing | Authority, presence |
| `breathy` | Airy, intimate | Vulnerability, closeness |
| `clear` | Crisp, distinct | Instruction, clarity |
| `husky` | Textured, raw | Emotion, authenticity |
| `rich` | Full-bodied | Warmth, depth |
| `thin` | Light, delicate | Subtlety, gentleness |
| `full` | Complete, round | Completeness |

### Energy Levels

| Energy | Character | Content Type |
|--------|-----------|--------------|
| `calm` | Still, peaceful | Sleep, deep meditation |
| `relaxed` | Ease, comfort | Relaxation, wind-down |
| `neutral` | Balanced | General content |
| `engaged` | Attentive, present | Active meditation |
| `energetic` | Lively, dynamic | Morning meditation, motivation |
| `passionate` | Intense, heartfelt | Devotional, inspiring |
| `intense` | Powerful, focused | Transformation, breakthrough |

## Voice Profiles by Content Type

### Sleep Content

```typescript
const sleepVoice: VoiceCharacteristics = {
  gender: 'neutral',
  age: 'mature',
  pitch: 'low',
  pace: 'very_slow',
  timbre: 'warm',
  energy: 'calm',
  warmth: 0.9,
  clarity: 0.7,
  breathiness: 0.6,
  resonance: 0.7,
  expressiveness: 0.3
};
```

**Key traits:**
- Low pitch creates safety and grounding
- Very slow pace allows for drifting off
- High warmth for comfort
- Lower expressiveness for monotonous, sleep-inducing quality

### Meditation Content

```typescript
const meditationVoice: VoiceCharacteristics = {
  gender: 'female',
  age: 'mature',
  pitch: 'medium_low',
  pace: 'slow',
  timbre: 'warm',
  energy: 'relaxed',
  warmth: 0.85,
  clarity: 0.8,
  breathiness: 0.4,
  resonance: 0.75,
  expressiveness: 0.5
};
```

**Key traits:**
- Balanced but slightly low pitch
- Slow but not sleep-inducing pace
- High warmth and clarity
- Moderate expressiveness for guidance

### Kids Content

```typescript
const kidsVoice: VoiceCharacteristics = {
  gender: 'female',
  age: 'young_adult',
  pitch: 'medium_high',
  pace: 'moderate',
  timbre: 'bright',
  energy: 'engaged',
  warmth: 0.8,
  clarity: 0.9,
  breathiness: 0.2,
  resonance: 0.6,
  expressiveness: 0.8
};
```

**Key traits:**
- Higher pitch for approachability
- Moderate pace for engagement
- Bright timbre for energy
- High expressiveness for storytelling

### Energizing Content

```typescript
const energizingVoice: VoiceCharacteristics = {
  gender: 'male',
  age: 'young_adult',
  pitch: 'medium',
  pace: 'moderate',
  timbre: 'bright',
  energy: 'energetic',
  warmth: 0.7,
  clarity: 0.9,
  breathiness: 0.1,
  resonance: 0.8,
  expressiveness: 0.85
};
```

**Key traits:**
- Clear, projecting voice
- Moderate to fast pace
- High energy and expressiveness
- Low breathiness for power

### Healing Content

```typescript
const healingVoice: VoiceCharacteristics = {
  gender: 'neutral',
  age: 'mature',
  pitch: 'medium_low',
  pace: 'slow',
  timbre: 'rich',
  energy: 'calm',
  warmth: 0.95,
  clarity: 0.75,
  breathiness: 0.5,
  resonance: 0.8,
  expressiveness: 0.6
};
```

**Key traits:**
- Maximum warmth for safety
- Rich timbre for depth
- Moderate breathiness for intimacy
- Calm but present energy

## Tradition-Specific Profiles

### Zen Buddhist Voice

```typescript
const zenVoice: TraditionVoiceProfile = {
  tradition: 'zen_buddhism',
  name: 'Zen Master',
  typicalAccents: ['Japanese', 'neutral'],
  typicalQualities: ['sparse', 'direct', 'spacious'],
  typicalPace: 'slow',
  typicalTimbre: 'clear',
  typicalEnergy: 'calm',
  commonPhrases: [
    'Just sit',
    'What is this?',
    'Before thinking',
    'This moment, complete'
  ],
  sampleTexts: [
    'In zazen, we simply sit. Nothing to achieve. Nowhere to go.',
    'The bell sounds. Can you hear it? Where does it go?'
  ]
};
```

### Tibetan Buddhist Voice

```typescript
const tibetanVoice: TraditionVoiceProfile = {
  tradition: 'tibetan_buddhism',
  name: 'Tibetan Lama',
  typicalAccents: ['Tibetan', 'Indian', 'neutral'],
  typicalQualities: ['warm', 'devotional', 'expansive'],
  typicalPace: 'measured',
  typicalTimbre: 'rich',
  typicalEnergy: 'engaged',
  commonPhrases: [
    'Precious human life',
    'May all beings be free',
    'The nature of mind',
    'Compassion for all sentient beings'
  ],
  sampleTexts: [
    'Visualize the Buddha before you, radiating infinite light and compassion.',
    'May the merit of this practice benefit all beings throughout space and time.'
  ]
};
```

### Hindu/Yoga Voice

```typescript
const yogaVoice: TraditionVoiceProfile = {
  tradition: 'hinduism_yoga',
  name: 'Yoga Guide',
  typicalAccents: ['Indian', 'neutral'],
  typicalQualities: ['devotional', 'flowing', 'embodied'],
  typicalPace: 'slow',
  typicalTimbre: 'warm',
  typicalEnergy: 'engaged',
  commonPhrases: [
    'Breathe in prana',
    'Honor your body',
    'The divine within you',
    'Namaste'
  ],
  sampleTexts: [
    'Breathe in, drawing prana into your heart center. Breathe out, releasing tension.',
    'The light in me honors the light in you. Namaste.'
  ]
};
```

### Secular Mindfulness Voice

```typescript
const secularVoice: TraditionVoiceProfile = {
  tradition: 'secular_mindfulness',
  name: 'Mindfulness Instructor',
  typicalAccents: ['neutral', 'American', 'British'],
  typicalQualities: ['accessible', 'grounded', 'scientific'],
  typicalPace: 'measured',
  typicalTimbre: 'clear',
  typicalEnergy: 'relaxed',
  commonPhrases: [
    'Notice without judgment',
    'When your mind wanders',
    'Bring your attention back',
    'This is natural'
  ],
  sampleTexts: [
    'Simply notice where your attention is right now. There is no right or wrong.',
    'When thoughts arise, acknowledge them and gently return to the breath.'
  ]
};
```

## Prosody and Expression

### Speech Breaks

```typescript
// Break strengths for different contexts
const breakExamples = {
  none: '',                           // No pause
  'x-weak': '<break strength="x-weak"/>', // Minimal pause
  weak: '<break strength="weak"/>',   // Brief pause
  medium: '<break strength="medium"/>', // Normal pause
  strong: '<break strength="strong"/>', // Significant pause
  'x-strong': '<break strength="x-strong"/>' // Long pause
};

// Timed breaks
const timedBreaks = {
  sentence: '<break time="500ms"/>',  // Between sentences
  paragraph: '<break time="1s"/>',     // Between paragraphs
  breath: '<break time="3s"/>',        // For breathing space
  meditation: '<break time="5s"/>'     // Extended silence
};
```

### Prosody Adjustments

```typescript
interface ProsodyParams {
  rate?: number | 'x-slow' | 'slow' | 'medium' | 'fast' | 'x-fast';
  pitch?: number | 'x-low' | 'low' | 'medium' | 'high' | 'x-high';
  volume?: number | 'silent' | 'x-soft' | 'soft' | 'medium' | 'loud' | 'x-loud';
  range?: number; // Pitch range percentage
}

// Example: Slowing down for emphasis
const slowEmphasis: ProsodyParams = {
  rate: 'slow',
  pitch: 'low',
  volume: 'soft'
};

// Example: Energizing passage
const energizing: ProsodyParams = {
  rate: 'medium',
  pitch: 'medium-high',
  volume: 'medium'
};
```

### Emotional Expression

```typescript
// Map content type to emotional range
const emotionalRanges: Record<string, string[]> = {
  sleep: ['peaceful', 'drowsy', 'safe', 'cradled'],
  meditation: ['calm', 'present', 'spacious', 'grounded'],
  healing: ['compassionate', 'nurturing', 'accepting', 'loving'],
  energizing: ['vibrant', 'motivated', 'powerful', 'alive'],
  kids: ['playful', 'curious', 'adventurous', 'wonder-filled']
};
```

## ElevenLabs Voice Settings

### Stability vs. Similarity

```typescript
interface VoiceSettings {
  stability: number;        // 0-1: Higher = more consistent
  similarity_boost: number; // 0-1: Higher = more similar to original
  style?: number;           // 0-1: Style transfer intensity
  use_speaker_boost?: boolean; // Enhance clarity
}
```

**Stability Guidelines:**

| Content Type | Stability | Similarity | Rationale |
|--------------|-----------|------------|-----------|
| Sleep | 0.7-0.8 | 0.7-0.8 | Consistency for relaxation |
| Meditation | 0.5-0.7 | 0.75-0.85 | Balanced expression |
| Kids | 0.6-0.8 | 0.7-0.8 | Predictable for children |
| Storytelling | 0.3-0.5 | 0.8-0.9 | Expressive range |
| Healing | 0.5-0.7 | 0.75-0.85 | Warm, consistent |
| Energizing | 0.4-0.6 | 0.7-0.8 | Dynamic expression |

### Model Selection by Content

| Content Type | Primary Model | Alternative |
|--------------|--------------|-------------|
| Sleep | `eleven_v3` | `eleven_multilingual_v2` |
| Meditation | `eleven_v3` | `eleven_multilingual_v2` |
| Healing | `eleven_v3` | - |
| Storytelling | `eleven_v3` | `eleven_multilingual_v2` |
| Kids | `eleven_multilingual_v2` | `eleven_turbo_v2_5` |
| Energizing | `eleven_v3` | `eleven_turbo_v2_5` |
| Real-time | `eleven_flash_v2_5` | `eleven_turbo_v2_5` |

## Voice Generation Workflow

### 1. Define Requirements

```typescript
const requirements = {
  contentType: 'meditation',
  tradition: 'zen_buddhism',
  targetAudience: 'adults',
  sessionLength: 'long', // For consistency over time
  emotionalGoal: 'calm_presence',
  language: 'en'
};
```

### 2. Generate Voice Profile

```typescript
const voiceProfile: GeneratedVoiceProfile = {
  id: 'zen-guide-001',
  characteristics: {
    gender: 'neutral',
    age: 'mature',
    pitch: 'medium_low',
    pace: 'slow',
    timbre: 'clear',
    energy: 'calm',
    warmth: 0.8,
    clarity: 0.9,
    breathiness: 0.3,
    resonance: 0.75,
    expressiveness: 0.4
  },
  accent: {
    region: 'neutral',
    strength: 0.0,
    characteristics: ['clear', 'unaccented']
  },
  qualities: {
    primary: ['spacious', 'direct', 'grounded'],
    secondary: ['wise', 'patient']
  },
  personality: {
    traits: ['mindful', 'present', 'non-judgmental'],
    emotionalRange: ['calm', 'serene', 'peaceful'],
    speakingStyle: ['sparse', 'measured', 'deliberate']
  },
  description: 'A calm, grounded voice embodying Zen simplicity and presence.',
  promptForTTS: 'A mature, gender-neutral voice with clear timbre and calm energy. Speaks slowly and deliberately with natural pauses. Warm but not overly emotional.',
  sampleText: 'Simply sit. Notice the breath. This moment, just as it is.',
  metadata: {
    tradition: 'zen_buddhism',
    generatedAt: Date.now(),
    seed: 12345,
    version: '1.0'
  }
};
```

### 3. Configure TTS Settings

```typescript
const ttsConfig = {
  model_id: 'eleven_v3',
  voice_id: 'selected-voice-id',
  voice_settings: {
    stability: 0.6,
    similarity_boost: 0.8,
    style: 0.4,
    use_speaker_boost: true
  },
  output_format: 'mp3_44100_192'
};
```

### 4. Apply Content-Specific Tags

```typescript
const taggedContent = `
[calm] [deliberate] Welcome to this moment of stillness.
[pauses]
[warmly] Allow yourself to simply be here.
[thoughtful] Notice your breath, naturally flowing.
[deliberate] In... [pause] and out...
`;
```

## Voice Quality Validation

### Consistency Check

```typescript
interface VoiceQualityMetrics {
  pitchConsistency: number;      // 0-1
  paceConsistency: number;       // 0-1
  emotionalAlignment: number;    // 0-1
  clarityScore: number;          // 0-1
  naturalness: number;           // 0-1
}

function validateVoiceQuality(audio: Buffer): VoiceQualityMetrics {
  // Analyze audio for quality metrics
  return {
    pitchConsistency: 0.92,
    paceConsistency: 0.88,
    emotionalAlignment: 0.85,
    clarityScore: 0.95,
    naturalness: 0.90
  };
}
```

### Content Alignment Check

```typescript
function checkContentAlignment(
  voiceProfile: GeneratedVoiceProfile,
  contentType: string
): boolean {
  const contentEnergy = getExpectedEnergy(contentType);
  const voiceEnergy = voiceProfile.characteristics.energy;

  // Ensure voice energy matches content needs
  const energyMap = {
    sleep: ['calm'],
    meditation: ['calm', 'relaxed'],
    healing: ['calm', 'relaxed', 'engaged'],
    energizing: ['engaged', 'energetic', 'passionate']
  };

  return energyMap[contentType]?.includes(voiceEnergy) ?? false;
}
```

## Best Practices

### 1. Match Voice to Content

```typescript
// Good: Calm voice for sleep content
const sleepVoice = {
  energy: 'calm',
  pace: 'very_slow',
  timbre: 'warm'
};

// Avoid: Energetic voice for sleep
const wrongSleepVoice = {
  energy: 'energetic',  // Wrong for sleep
  pace: 'fast',         // Wrong for sleep
  timbre: 'bright'      // Too stimulating
};
```

### 2. Consider Session Length

```typescript
// Long sessions: Higher stability for consistency
const longSession = {
  stability: 0.7,
  similarity_boost: 0.8
};

// Short sessions: Can use more expression
const shortSession = {
  stability: 0.5,
  similarity_boost: 0.85
};
```

### 3. Test with Sample Text

```typescript
// Always test with representative content
const testTexts = {
  meditation: 'Take a deep breath. Notice the sensation of air entering your body.',
  sleep: 'Allow your body to sink deeper into rest. Let go of the day.',
  energizing: 'Feel the energy rising within you. You are alive and powerful.',
  healing: 'You are safe here. Allow healing light to flow through you.'
};
```

### 4. Iterate and Refine

```typescript
async function refineVoice(
  initialProfile: GeneratedVoiceProfile,
  feedback: UserFeedback
): Promise<GeneratedVoiceProfile> {
  const adjustments = interpretFeedback(feedback);

  return {
    ...initialProfile,
    characteristics: {
      ...initialProfile.characteristics,
      warmth: clamp(initialProfile.characteristics.warmth + adjustments.warmth, 0, 1),
      pace: adjustPace(initialProfile.characteristics.pace, adjustments.pace),
      expressiveness: clamp(initialProfile.characteristics.expressiveness + adjustments.expressiveness, 0, 1)
    }
  };
}
```

### 5. Maintain Voice Library

```typescript
interface VoiceLibrary {
  voices: Map<string, GeneratedVoiceProfile>;
  categories: Map<string, string[]>;  // category -> voice IDs
  favorites: string[];

  getVoicesByTradition(tradition: SpiritualTradition): GeneratedVoiceProfile[];
  getVoicesByContent(contentType: string): GeneratedVoiceProfile[];
  getRecommendedVoice(requirements: VoiceRequirements): GeneratedVoiceProfile;
}
```

## Common Pitfalls

### 1. Too Much Expression in Calming Content

```typescript
// Wrong: High expressiveness for sleep
{ expressiveness: 0.9 }  // Too stimulating

// Better: Low expressiveness for sleep
{ expressiveness: 0.3 }  // Monotonous, sleep-inducing
```

### 2. Mismatched Pace and Energy

```typescript
// Wrong: Fast pace with calm energy
{ pace: 'fast', energy: 'calm' }  // Confusing

// Better: Consistent pace and energy
{ pace: 'slow', energy: 'calm' }  // Aligned
```

### 3. Ignoring Cultural Context

```typescript
// Consider tradition when selecting accent
const traditionAccents = {
  zen_buddhism: ['neutral', 'Japanese'],
  hinduism_yoga: ['neutral', 'Indian'],
  sufism: ['neutral', 'Middle Eastern'],
  secular_mindfulness: ['neutral']
};
```

### 4. Over-Relying on Default Settings

```typescript
// Always customize for content type
const customSettings = getVoiceSettingsForContent(contentType);
// Don't use default settings blindly
```

## Related Resources

- [ElevenLabs Integration Guide](./elevenlabs-integration.md)
- [Audio Tag Best Practices](./audio-tag-best-practices.md)
- [Prompt Engineering for Meditation](./prompt-engineering-meditation.md)
- [Model Selection Guide](./model-selection.md)
