Class ParagraphBuilder

Builder class for creating paragraph elements within an SSML document. Provides a fluent API for structuring content into logical paragraph blocks with sentences and speech modifications.

Paragraphs help organize speech content and provide natural pauses between text blocks. The <p> element is particularly useful for longer texts where you want to maintain proper speech flow and intonation patterns.

Example

// Basic paragraph usage
voice.paragraph(p => p
  .text('This is the first sentence. ')
  .text('This is the second sentence.')
);

Example

// Advanced paragraph with multiple elements
voice.paragraph(p => p
  .text('Welcome to our presentation. ')
  .sentence(s => s
    .text('This sentence has ')
    .emphasis('emphasis', 'strong')
  )
  .break('500ms')
  .sayAs('2025', { interpretAs: 'date' })
);

See

https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#specify-paragraphs-and-sentences Paragraph Element Documentation

Hierarchy (View Summary)

SSMLElement
- ParagraphBuilder

Index

Constructors

constructor

Methods

audio break emphasis escapeXml phoneme prosody render sayAs sentence sub text

Constructors

constructor

new ParagraphBuilder(): ParagraphBuilder
Returns ParagraphBuilder
Inherited from SSMLElement.constructor

Methods

audio

audio(src: string, fallbackText?: string): this
Inserts an audio file within the paragraph. Supports fallback text if the audio file is unavailable.

Audio elements can be used to include pre-recorded sounds, music, or other audio content within the synthesized speech.
Parameters
- src: string
  URL of the audio file (must be publicly accessible HTTPS URL)
- OptionalfallbackText: string
  Optional text to speak if audio fails to load
Returns this
This ParagraphBuilder instance for method chaining
Example
```
paragraph
  .text('And now, a word from our sponsor')
  .break('500ms')
  .audio(
    'https://example.com/jingle.mp3',
    'Sponsor message here'
  )
  .text('Back to our content.');
```
See
https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#add-recorded-audio Audio Element Documentation
- Defined in builders/ParagraphBuilder.ts:322

break

break(options?: string | BreakOptions): this
Adds a pause or break within the paragraph. Can specify either duration or strength of the pause.

Breaks are useful for adding natural pauses between phrases or ideas, improving the comprehension and naturalness of synthesized speech.
Parameters
- Optionaloptions: string | BreakOptions
  Break configuration or duration string
  - string
  - BreakOptions
    Configuration options for break/pause elements.
    
    Defines pauses in speech either by strength (semantic) or explicit duration. If both are specified, time takes precedence.
    
    Optionalstrength?: BreakStrength
    Semantic strength of the pause.
    
    Each strength corresponds to a typical pause duration:
    
    x-weak: 250ms (very short)
    
    weak: 500ms (short, like a comma)
    
    medium: 750ms (default, like a period)
    
    strong: 1000ms (long, like paragraph break)
    
    x-strong: 1250ms (very long, for emphasis)
    
    Ignored if time is specified.
    
    Example
    "medium"
    
    Example
    "strong"
    
    Optionaltime?: string
    Explicit duration of the pause.
    
    Specified in milliseconds (ms) or seconds (s). Valid range: 0-20000ms (20 seconds max) Values above 20000ms are capped at 20000ms.
    
    Takes precedence over strength if both are specified.
    
    Example
    "500ms" - Half second
    
    Example
    "2s" - 2 seconds
    
    Example
    "1500ms" - 1.5 seconds
Returns this
This ParagraphBuilder instance for method chaining
Example
```
// Using duration string
paragraph
  .text('First point')
  .break('1s')
  .text('Second point');

// Using strength
paragraph
  .text('Let me think')
  .break({ strength: 'medium' })
  .text('Yes, I remember now');
```
See
https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#add-a-break Break Element Documentation
- Defined in builders/ParagraphBuilder.ts:214

emphasis

emphasis(text: string, level?: EmphasisLevel): this
Adds emphasized speech with adjustable intensity to the paragraph. Changes the speaking style to emphasize certain words or phrases.
Parameters
- text: string
  Text to emphasize
- Optionallevel: EmphasisLevel
  Emphasis level: 'strong' | 'moderate' | 'reduced'. Default is 'moderate'
Returns this
This ParagraphBuilder instance for method chaining
Example
```
paragraph
  .text('This is ')
  .emphasis('extremely important', 'strong')
  .text(' for everyone to understand.')
  .emphasis('Please pay attention', 'moderate');
```
See
https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#adjust-emphasis Emphasis Element Documentation
- Defined in builders/ParagraphBuilder.ts:180

