Eve library

SSML Syntax Reference

Guide

Revision 1

On this page

Purpose: Complete technical reference for Speech Synthesis Markup Language (SSML) as used in Lilith's TTS system.

Core SSML Elements#

Document Structure#

Root Element#

xml
<speak version="1.1"
       xmlns="http://www.w3.org/2001/10/synthesis"
       xml:lang="en-US">
  <!-- All SSML content must be within speak tags -->
</speak>

Text Organization#

xml
<!-- Paragraph and sentence structure -->
<speak>
  <p>This is a paragraph with multiple sentences.</p>

  <p>
    <s>This is the first sentence.</s>
    <s>This is the second sentence.</s>
  </p>
</speak>

Timing and Pauses#

Break Elements#

xml
<!-- Various pause durations for contemplative content -->
<speak>
  <!-- Time-based breaks -->
  <s>Take a moment to breathe in<break time="1s"/>and breathe out.</s>

  <!-- Strength-based breaks -->
  <s>Notice your thoughts<break strength="medium"/>without judgment.</s>

  <!-- Sentence and paragraph breaks -->
  <s>End of thought.</s>
  <break strength="strong"/>
  <s>Beginning of new idea.</s>
</speak>

Contemplative Timing Patterns#

xml
<!-- Optimal timing for meditation guidance -->
<speak>
  <p>
    <s>Close your eyes gently.</s>
    <break time="2s"/>
    <s>Feel your body settling into stillness.</s>
    <break time="3s"/>
    <s>Now bring your attention to your breath.</s>
    <break time="1500ms"/>
    <s>Simply observe without trying to change anything.</s>
    <break time="4s"/>
  </p>
</speak>

Prosody Control#

Rate Adjustment#

xml
<!-- Speech rate variations for different content types -->
<speak>
  <!-- Slow for meditation -->
  <prosody rate="slow">
    <s>Allow your breath to find its natural rhythm.</s>
  </prosody>

  <!-- Medium for explanations -->
  <prosody rate="medium">
    <s>This practice helps develop present-moment awareness.</s>
  </prosody>

  <!-- Percentage-based fine control -->
  <prosody rate="75%">
    <s>Gradual speed adjustment for optimal comprehension.</s>
  </prosody>
</speak>

Pitch Modulation#

xml
<!-- Pitch control for emotional expression -->
<speak>
  <!-- Gentle, warm tone -->
  <prosody pitch="medium" range="narrow">
    <s>You are safe in this moment.</s>
  </prosody>

  <!-- Slight elevation for encouragement -->
  <prosody pitch="+2st" range="medium">
    <s>Trust in your innate wisdom.</s>
  </prosody>

  <!-- Lower pitch for grounding -->
  <prosody pitch="-1st" range="narrow">
    <s>Feel your connection to the earth beneath you.</s>
  </prosody>
</speak>

Volume Control#

xml
<!-- Volume variations for different effects -->
<speak>
  <!-- Soft for intimate guidance -->
  <prosody volume="soft">
    <s>Listen to the silence between your thoughts.</s>
  </prosody>

  <!-- Medium for normal instruction -->
  <prosody volume="medium">
    <s>When you notice your mind wandering, gently return to your breath.</s>
  </prosody>

  <!-- Subtle emphasis without harshness -->
  <prosody volume="loud" rate="90%">
    <s>You have everything you need within you right now.</s>
  </prosody>
</speak>

Emphasis and Expression#

Emphasis Levels#

xml
<!-- Appropriate emphasis for wisdom content -->
<speak>
  <!-- Reduced emphasis for subtle concepts -->
  <s>The practice of <emphasis level="reduced">non-attachment</emphasis>
  doesn't mean not caring.</s>

  <!-- Moderate emphasis for key concepts -->
  <s>Mindfulness is about <emphasis level="moderate">awareness</emphasis>,
  not control.</s>

  <!-- Strong emphasis for crucial insights -->
  <s>Remember: you are <emphasis level="strong">not</emphasis> your thoughts.</s>
