AudioVideoFlow

An AudioVideoFlow instance represents a media connection with a single remote participant.

AudioVideoFlow Properties

The Audio property provides access to an AudioControl instance, which provides access to the audio channel and can be used such purposes as muting and unmuting the audio channel, changing the sampling rate, and changing the direction. The Player property provides access to a Player instance, which can be used to play audio data captured previously. The Recorder property provides access to a Recorder instance, which can be used to record audio and video data. The SpeechRecognitionConnector property provides access to a SpeechRecognitionConnector instance, which can be used in conjunction with the Microsoft.Speech namespace to perform speech recognition. The SpeechSynthesisConnector property provides access to a SpeechSynthesisConnector instance, which can be used in conjunction with the Microsoft.Speech namespace to render text as speech. The ToneController property provides access to a ToneController instance. A ToneController can be used to send and receive Dual-Tone Multiple-Frequency (DTMF) tones and to receive Fax tones.

The Player, Recorder, ToneController, SpeechRecognitionConnector, and SpeechSynthesisConnector properties are considered to be devices. Although these devices are represented as properties on the AudioVideoFlow class, they are not automatically instantiated. Before any of these devices can be used, it must be created, and then attached to an AudioVideoFlow instance. The following code example shows the steps required to create a Player and attach it to an existing AudioVideoFlow instance.

Player myPlayer = new Player();
myPlayer.AttachFlow(avFlow);

When the device is no longer needed, the AudioVideoFlow instance that is attached to the device must be detached, as this does not happen automatically. The following sample shows how this is done.

	myPlayer.DetachFlow(avFlow);

For more information about these devices, see Devices in UCMA.

AudioVideoFlow Methods

An application that intends to configure the AudioVideoFlow by using Initialize(AudioVideoFlowTemplate) must process the AudioVideoFlowConfigurationRequested event synchronously. AudioVideoFlowConfigurationRequested is an AudioVideoCall event. The application can assume that the AudioVideoFlow State will not change from Idle during the event callback, so no state check is necessary. Only an invalid template configuration can possibly cause Initialize to throw an exception.

Sampling Rate Enhancements

In Microsoft Unified Communications Managed API (UCMA) 3.0, new properties have been added to the classes related to the AudioVideoFlow class: the AudioChannelTemplate and AudioChannel classes. These properties enable an application to specify the sampling rate in either stream direction (send or receive).

Negotiation Between Local and Remote Endpoints

After an AudioVideoFlow instance has been initialized or modified, negotiation with the remote participant is carried out. Settings such as HoldStatus and AllowedDirection on the remote endpoint can affect the resulting AudioVideoFlow settings. For example, if the application sets AllowedDirection to MediaChannelDirection.SendReceive, but the remote has previously set AllowedDirection to MediaChannelDirection.SendOnly, the Direction setting on the local endpoint will become MediaChannelDirection.ReceiveOnly.

The following steps show the values of AllowedDirection, Direction, and HoldStatus after negotiations have finished.

1. The local endpoint sets AllowedDirection to MediaChannelDirection.SendReceive, and HoldStatus is HoldType.None. On the remote endpoint, AllowedDirection = MediaChannelDirection.SendOnly.

   Result: Direction on the local endpoint will be set to MediaChannelDirection.ReceiveOnly.

2. The local endpoint applies a hold to both ends, using a call to BeginHold(HoldType.BothEndpoints, , ).

   Results: AllowedDirection is MediaChannelDirection.SendReceive, HoldStatus is set to HoldType.BothEndpoints, and Direction on the local endpoint will be set to MediaChannelDirection.Inactive.

3. The local endpoint removes the hold, using a call to BeginRetrieve.

   Results: AllowedDirection is MediaChannelDirection.SendReceive, HoldStatus is set to HoldType.None, and Direction on the local endpoint will depend on the response from the remote endpoint. If the remote endpoint responds with MediaChannelDirection.SendReceive, then Direction will be set to MediaChannelDirection.SendReceive. If the remote endpoint responds with MediaChannelDirection.SendOnly (as in step 1), then Direction on the local endpoint will be set to MediaChannelDirection.ReceiveOnly.

In negotiation with a remote endpoint, if the local endpoint sends an offer that places a restriction on the media flow by a change in the direction or by placing a hold, it does not matter if the remote endpoint rejects the offer. On the other hand, if the local endpoint sends an offer that removes existing restrictions, it waits for the remote endpoint to accept or reject the offer.

Operations that mute a media flow do not require negotiation.

AudioVideoFlow State Transitions

The AudioVideoFlow state transitions are shown in the following illustration.

1. The transition from Idle to Active occurs when the AudioVideoFlow instance determines that media can now be exchanged (or should be able to be exchanged) with the remote peer. The most common causes for this transition are:

   • Media (RTP or RTCP) is received from the remote peer.

   • For an incoming call, acknowledgement from the caller that it has received a provisional acceptance of the call (by the application calling BeginEstablishEarlyMedia()). That is, a SIP PRACK message is received from the caller.

   • Special case: The remote endpoint negotiates the audio channel to be disabled. Disabled media means that no transport connection will be established; in SDP, the media is identified with a ‘c=IN IP4 0.0.0.0’ connection address line.

2. The transition from Active to Terminated occurs when a call ends after the media session is established. The most common causes for this transition are:

   • One of the endpoints terminates the call.

   • The media session fails due to loss of media (for example, an RTP timeout).

   • An unrecoverable error (for example, a SIP timeout) occurs during a renegotiation (re-INVITE) request sent to the remote peer.

3. The transition from Idle to Terminated occurs when there is a failure in establishing the call. The most common causes for this transition are:

   • The call is rejected.

   • There is a failure in the offer/answer negotiation (for example, a failure to negotiate encryption parameters (SRTP)).

   • The application terminates the call before the media session is established.

   • The media session fails to establish a working transport connection between endpoints.