Class ParagraphElement

SSML element for structuring content into paragraphs.

The  element denotes a paragraph in synthesized speech, providing logical structure to the content and ensuring appropriate pauses between blocks of text. The speech synthesizer uses paragraph boundaries to apply natural intonation patterns and timing, creating more comprehensible and natural-sounding speech output. This element is particularly useful for longer texts where clear separation of ideas improves listener comprehension.

Paragraphs can contain various inline elements including text, sentences, breaks, emphasis, prosody, and other speech modification elements. The paragraph element helps the synthesizer understand document structure even when sentence elements aren't explicitly marked.

Example

// Simple paragraph with text
const paragraph = new ParagraphElement();
paragraph.text('This is a complete paragraph.');
paragraph.render();
// Output: <p>This is a complete paragraph.</p>

// Paragraph with multiple elements
const complex = new ParagraphElement();
complex
  .text('Important: ')
  .emphasis('Read carefully', 'strong')
  .text(' before proceeding.');

// Use with SSMLBuilder
const ssml = new SSMLBuilder({ lang: 'en-US' })
  .voice('en-US-AvaNeural')
    .paragraph(p => p
      .text('First paragraph content.')
    )
    .paragraph(p => p
      .text('Second paragraph content.')
    )
  .build();

Remarks

Paragraphs automatically add appropriate pauses before and after their content [[11]]
Can contain text and the following elements: audio, break, phoneme, prosody, say-as, sub, mstts:express-as, and s [[11]]
Paragraph boundaries help with natural speech flow and intonation
Nested paragraphs are not allowed
Special XML characters in text are automatically escaped
If paragraphs are not explicitly marked, the service automatically determines structure

See

https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#specify-paragraphs-and-sentences Paragraph and Sentence Documentation [[11]]
https://www.w3.org/TR/speech-synthesis11/#S3.1.8 W3C SSML Paragraph Specification

Hierarchy (View Summary)

SSMLElement
- ParagraphElement

Index

Constructors

constructor

Methods

addElement audio break emphasis escapeXml phoneme prosody render sayAs sub text

Constructors

constructor

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

Methods

addElement

addElement(element: SSMLElement): this
Adds an SSML element as a child of this paragraph.

This method allows adding any valid SSML element that can be contained within a paragraph, enabling complex structured content with various speech modifications and effects.
Parameters
- element: SSMLElement
  An SSML element to add to the paragraph. Must be a valid child element for paragraphs.
Returns this
This ParagraphElement instance for method chaining
Example
```
const paragraph = new ParagraphElement();
const sentence = new SentenceElement();
sentence.text('This is a sentence.');
paragraph.addElement(sentence);

// Add multiple elements
const emphasis = new EmphasisElement('important', 'strong');
paragraph
  .text('This is ')
  .addElement(emphasis)
  .text(' information.');
```
- Defined in elements/ParagraphElement.ts:123

audio

audio(src: string, fallbackText?: string): this
Adds an audio file to the paragraph.

The audio element allows insertion of pre-recorded audio files within the paragraph content, with optional fallback text.
Parameters
- src: string
  URL of the audio file (must be HTTPS)
- OptionalfallbackText: string
  Optional text to speak if audio is unavailable
Returns this
This ParagraphElement instance for method chaining
Example
```
paragraph
  .text('Listen to this sound: ')
  .audio('https://example.com/sound.mp3', 'Audio effect')
  .text(' Interesting, right?');
```
- Defined in elements/ParagraphElement.ts:309

break

break(options?: string | BreakOptions): this
Adds a pause or break within the paragraph.

Breaks provide control over pauses between words or sentences, useful for improving comprehension or creating dramatic effect.
Parameters
- Optionaloptions: string | BreakOptions
  Break configuration or duration string. Can be a duration (e.g., '500ms') or an object with strength/time.
Returns this
This ParagraphElement instance for method chaining
Example
```
// Simple duration
paragraph
  .text('First point')
  .break('1s')
  .text('Second point');

// With strength
paragraph
  .text('Let me think')
  .break({ strength: 'medium' })
  .text('Yes, I remember');
```
- Defined in elements/ParagraphElement.ts:226

emphasis

emphasis(text: string, level?: EmphasisLevel): this
Adds emphasized text to the paragraph.

Emphasis changes the speaking style to highlight important words or phrases through changes in pitch, timing, and vocal stress.
Parameters
- text: string
  The text to emphasize
- Optionallevel: EmphasisLevel
  Optional emphasis level: 'strong', 'moderate' (default), or 'reduced'
Returns this
This ParagraphElement instance for method chaining
Example
```
paragraph
  .text('This is ')
  .emphasis('very important', 'strong')
  .text(' for everyone to know.');
```
- Defined in elements/ParagraphElement.ts:196