</speak>

Say-As Elements#

xml
<!-- Proper pronunciation for numbers, dates, and special terms -->
<speak>
  <!-- Date pronunciation -->
  <s>The Buddha was born in approximately
  <say-as interpret-as="date" format="year">563 BCE</say-as>.</s>

  <!-- Number pronunciation -->
  <s>Practice this for just <say-as interpret-as="cardinal">5</say-as> minutes.</s>

  <!-- Time pronunciation -->
  <s>We'll meditate for <say-as interpret-as="time" format="ms">00:10</say-as>.</s>
</speak>

Advanced Pronunciation#

Phoneme-Level Control#

xml
<!-- Precise pronunciation for philosophical terms -->
<speak>
  <!-- Sanskrit terms -->
  <s>The concept of <phoneme alphabet="ipa" ph="ˈdʰərːmə">dharma</phoneme>
  is central to Buddhist teaching.</s>

  <!-- Greek philosophical terms -->
  <s>Aristotle's concept of <phoneme alphabet="ipa" ph="juːdaɪˈmoʊniə">eudaimonia</phoneme>
  refers to human flourishing.</s>

  <!-- Arabic Sufi terms -->
  <s>The Sufi practice of <phoneme alphabet="ipa" ph="ˈðikr">dhikr</phoneme>
  involves remembrance of the Divine.</s>
</speak>

Content-Specific SSML Patterns#

Meditation Guidance Templates#

Progressive Relaxation#

xml
<!-- SSML template for body scan meditation -->
<speak>
  <prosody rate="slow" pitch="medium-low" volume="soft">
    <p>
      <s>Let's begin by bringing attention to your feet.</s>
      <break time="2s"/>
      <s>Notice any sensations there</s>
      <break time="1s"/>
      <s>without needing to change anything.</s>
      <break time="3s"/>
    </p>

    <p>
      <s>Now let your awareness move slowly up to your legs.</s>
      <break time="2s"/>
      <s>Feel the weight of your legs</s>
      <break time="1s"/>
      <s>resting and supported.</s>
      <break time="4s"/>
    </p>

    <p>
      <s>Continue this gentle scanning</s>
      <break time="1s"/>
      <s>moving awareness through your whole body</s>
      <break time="2s"/>
      <s>with curiosity and kindness.</s>
      <break time="5s"/>
    </p>
  </prosody>
</speak>

Breathing Meditation#

xml
<!-- SSML for breath awareness meditation -->
<speak>
  <prosody rate="70%" pitch="medium" volume="soft">
    <p>
      <s>Simply rest your attention on the breath</s>
      <break time="1500ms"/>
      <s>feeling the gentle rise</s>
      <break time="2000ms"/>
      <s>and fall</s>
      <break time="2500ms"/>
      <s>of your chest and belly.</s>
      <break time="3000ms"/>
    </p>

    <p>
      <s>Each breath is a new beginning</s>
      <break time="1000ms"/>
      <s>a fresh opportunity</s>
      <break time="800ms"/>
      <s>to be present.</s>
      <break time="4000ms"/>
    </p>
  </prosody>
</speak>

Philosophical Explanation Templates#

Concept Introduction#

xml
<!-- SSML for introducing complex philosophical concepts -->
<speak>
  <prosody rate="85%" pitch="medium" volume="medium">
    <p>
      <s>Let's explore the concept of <emphasis level="moderate">impermanence</emphasis>.</s>
      <break time="600ms"/>
      <s>This is one of the fundamental insights in Buddhist philosophy.</s>
    </p>

    <break time="1s"/>

    <p>
      <s>Impermanence means that <emphasis level="strong">everything</emphasis>
      in our experience is constantly changing.</s>
      <break time="500ms"/>
      <s>Nothing remains the same from moment to moment.</s>
    </p>

    <break time="800ms"/>

    <p>
      <s>This includes our thoughts, our emotions, our physical sensations,</s>
      <break time="300ms"/>
      <s>and all the circumstances of our lives.</s>
    </p>
  </prosody>
