Audio Out

class audioOut.AudioOut

Bases: Schedule

Class which implements the AUDIO features.

Any device which has Audio OUT should implement this class. It contains all the necessary methods to use the audio outputs of a VPIxx device.

beep(volume=0.5, time=1, frequency=40000)

Beep bop beep bop bop beep beep beep.

Parameters:

volume (float) – Value between 0 and 1 of the desired volume.
time (int) – Time factor for the beep duration.

getBaseAddress()

Gets the Ram buffer start address.

This method allows the user to get the RAM buffer start address used in schedules. It should only be used if the user wants the schedules to wrap when it has reached its maximum size. When schedules are expected to wrap, the user should also use setBufferSize()

Returns:	Any value in a range of 0 up to the RAM size.
Return type:	int

getBaseAddressAux()

Gets the Ram buffer start address.

This method allows the user to get the RAM buffer start address used in schedules. It should only be used if the user wants the schedules to wrap when it has reached its maximum size. When schedules are expected to wrap, the user should also use setBufferSize().

Returns:	Any value in a range of 0 up to the RAM size.
Return type:	int

getBufferSize()

Gets the Ram buffer size.

This method allows the user to get the RAM buffer size used in schedules.

Returns:	Any value in a range of 0 up to the RAM size.
Return type:	int

getBufferSizeAux()

Gets the Ram buffer size.

This method allows the user to get the RAM buffer size used in schedules.

Returns:	Any value in a range of 0 up to the RAM size.
Return type:	int

getCodecSpeakerLeftVolume(unit)

Gets the current speaker volume of the left channel.

Parameters:	unit (float) – 0 for linear or 1 for dB.
Returns:	Range 0 to 1.
Return type:	float

getCodecSpeakerRightVolume(unit=0)

Gets the current speaker volume of the right channel.

Parameters:	unit (float) – 0 for linear or 1 for dB.
Returns:	Range 0 to 1.
Return type:	float

getCodecSpeakerVolume(unit)

Gets the current speaker volume of the right and left channel.

Parameters:	unit (float) – 0 for linear or 1 for dB.
Returns:	[left Speaker Volume, Right speaker Volume]
Return type:	A tuple containing floats

getCodecVolume(unit=0)

Gets the current codec volume of the right channel.

Parameters:	unit (int) – Set non-zero to return the gain in dB. Defaults to 0.
Returns:	Range 0 to 1.
Return type:	float

getCodecVolumeLeft(unit=0)

Gets the current codec volume of the left channel.

Parameters:	unit (int) – Set non-zero to return the gain in dB. Defaults to 0.
Returns:	Range 0 to 1.
Return type:	float

getCodecVolumeRight(unit=0)

Gets the current codec volume of the right channel.

Parameters:	unit (int) – Set non-zero to return the gain in dB. Defaults to 0.
Returns:	Range 0 to 1.
Return type:	float

getGroupDelay(sample_rate)

Gets the CODEC Audio OUT group delay in seconds.

Returns:	delay in seconds.
Return type:	float

getLeftRightMode()

Gets the audio schedule update mode.

Returns:

Any of the following predefined constants.

mono : Left schedule data goes to left and right channels.
left : Each schedule data goes to left channel only.
right : Each schedule data goes to right channel only.
stereo1 : Pairs of Left data are copied to left/right channels.
stereo2 : Left data goes to left channel, Right data goes to right.

Return type:

String

See also

setScheduleBufferMode

getReadAddress()

Gets the Ram buffer read address.

This method allows the user to get the RAM buffer read address used in schedules.

Returns:	Any value in a range of 0 up to the RAM size.
Return type:	int

getReadAddressAux()

Gets the Ram buffer read address.

This method allows the user to get the RAM buffer read address used in schedules.

Returns:	Any value in a range of 0 up to the RAM size.
Return type:	int

getScheduleCount()

Gets the schedule count value.

This method allows the user to get the current count for a schedule.

Returns:	Any positive value equal or greater to 0.
Return type:	int

