Class BackgroundAudioElement

SSML element for adding background audio to the entire speech output (Azure-specific).

The <mstts:backgroundaudio> element plays audio continuously throughout the entire SSML document, behind all spoken content. This is useful for adding ambient music, sound effects, or any audio atmosphere that enhances the listening experience. The background audio automatically loops if it's shorter than the speech duration and is trimmed if longer.

This is an Azure Speech Service specific extension and requires the mstts namespace. Only one background audio element can be used per SSML document, and it must be placed as a direct child of the <speak> element, before any <voice> elements.

Example

// Basic background audio
const bgAudio = new BackgroundAudioElement({
  src: 'https://example.com/music.mp3'
});
bgAudio.render();
// Output: <mstts:backgroundaudio src="https://example.com/music.mp3"/>

// With all options
const fullBgAudio = new BackgroundAudioElement({
  src: 'https://example.com/ambient.mp3',
  volume: '0.5',
  fadein: '3000ms',
  fadeout: '2000ms'
});

// Use with SSMLBuilder
const ssml = new SSMLBuilder({ lang: 'en-US' })
  .backgroundAudio({
    src: 'https://example.com/background.mp3',
    volume: '0.3',
    fadein: '2000ms'
  })
  .voice('en-US-AvaNeural')
    .text('This speech has background music playing softly.')
  .build();

Remarks

The audio file must be accessible via HTTPS (not HTTP)
Supported formats include MP3, WAV, and other common audio formats
The audio automatically loops if shorter than the speech duration
The audio is trimmed if longer than the speech duration
Only one background audio element is allowed per SSML document
Must be a direct child of the speak element, placed before voice elements
Consider file size and bandwidth when using background audio
The background audio doesn't affect speech timing or pauses

See

https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#add-background-audio Background Audio Documentation

Hierarchy (View Summary)

SSMLElement
- BackgroundAudioElement

Index

Constructors

constructor

Methods

escapeXml render

Constructors

constructor

new BackgroundAudioElement(
options: BackgroundAudioOptions,
): BackgroundAudioElement
Creates a new BackgroundAudioElement instance.
Parameters
- options: BackgroundAudioOptions
  Configuration object for the background audio element
  
  Configuration options for background audio.
  
  Defines audio that plays throughout the entire SSML document, behind the spoken content. Useful for adding music or ambient sounds.
  - Optionalfadein?: string
    Duration of the fade-in effect at the start.
    
    Gradually increases volume from 0 to the specified volume level. Specified in milliseconds (ms) or seconds (s).
    
    Example
    "2000ms" - 2-second fade in
    
    Example
    "3s" - 3-second fade in
  - Optionalfadeout?: string
    Duration of the fade-out effect at the end.
    
    Gradually decreases volume from the specified level to 0. Specified in milliseconds (ms) or seconds (s).
    
    Example
    "1500ms" - 1.5-second fade out
    
    Example
    "2s" - 2-second fade out
  - src: string
    URL of the background audio file. (Required)
    
    Requirements:
    
    Must be a publicly accessible HTTPS URL
    
    Supported formats: MP3, WAV, and other common audio formats
    
    File size limits depend on the service tier
    
    Audio automatically loops if shorter than speech duration
    
    Example
    "https://example.com/background-music.mp3"
    
    Example
    "https://cdn.example.com/sounds/ambient.wav"
  - Optionalvolume?: string
    Volume level of the background audio.
    
    Can be specified as:
    
    Decimal: "0.0" (silent) to "1.0" (full volume)
    
    Percentage: "0%" to "100%"
    
    Decibels: "+0dB", "-6dB" (negative reduces volume)
    
    Default Value
    "1.0"
    
    Example
    "0.5" - 50% volume
    
    Example
    "30%" - 30% volume
    
    Example
    "-6dB" - Reduce by 6 decibels
Returns BackgroundAudioElement
Example
```
// Minimal configuration
const simple = new BackgroundAudioElement({
  src: 'https://cdn.example.com/ambient.mp3'
});

// With volume control
const withVolume = new BackgroundAudioElement({
  src: 'https://cdn.example.com/music.mp3',
  volume: '0.3'  // 30% volume
});

// Full configuration with fades
const full = new BackgroundAudioElement({
  src: 'https://cdn.example.com/soundtrack.mp3',
  volume: '0.5',      // 50% volume
  fadein: '3000ms',   // 3-second fade in
  fadeout: '2000ms'   // 2-second fade out
});

// For podcast/narration
const podcast = new BackgroundAudioElement({
  src: 'https://example.com/podcast-intro.mp3',
  volume: '-10dB',    // Reduced by 10 decibels
  fadein: '5s',       // Slow 5-second fade in
  fadeout: '3s'       // 3-second fade out
});
```
Overrides SSMLElement.constructor
- Defined in elements/BackgroundAudioElement.ts:114

Methods

`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

render

render(): string

Renders the background audio element as an SSML XML string.

Generates the Azure-specific <mstts:backgroundaudio> element with the specified audio source and optional volume/fade settings. This element is self-closing and does not contain any child elements. The attributes are only included if their corresponding option values are provided.

Returns string

The XML string representation of the background audio element in the format: <mstts:backgroundaudio src="url" [volume="value"] [fadein="duration"] [fadeout="duration"]/>

Example

// Minimal output
const basic = new BackgroundAudioElement({
  src: 'https://example.com/music.mp3'
});
console.log(basic.render());
// Output: <mstts:backgroundaudio src="https://example.com/music.mp3"/>

// With volume
const withVol = new BackgroundAudioElement({
  src: 'https://example.com/music.mp3',
  volume: '0.5'
});
console.log(withVol.render());
// Output: <mstts:backgroundaudio src="https://example.com/music.mp3" volume="0.5"/>

// Full configuration
const full = new BackgroundAudioElement({
  src: 'https://example.com/music.mp3',
  volume: '0.3',
  fadein: '2000ms',
  fadeout: '1500ms'
});
console.log(full.render());
// Output: <mstts:backgroundaudio src="https://example.com/music.mp3" volume="0.3" fadein="2000ms" fadeout="1500ms"/>

Class BackgroundAudioElement

Example

Remarks

See

Hierarchy (View Summary)

Index

Constructors

Methods

Constructors

constructor

Parameters

`Optional`fadein?: string

Example

Example

`Optional`fadeout?: string

Example

Example

src: string

Example

Example

`Optional`volume?: string

Default Value

Example

Example

Example

Returns BackgroundAudioElement

Example

Methods

`Protected`escapeXml

Parameters

Returns string

Example

See

render

Returns string

Example

Settings

On This Page

Class BackgroundAudioElement

Example

Remarks

See

Hierarchy (View Summary)

Index

Constructors

Methods

Constructors

constructor

Parameters

Optionalfadein?: string

Example

Example

Optionalfadeout?: string

Example

Example

src: string

Example

Example

Optionalvolume?: string

Default Value

Example

Example

Example

Returns BackgroundAudioElement

Example

Methods

ProtectedescapeXml

Parameters

Returns string

Example

See

render

Returns string

Example

Settings

On This Page

`Optional`fadein?: string

`Optional`fadeout?: string

`Optional`volume?: string

`Protected`escapeXml