Creates a new ProsodyElement instance.
The text content to be spoken with modified prosody. Special XML characters (&, <, >, ", ') are automatically escaped. Can be any length of text from a single word to multiple paragraphs.
Configuration object for prosody modifications. All properties are optional.
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?: stringPitch 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.
Optionalpitch?: stringPitch adjustment for the speech.
Can be specified as:
Optionalrange?: stringPitch range variation.
Controls the variability of pitch (monotone vs expressive). Can be relative change or named value.
Optionalrate?: stringSpeaking rate/speed.
Can be specified as:
Optionalvolume?: stringVolume level of the speech.
Can be specified as:
// Whisper effect
const whisper = new ProsodyElement('This is confidential', {
volume: 'x-soft',
rate: 'slow',
pitch: 'low'
});
// Shouting effect
const shout = new ProsodyElement('Look out!', {
volume: 'x-loud',
pitch: 'high',
rate: 'fast'
});
// Robot/monotone voice
const robot = new ProsodyElement('I am a robot', {
pitch: 'medium',
range: 'x-low', // Minimal pitch variation
rate: '0.9'
});
// Question intonation with contour
const question = new ProsodyElement('Are you sure', {
contour: '(0%,+5Hz) (60%,+10Hz) (100%,+20Hz)' // Rising intonation
});
// Emphasis with multiple attributes
const emphasis = new ProsodyElement('This is important', {
pitch: '+10%',
rate: '0.8', // Slower
volume: '+5dB' // Louder
});
// Precise numeric control
const precise = new ProsodyElement('Precise control', {
pitch: '150Hz',
rate: '1.1', // 10% faster
volume: '75' // 75% volume
});
ProtectedescapeProtectedEscapes 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.
The text content to escape
The text with all special XML characters properly escaped
// In a render method implementation
class TextElement extends SSMLElement {
private text: string = 'Hello & "world" <script>';
render(): string {
// Escapes to: Hello & "world" <script>
return `<text>${this.escapeXml(this.text)}</text>`;
}
}
// Edge cases handled correctly
this.escapeXml('5 < 10 & 10 > 5');
// Returns: '5 < 10 & 10 > 5'
this.escapeXml('She said "Hello"');
// Returns: 'She said "Hello"'
this.escapeXml("It's a test");
// Returns: 'It's a test'
// Prevents XML injection
this.escapeXml('</voice><voice name="evil">');
// Returns: '</voice><voice name="evil">'
Renders the prosody element as an SSML XML string.
Generates the <prosody> element with only the specified attributes. Undefined
attributes are omitted from the output, keeping the XML clean. The text content
is automatically escaped to prevent XML injection and ensure valid output.
Attributes are rendered in a consistent order: pitch, contour, range, rate, volume.
The XML string representation of the prosody element with format:
<prosody [pitch="value"] [contour="value"] [range="value"] [rate="value"] [volume="value"]>text</prosody>
If no attributes are specified, returns: <prosody>text</prosody>
// Single attribute
const slow = new ProsodyElement('Slow speech', { rate: 'slow' });
console.log(slow.render());
// Output: <prosody rate="slow">Slow speech</prosody>
// Multiple attributes
const complex = new ProsodyElement('Complex prosody', {
pitch: 'high',
rate: 'fast',
volume: 'loud'
});
console.log(complex.render());
// Output: <prosody pitch="high" rate="fast" volume="loud">Complex prosody</prosody>
// With contour
const contour = new ProsodyElement('Rising tone', {
contour: '(0%,+0Hz) (100%,+20Hz)'
});
console.log(contour.render());
// Output: <prosody contour="(0%,+0Hz) (100%,+20Hz)">Rising tone</prosody>
// No attributes (valid but no effect)
const plain = new ProsodyElement('Plain text', {});
console.log(plain.render());
// Output: <prosody>Plain text</prosody>
// Special characters escaped
const special = new ProsodyElement('Terms & "conditions"', {
volume: 'soft'
});
console.log(special.render());
// Output: <prosody volume="soft">Terms & "conditions"</prosody>
SSML element for modifying prosodic properties of speech.
The
<prosody>element provides fine-grained control over various aspects of speech synthesis including pitch, speaking rate, volume, and intonation patterns. This element is essential for creating more natural and expressive synthesized speech by adjusting how text is spoken rather than what is spoken. Prosody modifications can convey emotion, emphasis, or create specific speaking styles like whispering or shouting.All prosody attributes are optional and can be combined to achieve complex speech modifications. The element affects all text and child elements within its scope, allowing for nested prosody elements with cumulative effects.
Example
Remarks
See