Note

Please see Azure Cognitive Services for Speech documentation for the latest supported speech solutions.

Browser Class (Microsoft.Speech)

The platform-independent Browser class is one of two classes in the Microsoft.Speech.VoiceXml namespace; the other class is Browser.CallProxy. Browser is an abstract class that is intended only to be a base class from which to derive platform-specific classes. The Browser class cannot be used directly.

Currently, the only class derived from the Browser class is the Browser class in the Microsoft.Rtc.Collaboration.AudioVideo.VoiceXml namespace, which is implemented in the Unified Communications Managed API (UCMA) 3.0 environment. The Browser class in the Microsoft.Rtc.Collaboration.AudioVideo.VoiceXml namespace can make use of any of the public members of the Browser class in the Microsoft.Speech.VoiceXml namespace, in addition to the members of the Microsoft.Speech.VoiceXml.Common namespace.

For a complete listing and description of all the public and protected members of the Browser class, see Browser.

Overview

The Browser provides access to functionality that allows callers to communicate with a VoiceXML application. The Browser processes the elements in a VoiceXML document using the VoiceXML interpreter in the VoiceXML runtime. An active instance of a Browser also provides access to system functionality, including speech synthesis and audio playback to present information to a caller, speech recognition and DTMF tone detection to collect information from a caller, and a recorder to capture and store the audio from a call.

Creating and Controlling the Browser State

You can use the default constructor in the Browser class to create a Browser instance in any derived class.

After a Browser has been instantiated, you can use methods that control the Browser’s state. These methods instruct the Browser to begin interpreting a VoiceXML document or to stop interpreting a VoiceXML document. A property on the Browser object gives the current state of the Browser session.

The arguments of the Browser’s Run(Uri, CookieContainer) and RunAsync(Uri, CookieContainer) methods reference the URI of the VoiceXML start page to interpret, and a CookieContainer object. The CookieContainer object stores information about the session that can be used by the Web server that serves the VoiceXML documents.

You can run a Browser instance in either synchronous or asynchronous mode.

Note

Only use the synchronous Run(Uri, CookieContainer) method for prototyping and experimentation. Do not use it in a production application.

After launching in asynchronous mode, the Browser generates events during a VoiceXML session that inform the hosting .NET application about the status of phone calls and the state of the Browser session.

When initiated, the Run(Uri, CookieContainer) and RunAsync(Uri, CookieContainer) methods detect whether the Browser instance is already running, and perform one of the following actions:

  • If the Browser instance is running, throw an InvalidOperationException.

  • If the Browser instance is not running, set the value of State to Active, and launch a Browser instance.

The hosting .NET application can terminate a Browser session by calling the StopAsync() method. The StopAsync() method allows the Browser to finish processing the current element before ending the session.

The StopAsync() method sets the value of State to Idle, freeing the Browser instance for use in a new session.

When a session is finished, the Browser instance can be reused or disposed.

Setting a Browser’s Input and Output

The Browser class includes methods that a hosting.NET application can use to specify audio inputs and outputs for a VoiceXML session. These methods are only useful for authoring a new Browser class that derives from Browser. Developers who will use an existing Browser implementation, such as the Browser in the Microsoft.Rtc.Collaboration.AudioVideo.VoiceXml namespace, cannot make use of methods described below that specify a Browser’s inputs and outputs.

Before launching an instantiated Browser instance to run against a VoiceXML document, the hosting .NET application sets the audio inputs and outputs that will be required to process an automated interaction with a caller during a session.

The media properties of the Browser class are implemented as method calls rather than as public property sets. These methods inform the Browser instance about the source of input audio received from the caller (for speech recognition or recording) and the destination for output audio (from speech synthesis or playback) that the caller will hear.

Input can come from an audio stream, the default audio device, the null device (no input), a Waveform audio (.WAV) format file, or a stream that contains Waveform audio-format data. Output can go to an audio stream, the default audio device, the null device (no output), a Waveform audio (.WAV) format file, or a stream that contains Waveform audio-format data.

Note

Calling any of the methods that set audio inputs and outputs while a Browser instance is running, that is, when the value of State equals Active, will result in an InvalidOperationException.

Browser Events

A .NET application registers to receive notification of the events raised during asynchronous Browser sessions. Events inform the hosting .NET application about the current state and type of a phone call transfer, the state of a request to disconnect from a VoiceXML document and the result of the request, and the state of a Browser session.

To receive event notification, a .NET application creates an event handler delegate that identifies the event handler, and adds the delegate instance to the event on the Browser instance. In the following example, a delegate that identifies the HandleDisconnecting event handler is added to the Disconnecting event of the VoiceXML Browser (vxb).

vxb.Disconnecting += new EventHandler<DisconnectingEventArgs>(HandleDisconnecting); 

See VoiceXML.Common Namespace (Microsoft.Speech) for information about the enumerated types and EventArgs classes that are associated with Browser events.