`Protected`escapeXml

escapeXml(text: string): string
Protected
Escapes special XML characters in text content to ensure valid XML output.

This method replaces XML special characters with their corresponding entity references to prevent XML parsing errors and potential security issues (XML injection). It should be used whenever inserting user-provided or dynamic text content into XML elements.

The following characters are escaped:
- & becomes & (must be escaped first to avoid double-escaping)
- < becomes < (prevents opening of unintended tags)
- > becomes > (prevents closing of unintended tags)
- " becomes " (prevents breaking out of attribute values)
- ' becomes ' (prevents breaking out of attribute values)
This method is marked as protected so it's only accessible to classes that extend SSMLElement, ensuring proper encapsulation while allowing all element implementations to use this essential functionality.
Parameters
- text: string
  The text content to escape
Returns string
The text with all special XML characters properly escaped
Example
```
// In a render method implementation
class TextElement extends SSMLElement {
  private text: string = 'Hello & "world" <script>';
  
  render(): string {
    // Escapes to: Hello &amp; &quot;world&quot; &lt;script&gt;
    return `<text>${this.escapeXml(this.text)}</text>`;
  }
}

// Edge cases handled correctly
this.escapeXml('5 < 10 & 10 > 5');  
// Returns: '5 &lt; 10 &amp; 10 &gt; 5'

this.escapeXml('She said "Hello"');  
// Returns: 'She said &quot;Hello&quot;'

this.escapeXml("It's a test");       
// Returns: 'It&apos;s a test'

// Prevents XML injection
this.escapeXml('</voice><voice name="evil">');  
// Returns: '&lt;/voice&gt;&lt;voice name=&quot;evil&quot;&gt;'
```
See
- https://www.w3.org/TR/xml/#syntax XML 1.0 Specification - Character Data and Markup
- https://cheatsheetseries.owasp.org/cheatsheets/XML_Security_Cheat_Sheet.html OWASP XML Security
Inherited from SSMLElement.escapeXml
- Defined in core/SSMLElement.ts:129

phoneme

phoneme(text: string, options: PhonemeOptions): this
Specifies exact phonetic pronunciation for text within the paragraph. Provides precise control over how specific words are pronounced.

This is particularly useful for proper names, technical terms, or words that the speech synthesizer might pronounce incorrectly by default.
Parameters
- text: string
  Text to pronounce