getScheduleCountAux()

Gets the schedule count value.

This method allows the user to get the current count for a schedule.

Returns:	Any positive value equal or greater to 0.
Return type:	int

getScheduleOnset()

Gets the schedule onset value.

This method allows the user to get the schedule onset value used in schedules. The onset represents a nanosecond delay between schedule start and first sample.

Returns:	Any positive value equal or greater to 0.
Return type:	int

getScheduleOnsetAux()

Gets the schedule onset value.

This method allows the user to get the schedule onset value used in schedules. The onset represents a nanosecond delay between schedule start and first sample.

Returns:	Any positive value equal or greater to 0.
Return type:	int

getScheduleRate()

Gets the schedule rate value.

This method allows the user to get the schedule rate value used in schedules. The rate represents the speed at which the schedule updates.

Returns:	Any positive value equal or greater to 0.
Return type:	int

getScheduleRateAux()

Gets the schedule rate value.

This method allows the user to get the schedule rate value used in schedules. The rate represents the speed at which the schedule updates.

Returns:	Any positive value equal or greater to 0.
Return type:	int

getScheduleRunningState()

Gets the schedule state for the subsystem.

Returns:	“running” if a schedule is currently running, “stopped” otherwise.
Return type:	schedule_state (str)

getScheduleRunningStateAux()

Gets the schedule state for the subsystem.

Returns:	“running” if a schedule is currently running, “stopped” otherwise.
Return type:	schedule_state (str)

getScheduleUnit()

Gets the schedule unit value.

This method allows the user to get the schedule unit value used in schedules.

Returns:	Any positive value equal or greater to 0.
Return type:	int

See also

getScheduleRate, setScheduleRate

getScheduleUnitAux()

Gets the schedule unit value.

This method allows the user to get the schedule unit value used in schedules.

Returns:	Any positive value equal or greater to 0.
Return type:	int

getVolume()

Gets volume for both Left/Right audio channels

Returns:	[left Speaker Volume, Right speaker Volume]
Return type:	A tuple containing floats

getVolumeLeft(): Get volume for the Left audio output channel, range 0-1

getVolumeRight(): Get volume for the Right audio output channel, range 0-1

initializeCodec(): This needs to be called once to configure initial audio CODEC state.

isCountDownEnabled()

Verifies the schedule countdown mode.

Returns:	True if the schedule is decrementing at every sample, False otherwise.
Return type:	enable (Bool)

isCountDownEnabledAux()

Verifies the schedule countdown mode.

Returns:	True if the schedule is decrementing at every sample, False otherwise.
Return type:	enable (Bool)

isScheduleRunning()

Verifies if a schedule is currently running on the subsystem.

Returns:	True if a schedule is currently running, False otherwise.
Return type:	schedule_running (Bool)

isScheduleRunningAux()

Verifies if a schedule is currently running on the subsystem.

Returns:	True if a schedule is currently running, False otherwise.
Return type:	schedule_running (Bool)

playAudio(bufferData, bufferAddress=0, numBufferFrames=None, volume=0.2, scheduleOnset=0.0, lrMode='mono', scheduleRate=48000, maxScheduleFrames=None)

Encapsulates all necessary lipdpx functinality required to play an audio stimulus with a single function call, while offering more argument flexibility than Datapixx.mex:

-bufferData can be any data type, so long as it can be casted to a NumPy (dtype=float) ndarray of shape (N,), (1,N), or (2,N) -maxSchedule is optional. default behavior is a single playthrough -lrMode can be either an integer or string (see below)

NOTE: this function invokes _libdpx.DPxUpdateRegCache()

This function does not perform argument integrity checks (except for ‘volume’), as these checks are performed in functions DPxWriteAudioBuffer() and DPxSetAudioSchedule() called by DPxPlayAudio()

Parameters:

bufferData (list/array) – can be a list or a NumPy array. If a list, must be castable to NumPy ndarray of type float
bufferAddress (int) – memory location in DATAPixx RAM. default=0
numBufferFrames (int) – number of audio samples written into DATAPixx RAM. NOTE: these are specified in bytes, while the data format is int16. therefore, numBufferFrames = len(bufferData)*2 default=len(bufferData)*2
volume (float/int) – the audio output volume, between 0 (no output) and 1 (full volume)
scheduleOnset (float) – the audio schedule delay in seconds
lrMode (int/string) –
the audio stereo mode. acceptable inputs are in the ‘int’ and ‘string’ columns: int string description 0 ‘mono’ same output to left and right speakers 1 ‘left’ output to left speaker only 2 ‘right’ output to right speaker only 3 ‘stereo1’ 1st row of ‘bufferData’ to left speaker. 2nd row of ‘bufferData’ to right speaker. 4 ‘stereo2’ vice-versa of stereo1 mode
default=’mono’
scheduleRate (int) – the audio codec sampling rate in Hz default = 48000 (CD standard)
maxScheduleFrames (int) – the number of samples after which the audio codec stops sampling. if maxScheduleFrames > numBufferFrames, the audio codec loops back to sample data at the start address of the audio buffer. default = len(bufferData)*2

Exceptions:

volume is not of type float or type int. warning when volume is not in the interval (0,1)

setAudSched(onset, rateValue, rateUnits, count)

Sets AUD schedule onset, count and rate.

This function is a shortcut which assigns Onset/Rate/Count. If Count > 0, enables Countdown mode.

Parameters:

onset (int) – Schedule onset.
rateValue (int) – Rate value.
rateUnits (string) – Usually hz. Can also be video to update every rateValue video frames or nano to update every rateValue nanoseconds.
count (int) – Schedule count.

setAudioBuffer(buff_addr, buff_size)

Sets base address, reads address and buffer size for AUD schedules.

This function is a shortcut which assigns Size/BaseAddr/ReadAddr

Parameters:

buff_addr (int) – Base addresss.
buff_size (int) – Buffer size.

setAudioSchedule(scheduleOnset, scheduleRate, maxScheduleFrames, lrMode='mono', bufferAddress=16000000, numBufferFrames=None)

Implements an audio schedule in a DATAPixx.

Mimics the behavior of Datapixx(‘SetAudioSchedule’) in MATLAB, but with more flexibility in the ‘lrMode’ format. ‘lrMode’ can be passed as an integer (as in MATLAB), or as a string.

Parameters:

scheduleOnset (float) – the audio schedule delay in seconds
scheduleRate (int) – the audio codec sampling rate in Hz
maxScheduleFrames – the number of samples after which the audio codec stops sampling. if maxScheduleFrames > numBufferFrames, the audio codec loops back to sample data at the start address of the audio buffer.

Exceptions:

scheduleOnset is not of type float or is less than 0
scheduleOnset * 10**9 is greater than 0xffffffff
scheduleRate is not of type int. warning when scheduleRate is not in the interval (8000,96000)
maxScheduleFrames is not of type int or is less than 0
lrMode is not equal to any acceptable values. acceptable values given in error message
bufferAddress is not of type int or is less than 0 or is odd
numBufferFrames is not of type int or is less than 0

setBaseAddress(value)

Sets the Ram buffer start address.

This method allows the user to set the RAM buffer start address used in schedules. The given address must be an even value.

Parameters:

address (int) – Any value in a range of 0 up to the RAM size.

setBufferSize(buffer_size)

Sets the Ram buffer size.

This method allows the user to set the RAM buffer size used in schedules. It should only be used if the user wants the schedules to wrap when it has reached its maximum size. When schedules are expected to wrap, the user should also use setBaseAddress() The given size is in bytes and must be an even value.

Parameters:

buffer_size (int) – Any value in a range of 0 up to the RAM size.

setBufferSizeAux(buffer_size)

Sets the Ram buffer size.

This method allows the user to set the RAM buffer size used in schedules. It should only be used if the user wants the schedules to wrap when it has reached its maximum size. When schedules are expected to wrap, the user should also use setBaseAddress() The given size is in byte and must be an even value.

