Media Guidelines

This section describes guidelines and tips for developers of applications that work with audio media.

• The Close() method on a WmaFileSource object must be called after the application is finished with this object. If Close is not called, the underlying unmanaged object will not be disposed, causing a memory leak for the application.

• Audio clipping can sometimes occur when an application plays media for a call between the application and a remote endpoint. To prevent this from occurring, the application should ensure that the value of the State property on AudioVideoCall is Established and that the value of the State property on AudioVideoFlow is Active before it starts the Player.

• An application that plays a media file located on a network share should use Buffered mode (a value of the MediaSourceBufferedMode enumeration) with BeginPrepareSource(MediaSourceOpenMode, AsyncCallback, Object). Otherwise, if the network share is disconnected while a Player object is playing the file, the engine thread that is handling the call will be blocked and the call will terminate due to a time-out. The time-out also disconnects any other calls within this engine thread.

• An application that interoperates with endpoints that use this hold syntax—c=IN IP4 0.0.0.0—to perform a hold operation, should verify that the value of the State property on the AudioVideoFlow object is Active, and that the value of the Enabled property on an AudioChannel instance is true prior to performing any recording operation.

• An application that expects a remote endpoint to place a call on hold using this syntax—c=IN IP4 0.0.0.0—while recording audio, should ensure that the file length (the Duration property on WmaFileSource) reflects the actual recorded audio length. To do so, the application should perform the following check in its handler for the ConfigurationChanged event.

  Check the Enabled property on the AudioChannel instance.

  • If the value is false, pause the recorder by calling the Pause() method on the Recorder instance.

  • If the value is true, restart the recorder by calling the Start() method on the Recorder instance.

• An application that expects a remote endpoint to place a call on hold using this syntax—c=IN IP4 0.0.0.0—while playing audio, can either pause the audio while the call is on hold, or continue playing the audio while the call is on hold. To ensure that when the call resumes, the audio played to the remote endpoint starts at the correct position, an application should perform one of the following actions.

  • The application intends to pause the audio file while the call is on hold.

    In the handler for the ConfigurationChanged event, the application should call the Pause() method on the Player instance if the value of the Enabled property on the AudioChannel instance is false (call placed on hold). If the value of the Enabled property is true (call resumed), the application should call the Start() method on the Player instance.

  • The application intends to continue playing the audio file while the call is on hold.

    In the handler for the ConfigurationChanged event, the application should call the Stop() method on the Player instance if the value of the Enabled property is false (call placed on hold). If the value of the Enabled property is true (call resumed), the application should calculate the length of time the call was on hold (in milliseconds), and skip forward in the audio file, using the Skip(Int32) method on the Player instance.