omni.kit.audiodeviceenum module

This module contains bindings to the C++ omni::audio::IAudioDeviceEnum interface. This provides functionality for enumerating available audio devices and collecting some basic information on each one.

Sound devices attached to the system may change at any point due to user activity (ie: connecting or unplugging a USB audio device). When enumerating devices, it is important to collect all device information directly instead of caching it.

The device information is suitable to be used to display to a user in a menu to allow them to choose a device to use by name.

class omni.kit.audiodeviceenum.Direction(self: omni.kit.audiodeviceenum._audio.Direction, arg0: int)None

Bases: pybind11_builtins.pybind11_object

Members:

PLAYBACK : audio playback devices only.

CAPTURE : audio capture devices only.

CAPTURE = Direction.CAPTURE
PLAYBACK = Direction.PLAYBACK
property name

handle) -> str

Type

(self

class omni.kit.audiodeviceenum.IAudioDeviceEnum

Bases: pybind11_builtins.pybind11_object

This interface contains functions for audio device enumeration. This is able to enumerate all audio devices attached to the system at any given point and collect the information for each device. This is only intended to collect the device information needed to display to the user for device selection purposes. If a device is to be chosen based on certain needs (ie: channel count, frame rate, etc), it should be done directly through the audio playback or capture context during creation. This is able to collect information for both playback and capture devices.

All the function in this interface are in omni.kit.audio.IAudioDeviceEnum class. To retrieve this object, use get_audio_device_enum_interface() method:

>>> import omni.kit.audio
>>> dev = omni.kit.audio.get_audio_device_enum_interface()
>>> count = dev.get_device_count(PLAYBACK)
>>> desc = dev.get_device_description(PLAYBACK, 0)
get_device_channel_count(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction, index: int)int

Retrieves the maximum channel count for a requested device.

This retrieves the maximum channel count for a requested device. This count is the maximum number of channels that the device can natively handle without having to trim or reprocess the data. Using a device with a different channel count than its maximum is allowed but will result in extra processing time to upmix or downmix channels in the stream. Note that downmixing channel counts (ie: 7.1 to stereo) will often result in multiple channels being blended together and can result in an unexpected final signal in certain cases.

Parameters
  • dir – the audio direction to get the maximum channel count for.

  • index – the index of the device to retrieve the channel count for. This should be between 0 and one less than the most recent return value of getDeviceCount().

Returns

If successful, this returns the maximum channel count of the requested device.

If the requested device is out of range of those connected to the system, 0 is returned.

get_device_count(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction)int

Retrieves the total number of devices attached to the system of a requested type.

Parameters

dir – the audio direction to get the device count for.

Returns

If successful, this returns the total number of connected audio devices of the requested type.

If there are no devices of the requested type connected to the system, 0 is returned.

get_device_description(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction, index: int)object

Retrieves a descriptive string for a requested audio device.

This retrieves a descriptive string for the requested device. This string is suitable for display to a user in a menu or selection list.

Parameters
  • dir – the audio direction to get the description string for.

  • index – the index of the device to retrieve the description for. This should be between 0 and one less than the most recent return value of getDeviceCount().

Returns

If successful, this returns a python string describing the requested device.

If the requested device is out of range of those connected to the system, this returns None.

get_device_frame_rate(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction, index: int)int

Retrieves the preferred frame rate of a requested device.

This retrieves the preferred frame rate of a requested device. The preferred frame rate is the rate at which the device natively wants to process audio data. Using the device at other frame rates may be possible but would require extra processing time. Using a device at a different frame rate than its preferred one may also result in degraded quality depending on what the processing versus preferred frame rate is.

Parameters
  • dir – the audio direction to get the preferred frame rate for.

  • index – the index of the device to retrieve the frame rate for. This should be between 0 and one less than the most recent return value of getDeviceCount().

Returns

If successful, this returns the preferred frame rate of the requested device.

If the requested device was out of range of those connected to the system, 0 is returned.

get_device_id(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction, index: int)object

Retrieves the unique identifier for the requested device.

Parameters
  • dir – the audio direction to get the device name for.

  • index – the index of the device to retrieve the identifier for. This should be between 0 and one less than the most recent return value of getDeviceCount().

Returns

If successful, this returns a python string containing the unique identifier of the requested device.

If the requested device is out of range of those connected to the system, this returns None.

get_device_name(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction, index: int)object

Retrieves the friendly name of a requested device.

Parameters
  • dir – the audio direction to get the device name for.

  • index – the index of the device to retrieve the name for. This should be between 0 and one less than the most recent return value of getDeviceCount().

Returns

If successful, this returns a python string containing the friendly name of the requested device.

If the requested device is out of range of those connected to the system, this returns None.

get_device_sample_size(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction, index: int)int

Retrieves the native sample size for a requested device.

This retrieves the bits per sample that a requested device prefers to process its data at. It may be possible to use the device at a different sample size, but that would likely result in extra processing time. Using a device at a different sample rate than its native could degrade the quality of the final signal.

Parameters
  • dir – the audio direction to get the native sample size for.

  • index – the index of the device to retrieve the sample size for. This should be between 0 and one less than the most recent return value of getDeviceCount().

Returns

If successful, this returns the native sample size in bits per sample of the requested device.

If the requested device is out of range of those connected to the system, 0 is returned.

get_device_sample_type(self: omni.kit.audiodeviceenum._audio.IAudioDeviceEnum, dir: omni.kit.audiodeviceenum._audio.Direction, index: int) → omni.kit.audiodeviceenum._audio.SampleType

Retrieves the native sample data type for a requested device.

This retrieves the sample data type that a requested device prefers to process its data in. It may be possible to use the device with a different data type, but that would likely result in extra processing time. Using a device with a different sample data type than its native could degrade the quality of the final signal.

Parameters
  • dir – the audio direction to get the native sample data type for.

  • index – the index of the device to retrieve the sample data type for. This should be between 0 and one less than the most recent return value of getDeviceCount().

Returns

If successful, this returns the native sample data type of the requested device.

If the requested device is out of range of those connected to the system, UNKNOWN is returned.

class omni.kit.audiodeviceenum.SampleType(self: omni.kit.audiodeviceenum._audio.SampleType, arg0: int)None

Bases: pybind11_builtins.pybind11_object

Members:

UNKNOWN : could not determine the same type or an invalid device index.

PCM_SIGNED_INTEGER : signed integer PCM samples.

PCM_UNSIGNED_INTEGER : unsigned integer PCM samples.

PCM_FLOAT : single precision floating point PCM samples.

COMPRESSED : a compressed sample format.

COMPRESSED = SampleType.COMPRESSED
PCM_FLOAT = SampleType.PCM_FLOAT
PCM_SIGNED_INTEGER = SampleType.PCM_SIGNED_INTEGER
PCM_UNSIGNED_INTEGER = SampleType.PCM_UNSIGNED_INTEGER
UNKNOWN = SampleType.UNKNOWN
property name

handle) -> str

Type

(self

omni.kit.audiodeviceenum.acquire_audio_device_enum_interface(plugin_name: str = None, library_path: str = None) → omni::audio::IAudioDeviceEnum
omni.kit.audiodeviceenum.get_audio_device_enum_interface() → omni.kit.audiodeviceenum._audio.IAudioDeviceEnum

helper method to retrieve a cached version of the IAudioDeviceEnum interface.

Returns

The cached omni.kit.audiodeviceenum.IAudioDeviceEnum interface. This will only be retrieved on the first call. All subsequent calls will return the cached interface object.