Parameters:

buffer_size (int) – Any value in a range of 0 up to the RAM size.

setCodecSpeakerLeftVolume(volume, unit=0)

Sets the speaker volume of the left channel.

Parameters:

volume (float) – Range 0-1 or dB.
unit (float) – 0 for linear or 1 for dB.

setCodecSpeakerRightVolume(volume, unit)

Sets the speaker volume of the right channel.

Parameters:

volume (float) – Range 0-1 or dB.
unit (float) – 0 for linear or 1 for dB.

setCodecSpeakerVolume(volume, unit=0)

Sets the speaker volume of both Left and right channels.

Parameters:

volume (float) – Range 0-1 or dB.
unit (float) – 0 for linear or 1 for dB.

setCodecVolume(volume, unit)

Sets the codec volume of for both left and right channels.

Parameters:

volume (float) – Range 0-1 or dB.
unit (float) – 0 for linear or 1 for dB.

setCodecVolumeLeft(volume, unit)

Sets the codec volume of the left channel.

Parameters:

volume (float) – Range 0-1 or dB.
unit (float) – 0 for linear or 1 for dB.

setCodecVolumeRight(volume, unit)

Sets the codec volume of the right channel.

Parameters:

volume (float) – Range 0-1 or dB.
unit (float) – 0 for linear or 1 for dB.

setLeftRightMode(mode)

Sets how audio data is updated by schedules.

Parameters:

mode (str) –

Any of the following predefined constants.

mono : Left schedule data goes to left and right channels.
left : Each schedule data goes to left channel only.
right : Each schedule data goes to right channel only.
stereo1 : Pairs of Left data are copied to left/right channels.
stereo2 : Left data goes to left channel, Right data goes to right.

See also

getLeftRightMode

setReadAddress(address)

Sets the Ram buffer read address.

This method allows the user to set the RAM buffer read address used in schedules. This address is used by the schedule to know where the data should be first read from. The schedule will then read the following data to the address following the RAM buffer read address.

The given address must be an even value.

Parameters:

address (int) – Any value in a range of 0 up to the RAM size.

setReadAddressRight(address)

Sets the Ram buffer read address.

This method allows the user to set the RAM buffer read address used in schedules. This address is used by the schedule to know where the data should be first read from. The schedule will then read the following data to the address following the RAM buffer read address.

The given address must be an even value.

Parameters:

address (int) – Any value in a range of 0 up to the RAM size.

setScheduleCount(count)

Sets the schedule count.

This method allows the user to set the schedule count for a schedule with a fixed number of samples. In which case, the schedule will decrement at a given rate and stop when the count reaches 0.

Parameters:

count (int) – Any positive value greater than 0.

setScheduleCountAux(count)

Sets the schedule count.

This method allows the user to set the schedule count for a schedule with a fixed number of samples. In which case, the schedule will decrement at a given rate and stop when the count reaches 0.

Parameters:

count (int) – Any positive value greater than 0.

setScheduleCountDown(enable)

Sets the schedule countdown mode.

This method allows the user to enable or disable the countdown on a schedule. When enabled, the schedule decrements at the given rate and stops automatically when the count hits 0. When disabled, the schedule increments at the given rate and is stopped by calling stopSchedule().

Parameters:

enable (Bool) – True if countdown is enabled, False otherwise.

setScheduleCountDownAux(enable)

Sets the schedule countdown mode.

This method allows the user to enable or disable the countdown on a schedule. When enabled, the schedule decrements at the given rate and stops automatically when the count hits 0. When disabled, the schedule increments at the given rate and is stopped by calling stopSchedule().

Parameters:

enable (Bool) – True if countdown is enabled, False otherwise.

setScheduleOnset(onset)

Sets the schedule onset value.

This method allows the user to set the nanosecond delay between schedule start and first sample. If no delay is required, this method does not need to be used. Default value is 0.

Parameters:

onset (int) – Any positive value equal or greater to 0.

setScheduleOnsetAux(onset)

