CallXML 2.0 Development Guide

| TOC

This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

Voxeo's Enhanced Text-To-Speech Guide

If you are looking to further refine your TTS output, this guide will give you all the knowledge that you need to fine-tune your applications for more naturalistic voice prompts. Voxeo currently uses the Speechify 2.0 engine for the Staging and Production environments, and this section will show you how to use TTS markup to add the final polish to your applications.

TTS Voices

Currently, we offer not only US-English voices, but also French and Spanish, (female), should you desire to deploy a multi-lingual application. The current options available are:

English-Female2
English-Male2
French-Female
Spanish-Female1

To change the default voice in CallXML, you will use the <text voice=”Name”> property as follows:

<text voice="English-Male2"> This is my English male voice </text>
<wait value="200ms"/>
<text voice="Spanish-Female1"> Escuche mi voz atractiva  </text>

Language-Specific Character Encoding

You should be aware that when using non-English TTS, some language-specific characters will cause a parse error, such as the following:

'¿','é', 'ó'

The simplest way to get around this in multilingual applications is to specify the xml document encoding that will allow these characters to parse:


<?xml version="1.0" encoding="iso-8859-1"?>
<callxml version="2.0">
 <block>
   <text voice="Spanish-Female1">
         ¿Qué sucedió a mis pantalones? 
  </text>
 </block>
</callxml>

Embedded Tags

Embedded tags are special codes that can be inserted into input text to customize the TTS behavior in a variety of ways. You can use embedded tags to:

Create pauses at specified points in the speech output
Customize word pronunciations
Spell out sequences of characters by name
Specify the interpretation of certain numeric expressions

A TTS tag begins with the sequence \! followed immediately by a string of alphanumeric characters. For example:

Markup	Explanation
`\!p300`	Synthesize a pause of 300 ms.

Markup	Explanation
`\!tsc`	Pronounce all characters individually by name.

Separate a tag from any preceding input by at least one unit of white space. A tag cannot be followed immediately by an alphanumeric character, though most tags may be followed immediately by punctuation, parentheses, and similar symbols.

Important: There must be a space before and after the tag in order for it to work properly. If you follow the tag immediately by a carriage return or line feed, the tag will not work and cause the entire sentence to fail. Put at least one space after that tag before that line feed.

Any sequence of non-white-space characters beginning with the prefix \! that is not a recognizable TTS tag is ignored in the speech output.

Creating Pauses

Use a pause tag to create a pause of a particular duration at a specified point in the speech output.

Pause Tag

Markup	Explanation
`\!pN`	Create a pause N milliseconds long.

The maximum value of the integer argument in a pause tag is 32767. To create a longer pause, use a series of consecutive pause tags. The smallest possible value of the pause tag is 1.

The behavior produced by the pause tag varies depending on its location in the text. When a pause tag is placed immediately before a punctuation mark, the standard pause duration triggered by the punctuation is replaced by the pause duration specified in the tag. In other locations, the tag creates an additional pause.

For example, sentence (a) has a default 150 ms pause at the comma. Sentences (b) and (c) replace the default pause with a longer and shorter pause, respectively, while sentence (d) inserts an additional pause of 300 ms, resulting in a total pause duration of 450 ms. In sentence (e) a 25 ms pause is inserted in a location where no pause would otherwise occur.

If a token begins with “http” or “www”, then up until the next white-space, the following symbols are expanded. The last / in a URL is omitted.

Input	Pronounciation
Tom is a good swimmer, because he took lessons as a child.	Tom is a good swimmer (150 ms pause), because he took lessons as a child.

Input	Pronounciation
Tom is a good swimmer \!p300, because he took lessons as a child.	Tom is a good swimmer (300 ms pause), because he took lessons as a child.

Input	Pronounciation
Tom is a good swimmer \!p100, because he took lessons as a child.	Tom is a good swimmer (100 ms pause), because he took lessons as a child.

Input	Pronounciation
Tom is a good swimmer, \!p300 because he took lessons as a child.	Tom is a good swimmer (150 ms pause), (300 ms pause) because he took lessons as a child.

