PromptQueue object
The PromptQueue object is a browser object used to
control prompt playback. It is accessible from script and has no markup element
on the SALT page. Not all browsers need to support the PromptQueue
module. In an HTML profile where the PromptQueue module
is supported, the PromptQueue object will be a child
of the window object.
The PromptQueue is maintained as a browser object rather than a markup element
for two reasons:
- It maintains a central object for playback control. The asynchronous nature
of the call to prompt.Queue() means that with multiple queued prompts,
the application cannot know (without explicit maintenance scripts) which prompt
is currently being played back, and therefore which to pause/stop/resume,
etc. when necessary. The PromptQueue object provides
a single object for doing this.
- This permits prompt playback to be uninterrupted across page transitions,
since the PromptQueue object persists across the
loading and unloading of individual pages. That is, unlike the markup elements
in the DOM, it is not destroyed when its containing page is unloaded (although
events which would otherwise be thrown to the prompt
elements, are lost if the containing page has been unloaded). An example of
this is shown below.
The PromptQueue object operates in the following
manner:
- The PromptQueue is a singleton object which conceptually
holds one or more prompt subqueues.
- As outlined in 2.1 of the SALT 1.0 Specs, these subqueues are delimited
by Start() calls (either on individual prompts
or on the PromptQueue itself).
- A new subqueue is initiated by calling Queue() on a prompt either when the PromptQueue
is empty, or after a Start() call when it is playing back.
- That is, each set of prompts queued and followed by Start() is considered a single subqueue.
- A subqueue will not be played back until a Start() call is made.
It will be seen below that actions of the PromptQueue
are local to a subqueue rather than the entire PromptQueue
object, with the exception of the Flush()
and Change() methods. The events supported
by PromptQueue have scope at the level of subqueue.
For example, the completion of playback of each subqueue is signaled by the
onempty event (see event handlers, below). An onerror
event on a single prompt will flush the
subqueue in which that prompt was held, but will not affect any other subqueues
in the PromptQueue (and therefore does not necessarily
halt playback as seen in the event handlers, below). Bargein
behavior is also local to a subqueue: that where bargein is set true, an onBargein
event on a single prompt will stop playback
and flush the current subqueue. Similarly, all PromptQueue
methods take effect in the scope of the subqueue rather than that of the PromptQueue
object, except PromptQueue.Flush(),
which is a global action to flush all the subqueues from the PromptQueue
object, and PromptQueue.Change(),
which applies adjustments of speed and volume to all subqueues on the PromptQueue.
Properties
- status - Read-only. Status code returned by the
speech platform. The status code of 0 indicates a successful completed subqueue
operation by the speech platform, a negative status code indicates an error
on the speech output platform.
Methods
Event Handlers
- onEmpty
- Attribute description:
- This event fires when the last of the prompts in a subqueue have
finished playback. It fires after the oncomplete is fired on the last
prompt of the subqueue (and therefore only fires when the playback
of the prompt subqueue completes naturally without explicit stop calls).
- For prompt queues which are not stopped by other means, there will
be one onempty event for every subqueue, i.e. for every Start() call made.
- Event Object Information:
- Bubbles: No
- To invoke: To invoke Final prompt in prompt subqueue has completed
playback.
- Default action: Set status = 0 if playback completes normally
- onError
- Attribute description:
- The onError event is fired if a serious
or fatal error occurs with the synthesis (voice output) process.
- Since onError on the PromptQueue
object will fire on generic platform errors, playback is stopped on
reception of this event and the subqueue is flushed. (Other queues
held in the PromptQueue object are not affected.)
- For platform errors, a status code of -1 is set; for errors fired
due to Start() being called on an empty subqueue, a
status code of -2 is set, and for Change()
when unsupported, a status code of -3 is set.
- onerror is also fired in telephony profiles as a result of the automatic
call to Flush() on detection of
a disconnect (status -30), or if playback is attempted after a disconnect
event.
- Event Object Information:
- Bubbles: No
- To invoke: The synthesis process experiences a serious or fatal
problem.
- Default action: On encountering an error, status codes are set
as follows:
- status -1: A generic speech output resource
error occurred during playback.
- status -2: the Start() call was made on an empty prompt subqueue.
- status -3: the Change()
call was made, but the platform does not support it.
- status -30: (telephony profiles only)
a disconnect invoked the Flush()
method, or prompt playback was attempted after disconnect.
Examples
This example shows how the PromptQueue is used to ensure
seamless prompt playback across page transitions in an HTML profile:
<html xmlns:salt="http://www.saltforum.org/2002/SALT">
<body>
<form id="form1"
action="nextpage.html">
<input
type="button" onclick="transition();" value="go
to next page" />
</form>
<salt:prompt id="transitionPrompt">
Let's
go to the next page!
</salt:prompt>
<script>
function
transition() {
transitionPrompt.Queue();
PromptQueue.Start();
form1.submit();
}
</script>
</body>
</html>
The prompt will play back during the transition to the next
page, because although the transitionPrompt element itself is destroyed
when the DOM is torn down for the next page, it has been queued onto
the PromptQueue object which is persistent
across pages. Subsequent prompts from the next page will be played once
the transitionPrompt prompt has been played out.
Notice that the transition() function could be replaced by the simple
shorthand transitionPrompt.Start() in the onclick event handler.
|
Certain applications may require not only the content of prompts
to be prefetched, but also the earliest possible queuing of prompts in advance
of playback, in the interests of efficient operation. The following example
shows how individual prompts (or subqueues) which are known to follow the
current prompt can be queued while the current prompt is being played back.
This example shows two prompts which are marked with the prefetch attribute
(to indicate to the browser that their content should be retrieved at an
early opportunity). The first is queued for playback on page load. The second
is queued as soon as the first is scheduled for playback by a click on the
play button, and is itself played back by a click on the next button.
<prompt id="p1" prefetch="true">
<content href="http://mybank/getStockName.asp?id=1"
/>
<content href="http://mybank/getStockValue.asp?id=1"
/>
</prompt>
<prompt id="p2" prefetch="true">
<content href="http://mybank/getStockName.asp?id=2"
/>
<content href="http://mybank/getStockValue.asp?id=2"
/>
</prompt>
<body onload="p1.Queue();">
...
<input type="button" value="play"
onclick="PromptQueue.Start();
p2.Queue();" />
<input type="button"
value="next"
onclick="PromptQueue.Stop();
PromptQueue.Start;"/>
...
</body>
This model can be scaled up to N prompts by ensuring that the next button
always queues the following prompt, by calling the relevant function after
the PromptQueue.Start() call, e.g.:
<input type="button"
value="next"
onclick="PromptQueue.Stop();
PromptQueue.Start();
QueueNextPrompt();" />
where QueueNextPrompt() is a function that decides
which prompt needs to be queued next.
A simpler solution for the case where the ordering of the prompts is known
in advance would be to call Start on each subqueue in sequential order.
That is, not only queue each subqueue but also schedule it for playback
in advance. This permits the queuing of multiple subqueues in advance, and,
in this case, the 'next' functionality would be a simple call to PromptQueue.Stop(),
which has the effect of ceasing playback, flushing the current subqueue,
and allowing the next to begin playback. (This also allows each subqueue
to begin playback immediately after the previous subqueue has finished,
without needing to wire the next Start call to the onempty event handler.) |
Extra info
For details on usage of this element, see the SALT Specification, Version
1.0.