</speak>

Practical Application#

xml
<!-- SSML for practical wisdom application -->
<speak>
  <prosody rate="90%" pitch="medium" volume="medium">
    <p>
      <s>Here's how you can apply this insight in daily life.</s>
      <break time="600ms"/>
    </p>

    <p>
      <s><emphasis level="moderate">First</emphasis>, when you're experiencing
      something difficult,</s>
      <break time="400ms"/>
      <s>remind yourself: <emphasis level="strong">"This too shall pass."</emphasis></s>
    </p>

    <break time="800ms"/>

    <p>
      <s><emphasis level="moderate">Second</emphasis>, when you're experiencing
      something wonderful,</s>
      <break time="400ms"/>
      <s>appreciate it fully while it's here,</s>
      <break time="300ms"/>
      <s>knowing that its very preciousness comes from its temporary nature.</s>
    </p>
  </prosody>
</speak>

Quality Optimization#

Voice-Content Matching#

Content Analysis for Voice Selection#

python
# Automated voice-content matching system
from lilith.voice_matching import ContentVoiceAnalyzer

analyzer = ContentVoiceAnalyzer()

# Analyze content characteristics
content_analysis = analyzer.analyze_content(
    text_content=philosophical_text,
    analysis_dimensions=[
        "emotional_tone",
        "complexity_level",
        "tradition_context",
        "intended_use_case",
        "target_audience"
    ]
)

# Match to optimal voice profile
voice_recommendation = analyzer.recommend_voice_profile(
    content_analysis=content_analysis,
    available_voices=["contemplative_female_01", "scholarly_male_02", "gentle_female_03"],
    optimization_criteria={
        "tradition_appropriateness": 0.4,
        "emotional_matching": 0.3,
        "clarity_optimization": 0.2,
        "user_preference": 0.1
    }
)

# Generate optimized SSML
optimized_ssml = analyzer.generate_optimized_ssml(
    text_content=philosophical_text,
    voice_profile=voice_recommendation.recommended_voice,
    content_analysis=content_analysis,
    optimization_target="contemplative_absorption"
)

Audio Quality Validation#

Automated Quality Checks#

python
# Comprehensive audio quality validation
class AudioQualityValidator:
    def __init__(self):
        self.quality_standards = self.load_quality_standards()
        self.analysis_tools = self.initialize_analysis_tools()

    def validate_generated_audio(self, audio_file: str, ssml_source: str) -> QualityReport:
        quality_report = QualityReport()

        # Technical audio analysis
        technical_analysis = self.analyze_technical_quality(
            audio_file=audio_file,
            standards=self.quality_standards.technical
        )
        quality_report.add_section("technical_quality", technical_analysis)

        # Prosodic accuracy analysis
        prosodic_analysis = self.analyze_prosodic_accuracy(
            audio_file=audio_file,
            ssml_markup=ssml_source,
            expected_prosody=self.extract_prosody_targets(ssml_source)
        )
        quality_report.add_section("prosodic_accuracy", prosodic_analysis)

        # Perceptual quality analysis
        perceptual_analysis = self.analyze_perceptual_quality(
            audio_file=audio_file,
            content_type=self.detect_content_type(ssml_source),
            listening_context="contemplative_practice"
        )
        quality_report.add_section("perceptual_quality", perceptual_analysis)

        # Generate overall quality score
        overall_score = self.calculate_overall_quality_score(
            technical_score=technical_analysis.score,
            prosodic_score=prosodic_analysis.score,
            perceptual_score=perceptual_analysis.score,
            weights=self.quality_standards.scoring_weights
        )

        quality_report.overall_score = overall_score
        quality_report.pass_threshold = self.quality_standards.pass_threshold
        quality_report.recommendations = self.generate_improvement_recommendations(quality_report)

        return quality_report

Technical Requirements: All SSML must validate against W3C SSML 1.1 specification and pass Lilith's enhanced quality standards for contemplative audio content.