Input	Pronounciation
Tom is a good swimmer, because he took lessons \!p25 as a child.	Tom is a good swimmer (150 ms pause), because he took lessons (25 ms pause) as a child.

Customizing pronunciations

In certain cases, you may want to specify a pronunciation that differs from the one generated by the internal text analysis rules. The tags described in this section are used to modify the default text processing behavior in a variety of ways:

Language-specific customizations

Character spellout modes

Pronouncing numbers and years

Customizing word pronunciations

Language-specific customizations
Some languages have tags that solve problems specific to those languages. For example, Mexican Spanish (es-MX) has tags for pronouncing the dollar sign ($) as “pesos” or “dollars” depending on the needs of the application.

Such tags are described in the Language Supplement.

Character Spellout Modes

The following tags are used to trigger character-by-character spellout of subsequent text.

Markup	Explanation
`\!ts0`	Default mode.

Markup	Explanation
`\!tsc`	All-character spellout mode: pronounce all characters individually by name

Markup	Explanation
`\!tsa`	Alphanumeric spellout mode: pronounce only alphanumeric characters by name.

Markup	Explanation
`\!tsr`	Radio spellout mode: like alphanumeric mode, but alphabetic characters are spelled out according to the International Radio Alphabet. Supported in English only.

For example:

Input	Pronounciation
My account number is \!tsa 487-B12.	My account number is four eight seven bee one two.

Input	Pronounciation
My account number is \!tsc 487-B12.	My account number is four eight seven dash bee one two.

Input	Pronounciation
The last name is spelled \!tsr Dvorak.	The last name is spelled delta victor oscar romeo alpha kilo.

Spellout modes remain in effect until they are turned off by the tag \!ts0, which restores the engine to its default processing mode. For example:

Input	Pronounciation
The composer’s name is spelled \!tsa Franz Liszt \!ts0 and pronounced "Franz Liszt."	The composer’s name is spelled eff ar ay en zee ell aye ess zee tee and pronounced Franz Liszt.

There are many words which are spelled out as a result of the default text processing behavior. In such cases, the use of a spellout mode tag may have no additional effect. For example:

Input	Pronounciation
He works for either the CIA or the FBI.	He works for either the cee aye ay or the eff bee aye.

Input	Pronounciation
He works for either the \!tsa CIA \!ts0 or the \!tsa FBI \!ts0.	He works for either the cee aye ay or the eff bee aye.

In alphanumeric and radio spellout modes, punctuation is interpreted exactly as it is in the default (non-spellout) mode; i.e., in most contexts it triggers a phrase break. In all-character spellout mode, punctuation is spelled out like any other character, rather than being interpreted as punctuation. Speech output continues without pause until the mode is turned off. For example:

Input	Pronounciation
\!tsa 3, 2, 1 \!ts0 blastoff.	three, two, one, blastoff

Input	Pronounciation
\!tsc 3, 2, 1 \!ts0, blastoff.	three comma two comma one, blastoff

Pronouncing Numbers and Years

In ordinary English text, a four digit numeric sequence with no internal commas or trailing decimal digits, like 1984, can be interpreted either as a year (nineteen eighty four) or as a quantity (one thousand nine hundred eighty four). The engine applies the year interpretation by default, as in:

Input	Pronounciation
He was born in May 1945.	He was born in May nineteen forty five.

To override the default year interpretation, and to restore the default interpretation, use the following tags:

Year Mode Tag	Pronounciation
`\!ny0`	Quantity interpretation.

Year Mode Tag	Pronounciation
`\!ny1`	Year interpretation (default).

For example:

Input	Pronounciation
In May \!ny0 1945 people emigrated.	In May one thousand nine hundred forty five people emigrated.

Each tag remains in effect until the interpretation is toggled by the use of the other tag. For example:

Input	Pronounciation
\!ny0 1945 \!ny1 people emigrated in 1945.	One thousand nine hundred forty five people emigrated in nineteen forty five.

Note: These tags have no effect in French or Spanish, where there is no difference in pronunciation between the year and quantity interpretations.

URLs

Pathnames

E-mail addresses

Telephone numbers

Years

Dates

Times

