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.Microphone class.

Overview

AudioDeviceInfo([deviceIndex, deviceName, ...])

Descriptor for an audio device (playback or recording) on this system.

AudioDeviceStatus([active, state, ...])

Descriptor for audio device status information.

Details

class psychopy.sound.AudioDeviceInfo(deviceIndex=-1, deviceName='Null Device', hostAPIName='Null Audio Driver', outputChannels=0, outputLatency=(0.0, 0.0), inputChannels=0, inputLatency=(0.0, 0.0), defaultSampleRate=48000, audioLib='')[source]

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.

Parameters:

  • 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
property audioLib

Audio library used to query device information (str).

static createFromPTBDesc(desc)[source]

Create an AudioDevice instance with values populated using a descriptor (dict) returned from the PTB audio.get_devices API call.

Parameters:

desc (dict) – Audio device descriptor returned from Psychtoolbox’s get_devices function.

Returns:

Audio device descriptor with properties set using desc.

Return type:

AudioDeviceInfo

property defaultSampleRate

Default sample rate in Hertz (Hz) for this device (int).

property deviceIndex

Enumerated index (int) of the audio device.

property deviceName

Human-readable name (str) for the audio device reported by the driver.

property hostAPIName

Human-readable name (str) for the host API.

property inputChannels

Number of input channels (int). If >0, this is likely a audio capture device.

property inputLatency

Low and high input latency in milliseconds (low, high).

property isCapture

True if this device is suitable for capture (bool).

property isDuplex

True if this device is suitable for capture and playback (bool).

property isPlayback

True if this device is suitable for playback (bool).

property outputChannels

Number of output channels (int). If >0, this is likely a audio playback device.

property outputLatency

Low and high output latency in milliseconds (low, high).

class psychopy.sound.AudioDeviceStatus(active=0, state=0, requestedStartTime=0.0, startTime=0.0, captureStartTime=0.0, requestedStopTime=0.0, estimatedStopTime=0.0, currentStreamTime=0.0, elapsedOutSamples=0, positionSecs=0.0, recordedSecs=0.0, readSecs=0.0, schedulePosition=0.0, xRuns=0, totalCalls=0, timeFailed=0, bufferSize=0, cpuLoad=0.0, predictedLatency=0.0, latencyBias=0.0, sampleRate=44100, outDeviceIndex=0, inDeviceIndex=0, audioLib='Null Audio Library')[source]

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.

Parameters:

  • 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.

property active

True if playback or recording has started (bool).

property audioLib

Identifier for the audio library which created this status (str).

property bufferSize

Debug - Size of the buffer allocated to contain stream samples. Used for debugging the audio engine.

property captureStartTime

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.

property cpuLoad

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.

static createFromPTBDesc(desc)[source]

Create an AudioDeviceStatus instance using a status descriptor returned by Psychtoolbox.

Parameters:

desc (dict) – Audio device status descriptor.

Returns:

Audio device descriptor with properties set using desc.

Return type:

AudioDeviceStatus

property currentStreamTime

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.

property elapsedOutSamples

Total number of samples submitted since the start of playback (int).

property estimatedStopTime

Estimated stop time given requestedStopTime (float).

property inDeviceIndex

Enumerated index of the input device (int).

property isCapture

True if this device is operating in capture mode (bool).

property isDuplex

True if this device is operating capture and recording mode (bool).

property isPlayback

True if this device is operating in playback mode (bool).

property latencyBias

Additional latency bias added by the user (float).

property outDeviceIndex

Enumerated index of the output device (int).

property positionSecs

Current stream playback position in seconds this loop (float). Does not account for hardware of driver latency.

property predictedLatency

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.

property readSecs

Total amount of sound data in seconds that has been fetched from the internal buffer (float).

property recordedSecs

Total amount of recorded sound data (in seconds) since start of capture (float).

property requestedStartTime

Requested start time of the audio stream after the start of playback or recording (float).

property requestedStopTime

Stop time requested when starting the stream (float).

property sampleRate

Sample rate in Hertz (Hz) the playback recording is using (int).

property schedulePosition

Current position in a running schedule in seconds (float).

property startTime

The actual (real) start time of audio playback or recording (float).

property state

State of the device (int). Either 1 for playback, 2 for recording or 3 for duplex (recording and playback).

property timeFailed

Debug - Used for debugging the audio engine (float).

property totalCalls

Debug - Used for debugging the audio engine (int).

property xRuns

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.


Back to top