AudioDeviceInfo and AudioDeviceStatus - descriptors for audio devices¶These classes are used to store information about audio devices and their
status. Only a subset of PsychoPy’s sound API currently use these classes, such
as the psychopy.sound.Microphone class.
|
Descriptor for an audio device (playback or recording) on this system. |
|
Descriptor for audio device status information. |
Descriptor for an audio device (playback or recording) on this system.
Properties associated with this class provide information about a specific
audio playback or recording device. An object can be then passed to
Microphone to open a stream using the
device described by the object.
This class is usually instanced only by calling
getDevices(). Users should
avoid creating instances of this class themselves unless they have good
reason to.
deviceIndex (int) – Enumerated index of the audio device. This number is specific to the engine used for audio.
deviceName (str) – Human-readable name of the device.
hostAPIName (str) – Human-readable name of the host API used for audio.
outputChannels (int) – Number of output channels.
outputLatency (tuple) – Low (float) and high (float) output latency in milliseconds.
inputChannels (int) – Number of input channels.
inputLatency (tuple) – Low (float) and high (float) input latency in milliseconds.
defaultSampleRate (int) – Default sample rate for the device in Hertz (Hz).
audioLib (str) – Audio library that queried device information used to populate the
properties of this descriptor (e.g., 'ptb' for Psychtoolbox).
Examples
Get a list of available devices:
import psychopy.sound as sound
recordingDevicesList = sound.Microphone.getDevices()
Get the low and high input latency of the first recording device:
recordingDevice = recordingDevicesList[0] # assume not empty
inputLatencyLow, inputLatencyHigh = recordingDevice.inputLatency
Get the device name as it may appear in the system control panel or sound settings:
deviceName = recordingDevice.deviceName
Specifying the device to use for capturing audio from a microphone:
# get the first suitable capture device found by the sound engine
recordingDevicesList = sound.Microphone.getDevices()
recordingDevice = recordingDevicesList[0]
# pass the descriptor to microphone to configure it
mic = sound.Microphone(device=recordingDevice)
mic.start() # start recording sound
Audio library used to query device information (str).
Create an AudioDevice instance with values populated using a descriptor (dict) returned from the PTB audio.get_devices API call.
desc (dict) – Audio device descriptor returned from Psychtoolbox’s get_devices function.
Audio device descriptor with properties set using desc.
Default sample rate in Hertz (Hz) for this device (int).
Enumerated index (int) of the audio device.
Human-readable name (str) for the audio device reported by the driver.
Human-readable name (str) for the host API.
Number of input channels (int). If >0, this is likely a audio capture device.
Low and high input latency in milliseconds (low, high).
True if this device is suitable for capture (bool).
True if this device is suitable for capture and playback (bool).
True if this device is suitable for playback (bool).
Number of output channels (int). If >0, this is likely a audio playback device.
Low and high output latency in milliseconds (low, high).
Descriptor for audio device status information.
Properties of this class are standardized on the status information returned by Psychtoolbox. Other audio backends should try to populate these fields as best they can with their equivalent status values.
Users should never instance this class themselves unless they have good reason to.
active (bool) – True if playback or recording has started, else False.
state (int) – State of the device, either 1 for playback, 2 for recording or 3 for duplex (recording and playback).
requestedStartTime (float) – Requested start time of the audio stream after the start of playback or recording.
startTime (float) – The actual (real) start time of audio playback or recording.
captureStartTime (float) – Estimate of the start time of audio capture. Only valid if audio capture is active. Usually, this time corresponds to the time when the first sound was captured.
requestedStopTime (float) – Stop time requested when starting the stream.
estimatedStopTime (float) – Estimated stop time given requestedStopTime.
currentStreamTime (float) – Estimate of the time it will take for the most recently submitted sample to reach the speaker. Value is in absolute system time and reported for playback only.
elapsedOutSamples (int) – Total number of samples submitted since the start of playback.
positionSecs (float) – Current stream playback position in seconds this loop. Does not account for hardware of driver latency.
recordedSecs (float) – Total amount of recorded sound data (in seconds) since start of capture.
readSecs (float) – Total amount of sound data in seconds that has been fetched from the internal buffer.
schedulePosition (float) – Current position in a running schedule in seconds.
xRuns (int) – Number of dropouts due to buffer over- and under-runs. Such conditions can result is glitches during playback/recording. Even if the number remains zero, that does not mean that glitches did not occur.
totalCalls (int) – Debug - Used for debugging the audio engine.
timeFailed (float) – Debug - Used for debugging the audio engine.
bufferSize (int) – Debug - Size of the buffer allocated to contain stream samples. Used for debugging the audio engine.
cpuLoad (float) – Amount of load on the CPU imparted by the sound engine. Ranges between 0.0 and 1.0 where 1.0 indicates maximum load on the core running the sound engine process.
predictedLatency (float) – Latency for the given hardware and driver. This indicates how far ahead you need to start the device to ensure is starts at a scheduled time.
latencyBias (float) – Additional latency bias added by the user.
sampleRate (int) – Sample rate in Hertz (Hz) the playback recording is using.
outDeviceIndex (int) – Enumerated index of the output device.
inDeviceIndex (int) – Enumerated index of the input device.
audioLib (str) – Identifier for the audio library which created this status.
True if playback or recording has started (bool).
Identifier for the audio library which created this status (str).
Debug - Size of the buffer allocated to contain stream samples. Used for debugging the audio engine.
Estimate of the start time of audio capture (float). Only valid if audio capture is active. Usually, this time corresponds to the time when the first sound was captured.
Amount of load on the CPU imparted by the sound engine (float). Ranges between 0.0 and 1.0 where 1.0 indicates maximum load on the core running the sound engine process.
Create an AudioDeviceStatus instance using a status descriptor returned by Psychtoolbox.
desc (dict) – Audio device status descriptor.
Audio device descriptor with properties set using desc.
Estimate of the time it will take for the most recently submitted sample to reach the speaker (float). Value is in absolute system time and reported for playback mode only.
Total number of samples submitted since the start of playback (int).
Estimated stop time given requestedStopTime (float).
Enumerated index of the input device (int).
True if this device is operating in capture mode (bool).
True if this device is operating capture and recording mode (bool).
True if this device is operating in playback mode (bool).
Additional latency bias added by the user (float).
Enumerated index of the output device (int).
Current stream playback position in seconds this loop (float). Does not account for hardware of driver latency.
Latency for the given hardware and driver (float). This indicates how far ahead you need to start the device to ensure is starts at a scheduled time.
Total amount of sound data in seconds that has been fetched from the internal buffer (float).
Total amount of recorded sound data (in seconds) since start of capture (float).
Requested start time of the audio stream after the start of playback or recording (float).
Stop time requested when starting the stream (float).
Sample rate in Hertz (Hz) the playback recording is using (int).
Current position in a running schedule in seconds (float).
The actual (real) start time of audio playback or recording (float).
State of the device (int). Either 1 for playback, 2 for recording or 3 for duplex (recording and playback).
Debug - Used for debugging the audio engine (float).
Debug - Used for debugging the audio engine (int).
Number of dropouts due to buffer over- and under-runs (int). Such conditions can result is glitches during playback/recording. Even if the number remains zero, that does not mean that glitches did not occur.