Accessing an utterance (Festival Speech Synthesis System)

14.5 Accessing an utterance

There are a number of standard functions that allow one to access parts of an utterance and traverse through it.

Functions exist in Lisp (and of course C++) for accessing an utterance. The Lisp access functions are

‘(utt.relationnames UTT)’: returns a list of the names of the relations currently created in UTT.
‘(utt.relation.items UTT RELATIONNAME)’: returns a list of all items in RELATIONNAME in UTT. This is nil if no relation of that name exists. Note for tree relation will give the items in pre-order.
‘(utt.relation_tree UTT RELATIONNAME)’: A Lisp tree presentation of the items RELATIONNAME in UTT. The Lisp bracketing reflects the tree structure in the relation.
‘(utt.relation.leafs UTT RELATIONNAME)’: A list of all the leafs of the items in RELATIONNAME in UTT. Leafs are defined as those items with no daughters within that relation. For simple list relations utt.relation.leafs and utt.relation.items will return the same thing.
‘(utt.relation.first UTT RELATIONNAME)’: returns the first item in RELATIONNAME. Returns nil if this relation contains no items
‘(utt.relation.last UTT RELATIONNAME)’: returns the last (the most next) item in RELATIONNAME. Returns nil if this relation contains no items
‘(item.feat ITEM FEATNAME)’: returns the value of feature FEATNAME in ITEM. FEATNAME may be a feature name, feature function name, or pathname (see below). allowing reference to other parts of the utterance this item is in.
‘(item.features ITEM)’: Returns an assoc list of feature-value pairs of all local features on this item.
‘(item.name ITEM)’: Returns the name of this ITEM. This could also be accessed as (item.feat ITEM 'name).
‘(item.set_name ITEM NEWNAME)’: Sets name on ITEM to be NEWNAME. This is equivalent to (item.set_feat ITEM 'name NEWNAME)
‘(item.set_feat ITEM FEATNAME FEATVALUE)’: set the value of FEATNAME to FEATVALUE in ITEM. FEATNAME should be a simple name and not refer to next, previous or other relations via links.
‘(item.relation ITEM RELATIONNAME)’: Return the item as viewed from RELATIONNAME, or nil if ITEM is not in that relation.
‘(item.relationnames ITEM)’: Return a list of relation names that this item is in.
‘(item.relationname ITEM)’: Return the relation name that this item is currently being viewed as.
‘(item.next ITEM)’: Return the next item in ITEM’s current relation, or nil if there is no next.
‘(item.prev ITEM)’: Return the previous item in ITEM’s current relation, or nil if there is no previous.
‘(item.parent ITEM)’: Return the parent of ITEM in ITEM’s current relation, or nil if there is no parent.
‘(item.daughter1 ITEM)’: Return the first daughter of ITEM in ITEM’s current relation, or nil if there are no daughters.
‘(item.daughter2 ITEM)’: Return the second daughter of ITEM in ITEM’s current relation, or nil if there is no second daughter.
‘(item.daughtern ITEM)’: Return the last daughter of ITEM in ITEM’s current relation, or nil if there are no daughters.
‘(item.leafs ITEM)’: Return a list of all lefs items (those with no daughters) dominated by this item.
‘(item.next_leaf ITEM)’: Find the next item in this relation that has no daughters. Note this may traverse up the tree from this point to search for such an item.

As from 1.2 the utterance structure may be fully manipulated from Scheme. Relations and items may be created and deleted, as easily as they can in C++;

‘(utt.relation.present UTT RELATIONNAME)’

returns t if relation named RELATIONNAME is present, nil otherwise.

‘(utt.relation.create UTT RELATIONNAME)’

Creates a new relation called RELATIONNAME. If this relation already exists it is deleted first and items in the relation are derefenced from it (deleting the items if they are no longer referenced by any relation). Thus create relation guarantees an empty relation.

‘(utt.relation.delete UTT RELATIONNAME)’

Deletes the relation called RELATIONNAME in utt. All items in that relation are derefenced from the relation and if they are no longer in any relation the items themselves are deleted.

‘(utt.relation.append UTT RELATIONNAME ITEM)’

Append ITEM to end of relation named RELATIONNAME in UTT. Returns nil if there is not relation named RELATIONNAME in UTT otherwise returns the item appended. This new item becomes the last in the top list. ITEM item may be an item itself (in this or another relation) or a LISP description of an item, which consist of a list containing a name and a set of feature vale pairs. It ITEM is nil or inspecified an new empty item is added. If ITEM is already in this relation it is dereferenced from its current position (and an empty item re-inserted).

‘(item.insert ITEM1 ITEM2 DIRECTION)’

Insert ITEM2 into ITEM1’s relation in the direction specified by DIRECTION. DIRECTION may take the value, before, after, above and below. If unspecified, after is assumed. Note it is not recommended to insert above and below and the functions item.insert_parent and item.append_daughter should normally be used for tree building. Inserting using before and after within daughters is perfectly safe.

‘(item.append_daughter PARENT DAUGHTER)’

Append DAUGHTER, an item or a description of an item to the item PARENT in the PARENT’s relation.

‘(item.insert_parent DAUGHTER NEWPARENT)’

Insert a new parent above DAUGHTER. NEWPARENT may be a item or the description of an item.

‘(item.delete ITEM)’

Delete this item from all relations it is in. All daughters of this item in each relations are also removed from the relation (which may in turn cause them to be deleted if they cease to be referenced by any other relation.

‘(item.relation.remove ITEM)’

Remove this item from this relation, and any of its daughters. Other relations this item are in remain untouched.

‘(item.move_tree FROM TO)’

Move the item FROM to the position of TO in TO’s relation. FROM will often be in the same relation as TO but that isn’t necessary. The contents of TO are dereferenced. its daughters are saved then descendants of FROM are recreated under the new TO, then TO’s previous daughters are derefenced. The order of this is important as FROM may be part of TO’s descendants. Note that if TO is part of FROM’s descendants no moving occurs and nil is returned. For example to remove all punction terminal nodes in the Syntax relation the call would be something like

(define (syntax_relation_punc p)
  (if (string-equal "punc" (item.feat (item.daughter2 p) "pos"))
      (item.move_tree (item.daughter1 p) p)
  (mapcar syntax_remove_punc (item.daughters p))))

‘(item.exchange_trees ITEM1 ITEM2)’

Exchange ITEM1 and ITEM2 and their descendants in ITEM2’s relation. If ITEM1 is within ITEM2’s descendants or vice versa nil is returns and no exchange takes place. If ITEM1 is not in ITEM2’s relation, no exchange takes place.

Daughters of a node are actually represented as a list whose first daughter is double linked to the parent. Although being aware of this structure may be useful it is recommended that all access go through the tree specific functions *.parent and *.daughter* which properly deal with the structure, thus is the internal structure ever changes in the future only these tree access function need be updated.

With the above functions quite elaborate utterance manipulations can be performed. For example in post-lexical rules where modifications to the segments are required based on the words and their context. See Post-lexical rules, for an example of using various utterance access functions.