Package org.jitsi.impl.neomedia.device

Class WASAPISystem

  • public class WASAPISystem
extends AudioSystem
    Implements an AudioSystem using Windows Audio Session API (WASAPI) and related Core Audio APIs such as Multimedia Device (MMDevice) API.
    Author:
    Lyubomir Marinov

    • Field Detail

      • DEFAULT_DEVICE_PERIOD

        public static final long DEFAULT_DEVICE_PERIOD
        The default interval in milliseconds between periodic processing passes by the audio engine.
        See Also:
        Constant Field Values

    • Method Detail

      • CoInitializeEx

        public static int CoInitializeEx()
                          throws HResultException
        Invokes the Windows API function CoInitializeEx (by way of WASAPI.CoInitializeEx(long, int)) with arguments suitable to the operation of WASAPIRenderer, WASAPIStream and WASAPISystem.

        Generally, the WASAPI integration is designed with COINIT_MULTITHREADED in mind. However, it may turn out that it works with COINIT_APARTMENTTHREADED as well.

        Returns:
        the value returned by the invocation of the Windows API function CoInitializeEx
        Throws:
        HResultException - if the invocation of the method WASAPI.CoInitializeEx throws such an exception

      • getFormatsToInitializeIAudioClient

        public static javax.media.format.AudioFormat[] getFormatsToInitializeIAudioClient​(javax.media.format.AudioFormat format)
        Gets an array of alternative AudioFormats based on format with which an attempt is to be made to initialize a new IAudioClient instance.
        Parameters:
        format - the AudioFormat on which the alternative AudioFormats are to be based
        Returns:
        an array of alternative AudioFormats based on format with which an attempt is to be made to initialize a new IAudioClient instance

      • getSampleSizeInBytes

        public static int getSampleSizeInBytes​(javax.media.format.AudioFormat format)
        Gets the size in bytes of an audio sample of a specific AudioFormat.
        Parameters:
        format - the AudioFormat to get the size in bytes of an audio sample of
        Returns:
        the size in bytes of an audio sample of the specified format

      • WAVEFORMATEX_fill

        public static void WAVEFORMATEX_fill​(long waveformatex,
                                     javax.media.format.AudioFormat audioFormat)
        Sets the fields of a specific WAVEFORMATEX instance from a specific AudioFormat instance so that the two of them are equivalent in terms of the formats of audio data that they describe.
        Parameters:
        waveformatex - the WAVEFORMATEX instance to set the fields of from the specified audioFormat
        audioFormat - the AudioFormat instance to set the fields of the specified waveformatex from

      • doInitialize

        protected void doInitialize()
                     throws Exception
        Invoked by DeviceSystem.initialize() to perform the very logic of the initialization of this DeviceSystem. This instance has been prepared for initialization by an earlier call to DeviceSystem.preInitialize() and the initialization will be completed with a subsequent call to DeviceSystem.postInitialize().
        Specified by:
        doInitialize in class DeviceSystem
        Throws:
        Exception - if an error occurs during the initialization of this instance. The initialization of this instance will be completed with a subsequent call to postInitialize() regardless of any Exception thrown by doInitialize().

      • getAECSupportedFormats

        public List<javax.media.format.AudioFormat> getAECSupportedFormats()
        Gets the List of AudioFormats supported by the voice capture DMO that supports/implements the acoustic echo cancellation (AEC) feature.

        If an AudioFormat instance contained in the returned List is one of the formats of a CaptureDeviceInfo2 or the supportedFormats of a FormatControl associated with a WASAPI CaptureDevice/DataSource or SourceStream, it signals that the AudioFormat in question has been included in that formats or supportedFormats only because it is supported by the voice capture DMO supporting/implementing the acoustic echo cancellation (AEC) feature.

        Returns:
        the List of AudioFormats supported by the voice capture DMO that supports/implements the acoustic echo cancellation (AEC) feature

      • getIMMDevice

        public long getIMMDevice​(String id)
                  throws HResultException
        Gets an audio endpoint device that is identified by a specific endpoint ID string.
        Parameters:
        id - the endpoint ID string which identifies the audio endpoint device to be retrieved
        Returns:
        an IMMDevice instance which represents the audio endpoint device that is identified by the specified endpoint ID string
        Throws:
        HResultException - if an error occurs while retrieving the audio endpoint device that is identified by the specified endpoint ID string in a native WASAPI function which returns an HRESULT value

      • getIMMDeviceDataFlow

        public int getIMMDeviceDataFlow​(long iMMDevice)
                         throws HResultException
        Gets the data flow of a specific IMMDevice in the form of an EDataFlow value.
        Parameters:
        iMMDevice - the IMMDevice to get the data flow of
        Returns:
        an EDataFlow value which represents the data flow of the specified IMMDevice
        Throws:
        HResultException - if an error occurs while retrieving the data flow of the specified iMMDevice in a native WASAPI function which returns an HRESULT value

      • getIMMDeviceIndex

        public int getIMMDeviceIndex​(String id,
                             int dataFlow)
                      throws HResultException
        Gets the zero-based index within the IMMDeviceCollection interface of an audio endpoint device specified by an endpoint ID string.
        Parameters:
        id - the endpoint ID string which specifies the audio endpoint device whose zero-based index within the IMMDeviceCollection interface is to be retrieved
        Returns:
        the zero-based index within the IMMDeviceCollection interface of an audio endpoint device identified by the specified endpoint ID string if the specified endpoint ID string identifies an actual audio endpoint device within the IMMDeviceCollection interface; otherwise, -1
        Throws:
        HResultException - if an error occurs while determining the zero-based index within the IMMDeviceCollection interface of the audio endpoint device identified by the specified endpoint ID string in a native WASAPI function which returns an HRESULT value

      • getRendererClassName

        protected String getRendererClassName()
        Gets the name of the class which implements the Renderer interface to render media on a playback or notification device associated with this DeviceSystem.
        Overrides:
        getRendererClassName in class DeviceSystem
        Returns:
        the name of the class which implements the Renderer interface to render media on a playback or notification device associated with this DeviceSystem or null if no Renderer instance is to be created by the DeviceSystem implementation or createRenderer(boolean) is overridden.

      • initializeAEC

        public long initializeAEC()
                   throws Exception
        Initializes a new IMediaObject instance which represents a Voice Capture DSP implementing acoustic echo cancellation (AEC).
        Returns:
        a new IMediaObject instance which represents a Voice Capture DSP implementing acoustic echo cancellation (AEC)
        Throws:
        Exception - if initializing the new instance fails

      • initializeIAudioClient

        public long initializeIAudioClient​(javax.media.MediaLocator locator,
                                   AudioSystem.DataFlow dataFlow,
                                   int streamFlags,
                                   long eventHandle,
                                   long hnsBufferDuration,
                                   javax.media.format.AudioFormat[] formats)
                            throws HResultException
        Initializes a new IAudioClient instance for an audio endpoint device identified by a specific MediaLocator. The initialization is performed to an extent suitable for the operation of WASAPIRenderer and WASAPIStream.
        Parameters:
        locator - a MediaLocator which identifies the audio endpoint device to initialize a new IAudioClient instance for
        dataFlow - the flow of media data to be supported by the audio endpoint device identified by the specified locator
        streamFlags -
        eventHandle -
        hnsBufferDuration - the base of the duration in milliseconds of the buffer that the audio application will share with the audio engine. If Format.NOT_SPECIFIED, the method uses the default interval between periodic passes by the audio engine.
        formats - an array of alternative AudioFormats with which initialization of a new IAudioClient instance is to be attempted. The first element of the formats array which is supported by the new IAudioClient instance is used to initialize it and any preceding elements are set to null to signify that they are not supported and to make it possible to retrieve the AudioFormat with which the new IAudioClient instance has been initialized.
        Returns:
        a new IAudioClient instance initialized for the audio endpoint device identified by the specified locator
        Throws:
        HResultException - if an error occurs while initializing a new IAudioClient for the audio endpoint device identified by the specified locator in a native WASAPI function which returns an HRESULT value

      • postInitialize

        protected void postInitialize()
                       throws Exception
        Invoked as part of the execution of DeviceSystem.initialize() after the execution of DeviceSystem.doInitialize() regardless of whether the latter completed successfully. The implementation of DeviceSystem fires a new PropertyChangeEvent to notify that the value of the property DeviceSystem.PROP_DEVICES of this instance may have changed i.e. that the list of devices detected by this instance may have changed. Because AudioSystem may support playback and notification audio devices apart from capture audio devices, fires more specific PropertyChangeEvents than DeviceSystem
        Overrides:
        postInitialize in class AudioSystem
        Throws:
        Exception

      • toString

        public String toString()
        Returns a human-readable representation of this DeviceSystem. The implementation of DeviceSystem returns the protocol of the MediaLocators of the CaptureDeviceInfos (to be) registered by this DeviceSystem.
        Overrides:
        toString in class DeviceSystem
        Returns:
        a String which represents this DeviceSystem in a human-readable form