`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
Adds phonetic pronunciation for specific text.

The phoneme element provides exact pronunciation using phonetic alphabets, essential for proper names or technical terms that might be mispronounced.
Parameters
- text: string
  The 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 ParagraphElement instance for method chaining
Example
```
paragraph
  .text('The company ')
  .phoneme('Xilinx', { alphabet: 'ipa', ph: 'zaɪlɪŋks' })
  .text(' makes semiconductors.');
```
- Defined in elements/ParagraphElement.ts:255

prosody

prosody(text: string, options: ProsodyOptions): this
Adds text with modified prosody (pitch, rate, volume).

Prosody modifications affect how text is spoken, allowing for expressive variations in speech characteristics.
Parameters
- text: string
  The text to modify
- options: ProsodyOptions
  Prosody configuration
  
  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 ParagraphElement instance for method chaining
Example
```
paragraph
  .text('Normal speech, then ')
  .prosody('whispered text', { 
    volume: 'x-soft', 
    pitch: 'low' 
  })
  .text(' back to normal.');
```
- Defined in elements/ParagraphElement.ts:286

render

render(): string
Renders the paragraph element as an SSML XML string.

Generates the  element containing all child content. Text content is automatically escaped to prevent XML injection, while child elements are rendered recursively to build the complete paragraph structure.

Returns string
The XML string representation of the paragraph element
Example
```
const paragraph = new ParagraphElement();
paragraph
 .text('This is ')
 .emphasis('important', 'strong')
 .text('.');
console.log(paragraph.render());
// Output: This is <emphasis level="strong">important</emphasis>.
```
Overrides SSMLElement.render
- Defined in elements/ParagraphElement.ts:336

sayAs

sayAs(text: string, options: SayAsOptions): this
Adds a say-as element to control pronunciation of formatted text.

The say-as element ensures proper pronunciation of dates, numbers, currency, and other specialized text formats within the paragraph.
Parameters
- text: string
  The text to be interpreted
- options: SayAsOptions
  Configuration for text interpretation
  
  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 ParagraphElement instance for method chaining
Example
```
paragraph
  .text('The date is ')
  .sayAs('2025-12-31', { interpretAs: 'date', format: 'ymd' })
  .text(' and the amount is ')
  .sayAs('42.50', { interpretAs: 'currency', detail: 'USD' });
```
- Defined in elements/ParagraphElement.ts:150

sub

sub(original: string, alias: string): this
Adds a substitution element for custom pronunciation.

The sub element allows you to specify an alias that should be spoken instead of the written text, useful for acronyms or abbreviations.
Parameters
- original: string
  The text as written
- alias: string
  How the text should be pronounced
Returns this
This ParagraphElement instance for method chaining
Example
```
paragraph
  .text('The ')
  .sub('WHO', 'World Health Organization')
  .text(' recommends regular exercise.');
```
- Defined in elements/ParagraphElement.ts:173

text

text(text: string): this
Adds plain text content to the paragraph.

The text will be spoken as part of the paragraph with appropriate pauses and intonation for paragraph context. Special XML characters are automatically escaped to ensure valid XML output and prevent injection attacks.
Parameters
- text: string
 The text content to add to the paragraph. Will be spoken with paragraph-appropriate prosody. Multiple calls append text sequentially.
Returns this
This ParagraphElement instance for method chaining
Example
```
const paragraph = new ParagraphElement();
paragraph.text('This is the first sentence. ');
paragraph.text('This is the second sentence.');
// Result: This is the first sentence. This is the second sentence.

// With special characters (automatically escaped)
paragraph.text('Terms & conditions apply.');
```
- Defined in elements/ParagraphElement.ts:92

Class ParagraphElement

Example

Remarks

See

Hierarchy (View Summary)

Index

Constructors

Methods

Constructors

constructor

Returns ParagraphElement

Methods

addElement

Parameters

Returns this

Example

audio

Parameters

Returns this

Example

break

Parameters

Returns this

Example

emphasis

Parameters

Returns this

Example

ProtectedescapeXml

Parameters

Returns string

Example

See

phoneme

Parameters

alphabet: PhonemeAlphabet

Example

Example

ph: string

Example

Example

Returns this

Example

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

render

Returns string

Example

sayAs

Parameters

Optionaldetail?: string

Example

Example

Example

Optionalformat?: string

Example

Example

`Protected`escapeXml

`Optional`contour?: string

`Optional`pitch?: string

`Optional`range?: string

`Optional`rate?: string

`Optional`volume?: string

`Optional`detail?: string

`Optional`format?: string