Rates

Uppercase strings

URLs

If a token begins with “http” or “www”, then up until the next white-space, the following symbols are expanded. The last / in a URL is omitted.

Symbol	Expansion
/	slash
.	dot
-	dash
_	underscore
:	,
~	tilde

Example:

Input	Pronounciation
http://voxeo.com/ is where the demo can be found	“aitch tee tee pee slash slash voxeo dot com is where the demo can be found”

Pathnames

If a token begins with “file” or an upper case letter followed by a colon (e.g. C: D: etc.), then until the next white space, the following symbols are expanded. The last / in a pathname is omitted..

Symbol	Expansion
/	slash
.	dot
-	dash
:	,
~	tilde

Example:

Input	Pronounciation
file:/C:/tts/dev is where to look for the executable.	“file colon slash see colon slash tee tee ehs slash dev, is where to look for the executable.”
C:\tts\dev\preproc.exe is the executable	“C colon slash tee tee ehs slash dev slash preproc dot exe, is the executable.”

Email Addresses

Symbols in an e-mail address are expanded as follows:

Symbol	Expansion
@	, at
.	dot
-	dash
_	underscore

Example:

Input	Pronounciation
email:john.smith@voxeo.com	“email, john dot smith, at voxeo dot com”

Telephone Numbers

US format telephone numbers read out as a sequence of cardinal numbers separated by pauses. The only exception to this is if 800 appears in the area code portion of the number, in which case the expansion is “eight hundred”.

Example:

Input	Pronounciation
1-800-428-5555	“one, eight hundred, four two eight, five five five five”
428-4444	“four two eight, four four four four”

Extension telephone numbers are also expanded. The following all produce the result “Extension number, one two three four”

ext. 1234 ext.1234 ext 1234 xt. 1234 xt.1234 xt 1234 x. 1234 x.1234 x 1234

Years

Four digit figures greater than 1000 and less than 3000 are context dependently converted into year format.

Example:

Input	Pronounciation
1200	“twelve hundred”
1801	“eighteen owe one”
1999	“nineteen ninety nine”
3487	“three four eight seven”

Dates

Dates in the following US formats are converted. If a date has been written in European format (e.g. dd/mm/yy), it is either not expanded, or it will be expanded as if it were a US format address (e.g. 02/01/99 will always be read out as “February first nineteen ninety nine”, rather than “January the second nineteen ninety nine”)..

Example:

Format	Example	Output
mm/dd/yyyy	03/31/2000	March thirty first, two thousand
mm/d/yyyy	12/7/1908	December seventh, nineteen oh eight
m/d/yyyy	6/22/1981	June twenty second, nineteen eighty one
mm/dd/yy	05/27/99	May twenty seventh, nineteen ninety nine
m/d/yyyy	9/1/1969	September first, nineteen sixty nine
mm/d/yy	06/1/55	June first, nineteen fifty five
m/dd/yy	5/12/97	May twelfth, nineteen ninety seven
m/d/yy	9/9/99	September ninth, nineteen ninety nine

Times

Multiple time formats are converted:

Example:

Markup	Explanation
11.07 pm	Eleven owe seven pee ehm
7.30.33 AM	Seven thirty ey ehm
13:45 pm	Thirteen forty five pee ehm
5:40 PM	Five forty pee ehm
10:20:59	Ten twenty
9:05:03	Nine owe five
13:36	Thirteen thirty six
8:10	Eight ten

Rates

Rates in the form QUANTITY1/QUANTITY2 are expanded.

Quantity1 is currently any of:

Quantity2 is currently any of:

s
sec
day
week
month
year

Any combination of these will be expanded. The / is expanded to “per“.

Example:

Input	Pronounciation
24 ins/year	Twenty four inches per year
m/s is a better measurement than km/h	Meters per second is a better measurement than kilometers per hour

Note: Seconds are not expanded at all. Times delimited by periods are only expanded inf the sequence is followed by am/AM or pm/PM.

User Tags

Escape sequences are embedded in the input text, and must be surrounded by white space. For tags that require numeric input, percentages should be represented as values between 0 and 1 (e.g., 66% = 0.66). Escape sequences are divided into five categories:

Special Case tags
Reading Style tags
Expansion Setting tags
Phonetic Input tags
Other tags

Note: All tags must always be preceded and followed by white space or they may not be detected correctly. This is true even if the string begins with a tag. In that case, you must begin the string with a space.

Special Case Tags

Certain types of text require special treatment – they need to be read out in a non-default manner.

Special Case	Code	Description
Addresses	a	Postal address format
Dates	d	mm/dd/yy for example
Fractions	f	½, ¾, for example
Measurements	l	Imperial & Metric units
Money	m	Currency units
Proper Names	n	People/Company names etc.
Ordinal Numbers	o	First, Second, Third, etc
Telephone Numbers	p	Telephone number format
Times	t	Times of day

Special cases can be difficult to detect. The TTS engine may think it has found a special case when it hasn’t (called a false positive) or instances may be missed. Italicized items above are particularly difficult to make work correctly. For each of the special cases above, the user can define how the TTS engine decides whether or not a text string is special. The default behavior is to have all special case risk modes set to conservative. The Risk options are:

Risk Setting	Code	Description
Off	o	No matches
Conservative	c	Might miss a few
Risky	r	Possible false-positives

Once the TTS Engine has identified one of the special cases (if the risk mode is not off), it treats it intelligently. The engine does not treat special cases differently in risky mode compared to conservative mode – the risk setting just dictates how many instances of a special case it is likely to detect.

The tag is written \!nCASERISK where CASE is one of the special case codes above, and RISK is one of the risk codes above. The case is treated in the specified risk mode after the tag. Below are some example tags with a broad description of the effect that each tag has on the processing. Note the special tag at the bottom of the table.

Markup	Explanation
\!nao	Don’t try to spot postal address formatting
\!ndc	Identify strings that look a lot like dates
\!nfr	Identify anything that looks like a fraction
\!nio	Don’t try to spot measurements
\!nmc	Identify things that look a lot like currency units
\!nnr	Identify anything that looks like a proper noun/name
\!npc	Identify things that look a lot like telephone numbers
\!ntr	Identify anything that looks like a time
\!de	Set ALL modes to conservative/default

Expansion Setting Tags

In TTS, expansion means noticing some sort of abbreviation (e.g. sec) and expanding it into a full word that represents how the abbreviation would be spoken (e.g. seconds). Expansion settings tags can de-activate expansion modes, which are turned on by default. This section describes the four modes that may be set: Acronym expansion, Abbreviation expansion, Numeric hyphen expansion, and Alphabetic hyphen expansion.

Acronym Expansion

Certain acronyms are spoken as if they were whole words (like OPEC), rather than being spelled out one letter at a time (like USA). By default, the TTS engine spells acronyms. Using the tags described below, it is possible to turn the acronym spell mode off for a given acronym, so that it is pronounced as a whole word. The tags are:

Markup	Explanation
\!ab	Start acronym spell mode
\!ae	Stop acronym spell mode

Example:

Input	Pronounciation
The USA has donated a million dollars to \!ae UNICEF \!ab in the UK	The yew es ey has donated a million dollars to unicef in the yew key

Abbreviation Expansion

By default, the TTS engine attempts to expand abbreviations that it knows about. If you want to turn this feature off, use the tag described below:

Markup	Explanation
\!eb	Start abbreviation expansion mode
\!ee	Stop abbreviation expansion mode

Examples:

Input	Pronounciation
Give me another 30 \! ee secs \!eb and I’ll be ready for Tue.	Give me another thirty secs, and I’ll be ready for Tuesday.

Alphabetic Hyphen Expansion

An alphabetic hyphen is any hyphen other than those defined in the “Numeric hyphen expansion”

Example:

Police saved a 7-month old baby

By default the alphabetic hyphen mode is terse which means that the hyphen is not pronounced. If the alphabetic hyphen mode is set to verbose, the hyphen will be pronounced as “dash”. The tags are:

Markup	Explanation
\!hav	Make alphabetic hyphen mode verbose
\!hat	Make alphabetic hyphen mode terse

Examples:

