Utterance access

A set of simple access methods exist for utterances, relations, items and features, both in Scheme and C++. As much as possible these access methods are as similar as possible.

As the users of this document will primarily be accessing utterance via Scheme we will describe the basic Scheme functions available for access and give some examples of idioms to achieve various standard functions.

In general the required arguments to a lisp function are reflected in the first parts of the name of the function. Thus item.relation.next requires an item, and relation name and will return the next item in that named relation from the given one.

A listing a short description of the major utterance access and manipulation functions is given in the Festival manual.

An important notion to be aware of is that an item is always viewed through so particular relation. For example, assuming a typically utterance called utt1.

(set! seg1 (utt.relation.first utt1 'Segment))

seg1 is an item viewed from the Segment relation. Calling item.next on this will return the next item in the Segment relation. A Segment item may also be in the SylStructure item. If we traverse it using next in that relation we will hit the end when we come to the end of the segments in that syllable.

You may view a given item from a specified relation by requesting a view from that. In Scheme nil will be returned if the item is not in the relation. The function item.relation takes an item and relation name and returns the item as view from that relation.

Here is a short example to help illustrate the basic structure.

(set! utt1 (utt.synth (Utterance Text "A short example.")))

The first segment in utt! will be silence.

(set! seg1 (utt.relation.first utt1 'Segment))

This item will be a silence as can shown by

(item.name seg1)

If we find the next item we will get the schwa representing the indefinite article.

(set! seg2 (item.next seg1))
(item.name seg2)

Let us move onto the "sh" to illustrate the different between traversing the Segment relation as opposed to the SylStructure

(set! seg3 (item.next seg2))

Let use define a function which will take an item, print its name name call next on it in the same relation and continue until it reaches the end.

(define (toend item) 
  (if item
      (begin
       (print (item.name item))
       (toend (item.next item)))))

If we call this function on seg3 which is in the Segment relation we will get a list of all segments until the end of the utterance

festival> (toend seg3)
"sh"
"oo"
"t"
"i"
"g"
"z"
"aa"
"m"
"p"
"@"
"l"
"#"
nil
festival>

However if we first changed the view of seg3 to the SylStructure relation we will be traversing the leaf nodes of the syllable structure tree which will terminate at the end of that syllable.

festival> (toend (item.relation seg3 'SylStructure)
"sh"
"oo"
"t"
nil
festival> 

Note that item.next returns the item immediately to the next in that relation. Thus it return nil when the end of a sub-tree is found. item.next is most often used for traversing simple lists through it is defined for any of the structure supported by relations. The function item.next_item allows traversal of any relation returning a next item until it has visiting them all. In the simple list case this this equivalent to item.next but in the tree case it will traverse the tree in pre-order that is it will visit roots before their daughters, and before their next siblings.

Scheme is particularly adept at using functions as first class objects. A typical traversal idiom is to apply so function to each item in a a relation. For example support we have a function PredictDuration which takes a single item and assigns a duration. We can apply this to each item in the Segment relation

(mapcar
 PredictDuration
 (utt.relation.items utt1 'Segment))

The function utt.relation.items returns all items in the relation as a simple lisp list.

Another method to traverse the items in a relation is use the while looping paradigm which many people are more familiar with.

(let ((f (utt.relation.first utt1 'Segment)))
  (while f
   (PredictDuration f)
   (set! f (item.next_item f))))

If you wish to traverse only the leaves of a tree you may call utt.relation.leafs instead of utt.relation.items. A leaf is defined to be an item with no daughters. Or in the while case, there isn't standardly defined a item.next_leaf but code easily be defined as

(define (item.next_leaf i)
  (let ((n (item.next_item i)))
   (cond
    ((null n) nil)
    ((item.daughters n) (item.next_leaf n))
    (t n))))