Sets the schedule onset value.

This method allows the user to set the nanosecond delay between schedule start and first sample. If no delay is required, this method does not need to be used. Default value is 0.

Parameters:

onset (int) – Any positive value equal or greater to 0.

setScheduleRate(rate, unit='hz')

Sets the schedule rate.

This method allows the user to set the schedule rate. Since the rate can be given with different units, the method also needs to have a unit associated with the rate. If no delay is required, this method does not need to be used. Default value is 0.

Parameters:

rate (int) – Any positive value equal or greater to 0.
unit (str) –
hz : samples per second, maximum 96 kHz.
video : samples per video frame, maximum 96 kHz. nano : sample period in nanoseconds, minimum 10417 ns.

setScheduleRateAux(rate, unit='hz')

Sets the schedule rate.

This method allows the user to set the schedule rate. Since the rate can be given with different units, the method also needs to have a unit associated with the rate. If no delay is required, this method does not need to be used. Default value is 0.

Parameters:

rate (int) – Any positive value equal or greater to 0.
unit (str) –
hz : samples per second, maximum 96 kHz.
video : samples per video frame, maximum 96 kHz. nano : sample period in nanoseconds, minimum 10417 ns.

setVolume(volume)

Sets volume for the Left and Right audio channels, range 0-1

Parameters:

volume (float) – Value for the desired volume, between 0 and 1.

setVolumeLeft(volume)

Sets volume for the Left audio channels, range 0-1

Parameters:

volume (float) – Value for the desired volume, between 0 and 1.

setVolumeRight(volume)

Sets volume for the Right audio channels, range 0-1

Parameters:

volume (float) – Value for the desired volume, between 0 and 1.

startSchedule()

Starts the active schedule for a given subsystem.

Depending on how the schedules are configured, it may not be necessary to call this method. When a schedule is using a countdown, it is not required to stop the schedule.

startScheduleAux()

Starts a schedule.

Schedules may be configured in different ways, affecting their behavior. Before a schedule is started, the user should make sure that it is properly set in the Aux mode.

See also

stopScheduleAux, setReadAddressAux, setBaseAddressAux, setScheduleOnsetAux, setScheduleRateAux, setScheduleCountDownAux, setScheduleCountAux

stopSchedule()

Stops the active schedule for a given subsystem.

Depending on how the schedules are configured, it may not be necessary to call this method. When a schedule is using a countdown, it is not required to stop the schedule.

stopScheduleAux()

Stops the active schedule for a given subsystem.

Depending on how the schedules are configured, it may not be necessary to call this method. When a schedule is using a countdown, it is not required to stop the schedule.

See also

startScheduleAux, setReadAddressAux, setBaseAddressAux, setScheduleOnsetAux, setScheduleRateAux, setScheduleCountDownAux, setScheduleCountAux

waitForAudio(timeOut=inf)

Basic blocking function to halt code execution until the current audio schedule finishes. Useful for preventing contiguous audio schedules from interfering with one another

Parameters:	timeOut (float) – maximum duration of blocking in seconds. default=np.inf (forever)
Returns:	total blocking time in seconds

Exceptions:

timeOut is not of type float and not of type int or is less than 0

writeAudioBuffer(bufferData, bufferAddress=16000000)

Writes the audio waveform data in ‘bufferData’ to the DATAPixx RAM at memory address ‘bufferAddress’.

Mimics the behavior of Datapixx(‘WriteAudioBuffer’) in MATLAB, but with more flexibility in the data format. ‘bufferData’ can be in any format really, while in MATLAB, it must be scaled between (0,1).

Parameters:

bufferData (list/array) – can be a list or a NumPy array. If a list, must be castable to NumPy ndarray of type float
bufferAddress (int) – memory location in DATAPixx RAM. default=0

Exceptions:

bufferData cannot be casted into a NumPy array of type float.
bufferData is empty
bufferData has more than 2 dimensions
bufferData has more than 2 rows
bufferAddress is not of type int or is less than 0 or is odd