- options: PhonemeOptions
  Phoneme configuration
  
  Configuration options for phoneme elements.
  
  Provides exact phonetic pronunciation using standard phonetic alphabets. Essential for proper names, technical terms, or words with ambiguous pronunciation.
  - alphabet: PhonemeAlphabet
    Phonetic alphabet used for transcription. (Required)
    
    Available alphabets:
    
    ipa: International Phonetic Alphabet (universal standard)
    
    sapi: Microsoft SAPI phonemes (English-focused)
    
    ups: Universal Phone Set (Microsoft's unified system)
    
    Example
    "ipa"
    
    Example
    "sapi"
  - ph: string
    Phonetic transcription of the word. (Required)
    
    The exact phonetic representation in the specified alphabet. Must be valid according to the chosen alphabet's rules.
    
    Example
    "ˈʃɛdjuːl" - IPA for "schedule" (British)
    
    Example
    "s k eh jh uw l" - SAPI for "schedule" (American)
Returns this
This ParagraphBuilder instance for method chaining
Example
```
// Using IPA (International Phonetic Alphabet)
paragraph
  .text('The word ')
  .phoneme('schedule', {
    alphabet: 'ipa',
    ph: 'ˈʃɛdjuːl'  // British pronunciation
  })
  .text(' has different pronunciations.');

// Using SAPI
paragraph.phoneme('Azure', {
  alphabet: 'sapi',
  ph: 'ae zh er'
});
```
See
https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#use-phonemes-to-improve-pronunciation Phoneme Element Documentation
- Defined in builders/ParagraphBuilder.ts:252

prosody

prosody(text: string, options: ProsodyOptions): this
Modifies prosody (pitch, rate, volume) of speech within the paragraph. Allows fine-grained control over how text is spoken.

Prosody modifications can make speech sound more natural and expressive, and can be used to convey emotion or emphasis.
Parameters
- text: string
  Text to modify
- options: ProsodyOptions
  Prosody configuration options
  
  Configuration options for prosody (speech characteristics).
  
  Controls various aspects of speech delivery including pitch, speaking rate, volume, and intonation contours. Multiple properties can be combined for complex speech modifications.
  - Optionalcontour?: string
    Pitch contour changes over time.
    
    Defines how pitch changes during speech using time-position pairs. Format: "(time1,pitch1) (time2,pitch2) ..." Time as percentage, pitch as Hz or percentage change.
    
    Example
    "(0%,+5Hz) (50%,+10Hz) (100%,+5Hz)" - Rising intonation
    
    Example
    "(0%,+20Hz) (100%,-10Hz)" - Falling intonation
  - Optionalpitch?: string
    Pitch adjustment for the speech.
    
    Can be specified as:
    
    Absolute frequency: "200Hz", "150Hz"
    
    Relative change: "+2st" (semitones), "+10%", "-5%"
    
    Named values: "x-low", "low", "medium", "high", "x-high"
    
    Example
    "high" - High pitch
    
    Example
    "+10%" - 10% higher
    
    Example
    "200Hz" - Specific frequency
    
    Example
    "-2st" - 2 semitones lower
  - Optionalrange?: string
    Pitch range variation.
    
    Controls the variability of pitch (monotone vs expressive). Can be relative change or named value.
    
    Example
    "x-low" - Very monotone
    
    Example
    "high" - Very expressive
    
    Example
    "+10%" - 10% more variation
  - Optionalrate?: string
    Speaking rate/speed.
    
    Can be specified as:
    
    Multiplier: "0.5" (half speed), "2.0" (double speed)
    
    Percentage: "+10%", "-20%"
    
    Named values: "x-slow", "slow", "medium", "fast", "x-fast"
    
    Example
    "slow" - Slow speech
    
    Example
    "1.5" - 50% faster
    
    Example
    "+25%" - 25% faster
  - Optionalvolume?: string
    Volume level of the speech.
    
    Can be specified as:
    
    Numeric: "0" to "100" (0=silent, 100=loudest)
    
    Percentage: "50%", "80%"
    
    Decibels: "+10dB", "-5dB"
    
    Named values: "silent", "x-soft", "soft", "medium", "loud", "x-loud"
    
    Example
    "soft" - Quiet speech
    
    Example
    "loud" - Loud speech
    
    Example
    "50" - 50% volume
    
    Example
    "+5dB" - 5 decibels louder
Returns this
This ParagraphBuilder instance for method chaining
Example
```
// Whispered effect
paragraph.prosody('This is a secret', {
  volume: 'x-soft',
  rate: 'slow',
  pitch: 'low'
});

// Excited speech
paragraph.prosody('Amazing news!', {
  rate: 'fast',
  pitch: 'high',
  volume: 'loud'
});
```
See
https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#adjust-prosody Prosody Element Documentation
- Defined in builders/ParagraphBuilder.ts:292

render

render(): string
Internal
Renders the paragraph element as an XML string. This method is called internally by the SSML builder to generate the final XML.

Returns string
The paragraph element as an XML string with all its content
Example
```
const xml = paragraphBuilder.render();
// Returns: <p>paragraph content here</p>
```
Overrides SSMLElement.render
- Defined in builders/ParagraphBuilder.ts:340

sayAs

sayAs(text: string, options: SayAsOptions): this
Controls how text is interpreted and pronounced within the paragraph. Useful for dates, numbers, currency, abbreviations, and other specialized text.

This method forwards to the underlying ParagraphElement's sayAs method, allowing proper pronunciation of special text formats.
Parameters
- text: string
  Text to interpret
- options: SayAsOptions
  Say-as configuration options
  
  Configuration options for say-as elements.
  
  Controls interpretation and pronunciation of formatted text like dates, numbers, currency, and other specialized content.
  - Optionaldetail?: string
    Additional detail for interpretation.
    
    Provides extra context for certain interpretAs types:
    
    For currency: ISO currency code (USD, EUR, GBP, etc.)
    
    For other types: Additional pronunciation hints
    
    Example
    "USD" - US Dollars
    
    Example
    "EUR" - Euros
    
    Example
    "JPY" - Japanese Yen
  - Optionalformat?: string
    Format hint for interpretation.
    
    Provides additional formatting information. Available formats depend on interpretAs value:
    
    For dates:
    
    "mdy": Month-day-year
    
    "dmy": Day-month-year
    
    "ymd": Year-month-day
    
    "md": Month-day
    
    "dm": Day-month
    
    "ym": Year-month
    
    "my": Month-year
    
    "d": Day only
    
    "m": Month only
    
    "y": Year only
    
    For time:
    
    "hms12": 12-hour format with seconds
    
    "hms24": 24-hour format with seconds
    
    Example
    "ymd" - For date: 2025-12-31
    
    Example
    "hms24" - For time: 14:30:00
  - interpretAs: SayAsInterpretAs
    How to interpret the text content. (Required)
    
    Determines the pronunciation rules applied to the text. Each type has specific formatting requirements.
    
    Example
    "date" - For dates
    
    Example
    "cardinal" - For numbers
    
    Example
    "telephone" - For phone numbers
    
    Example
    "currency" - For money
    
    See
    SayAsInterpretAs type for full list
Returns this
This ParagraphBuilder instance for method chaining
Example
```
paragraph
  .text('The meeting is on ')
  .sayAs('2025-08-24', { 
    interpretAs: 'date', 
    format: 'ymd' 
  })
  .text(' at ')
  .sayAs('14:30', { 
    interpretAs: 'time',
    format: 'hms24'
  });
```
See
https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#say-as-element Say-As Element Documentation
- Defined in builders/ParagraphBuilder.ts:131

sentence

sentence(callback: (sentenceElement: SentenceElement) => void): this
Adds a sentence element to the paragraph with structured content. Sentences help define clear boundaries for intonation and natural pauses.

The <s> element explicitly marks sentence boundaries, which can improve the naturalness of speech synthesis by ensuring proper intonation patterns.
Parameters
- callback: (sentenceElement: SentenceElement) => void
  Function that receives a SentenceElement to build sentence content
Returns this
This ParagraphBuilder instance for method chaining
Example
```
// Simple sentence
paragraph.sentence(s => s
  .text('This is a complete sentence.')
);

// Sentence with multiple elements
paragraph.sentence(s => s
  .text('The price is ')
  .sayAs('42.50', { interpretAs: 'currency', detail: 'USD' })
  .text(' including tax.')
);
```
See
https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#specify-paragraphs-and-sentences Sentence Element Documentation
- Defined in builders/ParagraphBuilder.ts:93

sub

sub(original: string, alias: string): this
Substitutes text with an alias for pronunciation within the paragraph. Useful for acronyms, abbreviations, or text that should be pronounced differently than written.
Parameters
- original: string
  The original text as written
- alias: string
  How the text should be pronounced
Returns this
This ParagraphBuilder instance for method chaining
Example
```
paragraph
  .text('The ')
  .sub('WHO', 'World Health Organization')
  .text(' released new guidelines.')
  .sub('Dr.', 'Doctor')
  .text(' Smith will present them.');
```
See
https://www.w3.org/TR/speech-synthesis11/#S3.1.11 Sub Element W3C Specification
- Defined in builders/ParagraphBuilder.ts:156

text

text(text: string): this
Adds plain text content to the paragraph. Special characters (&, <, >, ", ') are automatically escaped.
Parameters
- text: string
  The text to add to the paragraph
Returns this
This ParagraphBuilder instance for method chaining
Example
```
paragraph.text('This is a simple paragraph text. ');

// Chain multiple text segments
paragraph
  .text('First part. ')
  .text('Second part. ')
  .text('Third part.');
```
- Defined in builders/ParagraphBuilder.ts:61

Class ParagraphBuilder

Example

Example

See

Hierarchy (View Summary)

Index

Constructors

Methods

Constructors

constructor

Returns ParagraphBuilder

Methods

audio

Parameters

Returns this

Example

See

break

Parameters

Optionalstrength?: BreakStrength

Example

Example

Optionaltime?: string

Example

Example

Example

Returns this

Example

See

emphasis

Parameters

Returns this

Example

See

ProtectedescapeXml

Parameters

Returns string

Example

See

phoneme

Parameters

alphabet: PhonemeAlphabet

Example

Example

ph: string

Example

Example

Returns this

Example

See

prosody

Parameters

Optionalcontour?: string

Example

Example

Optionalpitch?: string

Example

Example

Example

Example

Optionalrange?: string

Example

Example

Example

Optionalrate?: string

Example

Example

Example

Optionalvolume?: string

Example

Example

Example

Example

Returns this

Example

See

render

Returns string

Example

sayAs

`Optional`strength?: BreakStrength

`Optional`time?: string

`Protected`escapeXml

`Optional`contour?: string

`Optional`pitch?: string

`Optional`range?: string

`Optional`rate?: string

`Optional`volume?: string

`Optional`detail?: string

`Optional`format?: string