Input	Pronounciation
John was \!hav twenty-one for the \!hat thirty-third time yesterday.	John was twenty dash one for the thirty third time yesterday.

Other Tags

There are two useful miscellaneous tags:

“Proper nouns”
“Force sentence breaks”

Proper Nouns

Markup	Explanation
\!pn	Treat the next word like a proper noun

Example:

Input	Pronounciation
\!pn Begin was re-elected last Sunday.	BE-gin was re-elected last Sunday.

'Begin' will be treated as a proper noun in the TTS modules. Otherwise, it is possible (albeit unlikely) that it may be treated as a verb form. In this example, it is clear that knowing Begin as a proper noun results in a completely different pronunciation of the word: BE-gin versus be-GIN

Knowing that a word is a proper noun as opposed to another part of speech is also useful for other TTS processing modules. Using this tag ensures corrects handling on a one-off basis

Force Sentence Breaks

If the user wishes to override punctuation, and to force a sentence break at a particular point in the text string, it is possible to do so with this tag:.

Markup	Explanation
\!br	Force a sentence break here

Example:

Input	Pronounciation
It has to stop \!br now.	it has to stop. now

Abbreviations

The following tables enumerate the abbreviations recognized by the TTS engine.

Abbreviation	Expansion
AK	Alaska
Apr	April
AR	Arkansas
Aug	August
AZ	Arizona
CA	California
cm	centimeters(s)
Ctr	center
c/o, C/O	care of
db	decibel(s)
DC, Dc, dc	DC

Dec	December
deg	degree(s)
degs	degrees
e	east
EG	E G
etc	etcetera
Feb	February
Fri	Friday
GA, Ga	Georgia
ge	G E
gm	gram(s)
hrs	hours
Hz	hertz
Ia	Iowa
IBM	I B M
IL, il	Illonois
Jan	January
Jr	junior
Jun	Jun
kg	kilogram(s)
km	kilometer(s)
lb	pound(s)
lbs	pounds
Mar	March
Md	Maryland
mgmt	management
misc	miscellaneous
MN	Minnesota
Mr., MR.	mister
Mrs., MRS.	missus
msec	millisecond(s)
NC	North Carolina
ND	North Dakota
NH	New Hampshire
NJ	New Jersey
NM	New Mexico
Nov	November
NV	Nevada
NY	New York
Oct	October
PHD, Phd, phd	P H D
Pres.	president
RI	Rhode Island
Rm.	room
SC	South Carolina
SD	South Dakota
Sep	September
Sept	September
Sgt.	sergeant
Tbsp., tbsp.	tablespoon(s)
Tue.	Tuesday
Tues.	Tuesday
USA	U S A
UT	Utah
Va	Virginia
Vt	Vermont
WI	Wisconsin
WV	West Virginia
WY	Wyoming
yds.	yards
yr	year(s)
yrs	years

Multiple Expansions

Abbreviation	Expansion 1-	Expansion 2
apt	apartment	apt
Ct	Conneticut	court
Dr	doctor	drive
FL	Florida	floor
ft	foot	feet
KY, Ky	Kentucky	key
MT	Montana	mount
Ste	saint	suite
US	US	us

Links to the Language Supplements

Language Supplement for US English (en-US)
Language Supplement for Spanish (Mexican) (es-MX)
Language Supplement for French (Continental) (fr-FR)

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Logger Key -- CallXML

| TOC

| G: Rhetorical TTS Guide

Voxeo's Enhanced Text-To-Speech Guide

TTS Voices

Language-Specific Character Encoding

Embedded Tags

Creating Pauses

Customizing pronunciations

Character Spellout Modes

Pronouncing Numbers and Years

Syllable Boundaries

Syllable Stress

Speech Sound Symbols

Text Pre-Processing

Pathnames

Email Addresses

Telephone Numbers

Years

Dates

Times

Rates

User Tags

Special Case Tags

Expansion Setting Tags

Acronym Expansion

Abbreviation Expansion

Alphabetic Hyphen Expansion

Other Tags

Force Sentence Breaks

Abbreviations

Multiple Expansions

Links to the Language Supplements