The Libaudioverse API

Implements all of the Libaudioverse API.

This is the only module that should be used. All other modules are private.

class libaudioverse.AdditiveSawNode(server)

The most accurate, least featureful, and slowest saw oscillator.

This oscillator uses additive synthesis to produce saw waves. The efficiency therefore depends on the frequency. Sweeping this oscillator will perform poorly if you do not set the harmonics to a nonzero value.

This oscillator is slightly under the range -1 to 1. Of the additive oscillators, the sawtooth wave is the worst in this respect. For this reason, it is probably not suitable as a control signal. This is not fixable using additive synthesis and is a frequency dependent effect.

This node has no inputs.

Outputs:

index	channels	description
0	1	A saw wave.

frequency

Type: float

Range: [0, INFINITY]

Default value: 440.0

The frequency of the saw wave, in hertz.

frequency_multiplier

Type: float

Range: [-INFINITY, INFINITY]

Default value: 1.0

An additional multiplicative factor applied to the frequency of the oscillator.

This is useful for creating instruments, as the notes of the standard musical scale fall on frequency multiples of a reference pitch, rather than a linear increase.

harmonics

Type: int

Range: [0, MAX_INT]

Default value: 0

The number of harmonics. 0 requests automatic adjustment. Use a nonzero value if you intend to sweep the saw wave.

While this property has no max value, any combination of frequency and harmonics that leads to aliasing will alias. To avoid this, make sure that frequency*harmonics never goes over half your chosen sampling rate.

phase

Type: float

Range: [0.0, 1.0]

Default value: 0.0

The phase of the saw wave. This is measured in periods, not in radians.

class libaudioverse.AdditiveSquareNode(server)

The most accurate, least featureful, and slowest square oscillator.

This oscillator uses additive synthesis to produce square waves. The efficiency therefore depends on the frequency. Sweeping this oscillator will perform poorly if you do not set the harmonics to a nonzero value.

This oscillator is slightly under the range -1 to 1. For this reason, it is probably not suitable as a control signal. This is not fixable using additive synthesis and is a frequency dependent effect.

This node has no inputs.

Outputs:

index	channels	description
0	1	A square wave.

frequency

Type: float

Range: [0, INFINITY]

Default value: 440.0

The frequency of the square wave, in hertz.

frequency_multiplier

Type: float

Range: [-INFINITY, INFINITY]

Default value: 1.0

An additional multiplicative factor applied to the frequency of the oscillator.

This is useful for creating instruments, as the notes of the standard musical scale fall on frequency multiples of a reference pitch, rather than a linear increase.

harmonics

Type: int

Range: [0, MAX_INT]

Default value: 0

The number of harmonics. 0 requests automatic adjustment. Use a nonzero value if you intend to sweep the square wave.

While this property has no max value, any combination of frequency and harmonics that leads to aliasing will alias. To avoid this, make sure that 2*frequency*(2*harmonics-1) never goes over half your chosen sampling rate.

phase

Type: float

Range: [0.0, 1.0]

Default value: 0.0

The phase of the square wave. This is measured in periods, not in radians.

class libaudioverse.AdditiveTriangleNode(server)

The most accurate, least featureful, and slowest triangle oscillator.

This oscillator uses additive synthesis to produce triangle waves. The efficiency therefore depends on the frequency. Sweeping this oscillator will perform poorly if you do not set the harmonics to a nonzero value.

This oscillator is slightly under the range -1 to 1. Calibration scripts show that the worst case is -0.9 to 0.9, with the error increasing as frequency increases. For this reason, it is probably not suitable as a control signal. This is not fixable using additive synthesis and is a frequency dependent effect.

This node has no inputs.

Outputs:

index	channels	description
0	1	A triangle wave.

frequency

Type: float

Range: [0, INFINITY]

Default value: 440.0

The frequency of the triangle wave, in hertz.

frequency_multiplier

Type: float

Range: [-INFINITY, INFINITY]

Default value: 1.0

An additional multiplicative factor applied to the frequency of the oscillator.

This is useful for creating instruments, as the notes of the standard musical scale fall on frequency multiples of a reference pitch, rather than a linear increase.

harmonics

Type: int

Range: [0, MAX_INT]

Default value: 0

The number of harmonics. 0 requests automatic adjustment. Use a nonzero value if you intend to sweep the triangle wave.

While this property has no max value, any combination of frequency and harmonics that leads to aliasing will alias. To avoid this, make sure that 2*frequency*(2*harmonics-1) never goes over half your chosen sampling rate.

phase

Type: float

Range: [0.0, 1.0]

Default value: 0.0

The phase of the triangle wave. This is measured in periods, not in radians.

class libaudioverse.AllpassNode(server, channels, max_delay)

Implements a first-order allpass filter whose transfer function is \(\frac{c+Z^{-d} }{1 + cZ^{-d} }\) where c is the coefficient and d the delay in samples.

This filter is useful in various reverb designs.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to filter.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The filtered signal.

coefficient

Type: float

Range: [-INFINITY, INFINITY]

The coefficient of the allpass filter’s transfer function.

For those not familiar with digital signal processing, this controls how quickly the repeating echoes created by this filter decay.

delay_max

Type: int

This property is read-only.

The max delay as set at the node’s creation time.

delay_samples

Type: int

Range: dynamic

Default value: 1

The delay of the delay line in samples. The range of this property depends on the maxDelay parameter to the constructor.

Note that values less than 1 sample still introduce delay.

interpolation_time

Type: float

Range: [0.001, INFINITY]

Default value: 0.001

When the delay_samples property is changed, the delay line crossfades between the old position and the new one. Essentially, this property sets how long it will take the allpass filter to settle after a delay change. Note that for this node, it is impossible to get rid of the crossfade completely.

class libaudioverse.AmplitudePannerNode(server)

This panner pans for a set of regular speakers without any additional effects applied. Additionally, it understands surround sound speaker layouts and allows for the assignment of custom speaker mappings. The default configuration provides a stereo panner that can be used without any additional steps. The additional function Lav_amplitudePannerNodeConfigureStandardChannelMap can set the panner to output for a variety of standard configurations, so be sure to see its documentation.

Inputs:

index	channels	description
0	1	The signal to pan

Outputs:

index	channels	description
0	Depends on a number of properties on this node.	The result of panning the signal.

azimuth

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The horizontal angle of the panner in degrees. 0 is directly ahead, and positive values are clockwise.

channel_map

Type: float_array

Range: [-INFINITY, INFINITY]

Default value: [-90, 90]

The angles of the speakers in the order in which they are to be mapped to channels. The first speaker will be mapped to the first channel, the second to the second, etc. These channels are then combined and produced as the single output of the panner.

You can use floating point infinity to indicate a channel should be skipped. This functionality is used by all of the standard channel maps to skip the center and LFE channels.

configure_standard_map(node, channels)

Sets the channel map and other properties on this node to match a standard configuration. The possible standard configurations are found in the PanningStrategies enumeration.

elevation

Type: float

Range: [-90.0, 90.0]

Default value: 0.0

The vertical angle of the panner in degrees. 0 is horizontal and positive values are upwards. Note that, for amplitude panners, this has no effect and exists only to allow swapping with the HRTF panner without changing code.

should_crossfade

Type: boolean

Default value: True Whether or not to instantly move to the new position. If crossfading is disabled, large movements of the panner will cause audible clicks. Disabling crossfading can aid performance under heavy workloads, especially with the HRTF panner. If crossfading is enabled, moving the panner will slowly fade it to the new position over the next block.

class libaudioverse.ArrayProperty(handle, slot, reader, replacer, length, lock)

Base class for all array properties.

value

The array, as a tuple.

class libaudioverse.AutomatedProperty(handle, slot, getter, setter, converter=<function LibaudioverseProperty.<lambda>>)

A property that supports automation and node connection.

cancel_automators(time)

Cancel all automators scheduled to start after time.

Wraps Lav_automationCancelAutomators.

envelope(time, duration, values)

Run an envelope.

The property’s value will stay where it was after the last automator until the specified time is reached, whereupon it will follow the envelope until time+duration.

This function wraps Lav_automationEnvelope.

linear_ramp_to_value(time, value)

Schedule a linear automator.

The property’s value will change to the specified value by the specified time, starting at the end of the previous automator

This function wraps Lav_automationLinearRampToValue.

set(time, value)

Sets the property’s value to a specific value at a specific time.

Wraps Lav_automationSet.

class libaudioverse.BiquadNode(server, channels)

Implementation of a biquad filter section, as defined by the Audio EQ Cookbook by Robert Bristo-Johnson. This node is capable of implementing almost every filter needed for basic audio effects, including equalizers. For the specific equations used, see the Audio EQ Cookbook. It may be found at: http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to process.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The result of processing the audio via the filter.

dbgain

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

This property is a the gain in decibals to be used with the peaking and shelving filters. It measures the gain that these filters apply to the part of the signal they boost.

filter_type

Type: int

Range: BiquadTypes

Default value: BiquadTypes.lowpass

The type of the filter. This determines the interpretations of the other properties on this node.

frequency

Type: float

Range: [0, INFINITY]

Default value: 2000.0

This is the frequency of interest. What specifically this means depends on the selected filter type; for example, it is the cutoff frequency for lowpass and highpass.

q

Type: float

Range: [0.001, INFINITY]

Default value: 0.5

Q is a mathematically complex parameter, a full description of which is beyond the scope of this manual. Naively, Q can be interpreted as a measure of resonation. For Q<=0.5, the filter is said to be damped: it will cut frequencies. For Q>0.5, however, some frequencies are likely to be boosted.

Q controls the bandwidth for the bandpass and peaking filter types For everything except the peaking filter, this property follows the normal definition of Q in the electrical engineering literature. For more specifics, see the Audio EQ Cookbook. It is found here: http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt

class libaudioverse.BiquadTypes

Indicates a biquad filter type, used with the BiquadNode and in a few other places.

allpass = 4

Indicates an allpass filter.

bandpass = 2

Indicates a bandpass filter.

highpass = 1

Indicates a highpass filter.

highshelf = 7

Indicates a highshelf filter.

identity = 8

This filter does nothing.

lowpass = 0

Indicates a lowpass filter.

lowshelf = 6

Indicates a lowshelf filter.

notch = 3

Indicates a notch filter.

peaking = 5

Indicates a peaking filter.

class libaudioverse.BlitNode(server)

Generates bandlimited impulse trains. These sound like a buzz, but have important applications in the alias-free synthesis of analog waveforms.

This node has no inputs.

Outputs:

index	channels	description
0	1	A bandlimited impulse train.

frequency

Type: float

Range: [0, INFINITY]

Default value: 440.0

The frequency of the impulse train in HZ.

frequency_multiplier

Type: float

Range: [-INFINITY, INFINITY]

Default value: 1.0

An additional multiplicative factor applied to the frequency of the oscillator.

This is useful for creating instruments, as the notes of the standard musical scale fall on frequency multiples of a reference pitch, rather than a linear increase.

harmonics

Type: int

Range: [0, MAX_INT]

Default value: 0

The number of harmonics to include. 0 requests automatic adjustment. When 0, the algorithm this node represents will include as many harmonics as it can without aliasing.

phase

Type: float

Range: [0.0, 1.0]

Default value: 0.0

The phase of the impulse train. This is measured in periods, not in radians.

should_normalize

Type: boolean

Default value: True If false, the produced BLIT will have an integral of 1 over every period. If true, the produced blit will be normalized to be between 1 and -1, and suitable for audio. The default is true.

class libaudioverse.BooleanProperty(handle, slot)

Represents a boolean property.

Note that boolean properties show up as int properties when their type is queried. This class adds extra marshalling to make sure that boolean properties show up as booleans on the Python side, as the C API does not distinguish between boolean properties and int properties with range [0, 1].

class libaudioverse.Buffer(server)

An audio buffer.

Use load_from_file to read a file or load_from_array to load an iterable.

decode_from_array(array)

Takes an encoded array of audio data and decodes it.

Wraps Lav_bufferDecodeFromArray. Array must be a string, bytes, or iterable of bytes. DO not give unicode to this function. Objects which do not support the ctypes buffer interface will process unusably slowly.

get_duration()

Get the duration of the buffer in seconds.

Wraps Lav_bufferGetDuration.

get_length_in_samples()

Returns the length of the buffer in samples.

Wraps Lav_bufferGetLengthInSamples.

load_from_array(sr, channels, frames, data)

Load from an array of interleaved floats.

Wraps Lav_bufferLoadFromArray.

load_from_file(path)

Load an audio file.

Wraps Lav_bufferLoadFromFile.

normalize()

Normalizes the buffer.

Wraps Lav_bufferNormalize.

exception libaudioverse.BufferInUseError

Indicates an attempt to modify a buffer while something is reading its data.

class libaudioverse.BufferNode(server)

This node plays a buffer. The output of this node will have as many channels as the buffer does, so connecting it directly to the server will have the desired effect.

This node has no inputs.

Outputs:

index	channels	description
0	Depends on the currently playing buffer.	The output from the buffer being played.

buffer

Type: buffer

The currently playing buffer. Setting this property will reset position.

ended_count

Type: int

Range: [0, MAX_INT]

Default value: 0

Increments every time the buffer reaches it’s end. If the buffer is not looping, this can be used to determine when the buffer is ended, without using the callback. if the buffer is configured to loop, the counter will count up every time the end of a loop is reached. You can write to this property to reset it.

get_end_callback()

Get the end callback.

This is a feature of the Python bindings and is not available in the C API. See the setter for specific documentation on this callback.

looping

Type: boolean

Default value: False If true, this node continues playing the same buffer from the beginning after it reaches the end.

position

Type: double

Range: dynamic

Default value: 0.0

The position of playback, in seconds. The range of this property corresponds to the total duration of the buffer.

rate

Type: double

Range: [0, INFINITY]

Default value: 1.0

A multiplier that applies to playback rate. 1.0 is identity. Values less than 1.0 cause a decrease in pitch and values greater than 1.0 cause an increase in pitch.

set_end_callback(callback, additional_args=None, additional_kwargs=None)

Set the end callback.

Additional_args and additional_kwargs are passed to the callback in addition to any arguments from Libaudioverse. Note that Libaudioverse always uses positional arguments.

C callback signature: void (LavHandle nodeHandle, void * userdata)

Called outside the audio threads every time the buffer reaches the end of the audio data.

Callback parameters:

nodeHandle

The node which called this callback.

userdata

The userdata parameter as passed to the setter for this callback.

class libaudioverse.BufferProperty(handle, slot)

Proxy to a buffer property.

It is safe to set this property to None.

class libaudioverse.BufferTimelineNode(server, channels)

Represents timelines of buffers.

This node provides the ability to schedule buffers to play at any specific time in the future. This node supports pitch bending scheduled buffers. There is no limit to the number of buffers which may be scheduled at any given time, and polyphony is supported.

This node has no inputs.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The sum of all playing buffers.

schedule_buffer(node, buffer, time, pitch_bend)

Schedule a buffer, optionally with pitch bend. The time is relative to now.

exception libaudioverse.CannotConnectToPropertyError

Attempt to connect a node to a property which cannot be automated.

exception libaudioverse.CannotCrossServersError

An attempt was made to relate two objects from different servers. This could be assigning to buffer properties, connecting nodes, or any other such condition.

exception libaudioverse.CannotInitAudioError

The audio subsystem could not be initialized.

exception libaudioverse.CausesCycleError

The requested operation would cause a cycle in the graph of nodes that need processing.

class libaudioverse.ChannelInterpretations

Specifies how to treat inputs to this node for upmixing and downmixing.

discrete = 0

If channel counts mismatch, don’t apply mixing matrices. Either drop or fill with zeros as appropriate.

speakers = 1

Apply mixing matrices if needed.

class libaudioverse.ChannelMergerNode(server, channels)

Libaudioverse inputs and outputs transport multiple channels of audio, which is usually the desired behavior. This node, coupled with the ChannelSplitterNode , allows advanced applications to manipulate the individual audio channels directly. The usual workflow is as follows: feed the output of a node through a ChannelSplitterNode, modify the channels individually, and then merge them with this node.

The number of inputs to this node depends on parameters to its constructor.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The result of merging the input channels.

class libaudioverse.ChannelSplitterNode(server, channels)

Libaudioverse inputs and outputs transport multiple channels of audio, which is usually the desired behavior. This node, coupled with the ChannelMergerNode, allows advanced applications to manipulate the individual audio channels directly. The usual workflow is as follows: feed the output of a node through this node, modify the channels individually, and then merge them with a ChannelMergerNode.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to split into component channels.

The number of outputs from this node depends on parameters to its constructor.

class libaudioverse.ConvolverNode(server, channels)

A simple convolver.

This implements convolution directly, without use of the FFT.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to be convolved.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The convolved signal.

impulse_response

Type: float_array

Range: [-INFINITY, INFINITY]

Default value: [1.0]

The impulse response to convolve the input with.

class libaudioverse.CrossfaderNode(server, channels, inputs)

A crossfader is a node which allows for selection of exactly one input. The selection can be changed by crossfading, a technique whereby the currently selected input is slowly faded out and the new one faded in.

By using crossfades of no duration, this node can also be made to function as a switch or selector, selecting an input from among the connected nodes. This particular case is optimized, and special support is implemented via allowing you to write directly to the current_input property.

This crossfader has a configurable number of inputs. All inputs and the single output have the same channel count. These are both configurable via parameters to the constructor.

The number of inputs to this node depends on parameters to its constructor.

Outputs:

index	channels	description
0	Depends on the channel count given to the constructor.	The output of the crossfade.

crossfade(node, duration, input)

Begin a crossfade.

if a crossfade is currently inn progress, it finishes immediately and fires the event.

Using a duration of 0 is an instantaneous crossfade, equivalent to writing directly to the current_input property. Crossfades of duration 0 do not fire the finished event.

current_input

Type: int

Range: dynamic

Default value: 0

The currently active input.

Writing to this property is equivalent to crossfading with a time of 0. Note that the output is a combination of the current and target inputs while crossfading.

get_finished_callback()

Get the finished callback.

This is a feature of the Python bindings and is not available in the C API. See the setter for specific documentation on this callback.

is_crossfading

Type: boolean

Default value: False True if we are crossfading, otherwise false.

set_finished_callback(callback, additional_args=None, additional_kwargs=None)

Set the finished callback.

Additional_args and additional_kwargs are passed to the callback in addition to any arguments from Libaudioverse. Note that Libaudioverse always uses positional arguments.

C callback signature: void (LavHandle nodeHandle, void * userdata)

Called outside the audio thread when the currently scheduled crossfade finishes.

Callback parameters:

nodeHandle

The node which called this callback.

userdata

The userdata parameter as passed to the setter for this callback.

target_input

Type: int

This property is read-only.

The input which the current crossfade is headed for.

When not crossfading, this property is meaningless.

class libaudioverse.CrossfadingDelayNode(server, max_delay, channels)

Implements a crossfading delay line. Delay lines have uses in echo and reverb, as well as many more esoteric effects.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to delay.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The delayed signal.

delay

Type: float

Range: dynamic

Default value: 0.0

The delay of the delay line in seconds. The range of this property depends on the maxDelay parameter to the constructor.

Note that values less than 1 sample still introduce delay.

delay_max

Type: float

This property is read-only.

The max delay as set at the node’s creation time.

feedback

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The feedback coefficient. The output of the delay line is fed back into the delay line, multiplied by this coefficient. Setting feedback to small values can make echoes, comb filters, and a variety of other effects.

interpolation_time

Type: float

Range: [0.001, INFINITY]

Default value: 0.001

When the delay property is changed, the delay line crossfades between the old position and the new one. This property sets how long this crossfade will take. Note that for this node, it is impossible to get rid of the crossfade completely.

class libaudioverse.DcBlockerNode(server, channels)

A DC blocker. This is a first-order filter, the best possible within numerical limits. It consists of a zero at DC, and a pole as close to DC as we can put it. For any sampling rate, this node is the best first-order section for DC removal possible.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	A signal with some DC.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The same signal with DC cut using a first-order filter.

class libaudioverse.DeviceInfo(channels, identifier, name)

Represents info on a audio device.

Channels is the number of channels for the device. Name is a unicode string containing a human-readable name. Identifier should be used with Server.set_output_device.

The caveat from the Libaudioverse manual should be summarized here: channels is not reliable, and your application should default to stereo while providing the user the option to change it.

class libaudioverse.DistanceModels

used in the 3D components of this library. Indicates how sound should become quieter as objects move away from the listener.

Libaudioverse computes the distance from the center of the source to the listener, then subtracts the size. In the following, distance refers to this distance. Libaudioverse also computes a second value called distancePercent; specifically, distancePercent = distance/maxDistance.

inverse = 1

Sounds fall off as 1/(1+315*distancePercent). Just before maxDistance, the gain of the sound will be approximately -25 DB. This distance model emphasizes distance changes when sounds are close, but treats distance changes of further away sources more subtly. For full benefit of the effect of close sounds, this distance model must be used with fairly large values for maxDistance, usually around 300.

inverse_square = 2

Sounds fall off as 1.0/(1+315*distancePercent*distancePercent). This is a standard inverse square law, modified such that the sound volume just before maxDistance is about -25 DB. Of the available distance models, this is the closest to an accurate simulation of large, wide-open places such as fields and stadiums.

linear = 0

Sound falls off as 1-distancePercent.

class libaudioverse.DoppleringDelayNode(server, max_delay, channels)

Implements a dopplering delay line, an interpolated delay line that intensionally bends pitch when the delay changes. Delay lines have uses in echo and reverb, as well as many more esoteric effects.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to delay.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The delayed signal.

delay

Type: float

Range: dynamic

Default value: 0.0

The delay of the delay line in seconds. The range of this property depends on the maxDelay parameter to the constructor.

Note that values less than 1 sample still introduce delay.

delay_max

Type: float

This property is read-only.

The max delay as set at the node’s creation time.

interpolation_time

Type: float

Range: [0.001, INFINITY]

Default value: 0.01

When the delay property is changed, the delay line moves the delay to the new position. This property sets how long this will take. Note that for this node, it is impossible to get rid of the crossfade completely.

On this delay line, the interpolation time is the total duration of a pitch bend caused by moving the delay.

class libaudioverse.DoubleProperty(handle, slot)

Proxy to a double property.

class libaudioverse.EnumProperty(handle, slot, enum)

Proxy to an integer property taking an enum.

This class is like IntProperty, but it will error if you try to yuse the wrong enum or a regular integer constant. In the C API, the distinction between these classes does not exist: both use Lav_nodeGetIntProperty and Lav_nodeSetIntProperty.

class libaudioverse.EnvironmentNode(server, hrtf_path)

This is the entry point to the 3D simulation capabilities. Environment nodes hold the information needed to pan sources, as well as acting as an aggregate output for all sources that use this environment.

Note that the various properties for default values do not affect already created sources. It is best to configure these first. Any functionality to change a property on all sources needs to be implemented by the app, and is not offered by Libaudioverse.

This node has no inputs.

Outputs:

index	channels	description
0	Depends on the output_channels property.	The output of the 3D environment.

add_effect_send(node, channels, is_reverb, connect_by_default)

Add an effect send.

Effect sends are aggregates of all sources configured to make use of them. This function’s return value is the index of the newly created effecct send.

The world gains an additional output for every added effect send. This output aggregates all audio of sources configured to send to it, including the panning effects on those sources. The returned index is the number of the newly created output.

Two special cases are worth noting.

First, a mono effect send includes all sources with only attenuation applied.

Second, if the effect send has 4 channels, it may be configured to be a reverb effect send with the is_reverb parameter. Reverb effect sends are treated differently in terms of attenuation: as sources move away from the listener, their dry path becomes less but the audio sent to the reverb effect send becomes greater.

No effect send can include occlusion effects.

default_reverb_distance

Type: float

Range: [0.0, INFINITY]

Default value: 75.0

The distance at which a source will be heard only in the reverb.

See documentation on the SourceNode node for a specific explanation. By default, sources get the value of this property from the environment. To control this property on a per-source basis, set Lav_SOURCE_CONTROL_REVERB to true on the source.

default_size

Type: float

Range: [0.0, INFINITY]

Default value: 0.0

The default size for new sources. Sources aare approximated as spheres, with 0 being the special case of a point source. Size is used to determine the listener’s distance from a source.

distance_model

Type: int

Range: DistanceModels

Default value: DistanceModels.linear

Distance models control how quickly sources get quieter as they move away from the listener.

By default, sources are configured to delegate to the environment when looking for values to use for the distance model parameters. This behavior may be changed by setting Lav_SOURCE_CONTROL_DISTANCE_MODEL to true.

max_distance

Type: float

Range: [0.0, INFINITY]

Default value: 150.0

The maximum distance at which a source is audible. Consider this property to be in meters.

By default, sources are configured to delegate to the environment when looking for values to use for the distance model parameters. This behavior may be changed by setting Lav_SOURCE_CONTROL_DISTANCE_MODEL to true.

max_reverb_level

Type: float

Range: [0.0, 1.0]

Default value: 0.6

The maximum amount of audio to be diverted to reverb sends, if any.

Behavior is undefined if this property is ever less than Lav_ENVIRONMENT_MIN_REVERB_LEVEL.

By default, sources look to their environmlent for the value of this property. If you wish to set it on a per-source basis, set Lav_SOURCE_CONTROL_REVERB to true on the source.

min_reverb_level

Type: float

Range: [0.0, 1.0]

Default value: 0.15

The minimum reverb level allowed.

if a send is configured to be a reverb send, this is the minimum amount of audio that will be diverted to it.

Behavior is undefined if this property is ever greater than the value of Lav_ENVIRONMENT_MAX_REVERB_LEVEL.

By default, sources look to their environmlent for the value of this property. If you wish to set it on a per-source basis, set Lav_SOURCE_CONTROL_REVERB to true on the source.

orientation

Type: float6

Default value: [0.0, 0.0, -1.0, 0.0, 1.0, 0.0]

The orientation of the listener. The first three elements are a vector representing the direction in which the listener is looking and the second 3 a vector representing the direction in which a rod pointing out of the top of the listener’s head would be pointing

This property packs these vectors because they must never be modified separately. Additionally, they should both be unit vectors and must also be orthoganal.

the default situates the listener such that positive x is right, positive y is up, and positive z is behind the listener. The setting (0, 1, 0, 0, 0, 1) will situate the listener such that positive x is right and positive y is forward. For those not familiar with trigonometry and who wish to consider positive x east and positivve y north, the following formula will turn the listener to face a scertain direction specified in radians clockwise of north: (sin(theta), cos(theta), 0, 0, 0, 1). As usual, note that radians=degrees*PI/180.

output_channels

Type: int

Range: [0, 8]

Default value: 2

Environments are not smart enough to determine the number of channels their output needs to have. If you are using something greater than stereo, i.e. 5.1, you need to change this property. The specific issue solved by this property is the case in which one source is set to something different than all others, or where the app changes the panning strategies of sources after creation.

Values besides 2, 4, 6, or 8 do not usually have much meaning.

panning_strategy

Type: int

Range: PanningStrategies

Default value: PanningStrategies.stereo

The panning strategy for any source configured to delegate to the environment. All new sources delegate to the environment by default.

If you want to change this property for a specific source, set Lav_SOURCE_CONTROL_PANNING on the source to true.

play_async(node, buffer, x, y, z, is_dry)

Play a buffer, using the specified position and the currently set defaults on the world for distance model and panning strategy. This is the same as creating a buffer and a source, but Libaudioverse retains control of these objects. When the buffer finishes playing, the source is automatically disposed of.

position

Type: float3

Default value: [0.0, 0.0, 0.0]

The position of the listener, in world coordinates.

class libaudioverse.FdnFilterTypes

Possible filter types for a feedback delay network’s feedback path.

disabled = 0

Don’t insert filters on the feedback path.

highpass = 2

Insert highpass filters on the FDN’s feedback path.

lowpass = 1

Insert lowpass filters on the FDN’s feedback path.

class libaudioverse.FdnReverbNode(server)

An 8 delay line FDN reverberator, based off a householder reflection.

This reverb takes as its input and outputs ats its output quadraphonic audio. Panning effects will still be observed at the output with some bias. If a stereo signal is fed into the reverb and the reverb is likewise connected to a stereo output, the input signal’s volume will effectively be halved.

Inputs:

index	channels	description
0	4	The signal to apply reverb to.

Outputs:

index	channels	description
0	4	The signal with reverb applied.

cutoff_frequency

Type: float

Range: dynamic

Default value: 5000

Controls the frequencies of lowpass filters on the feedback path of the reverb. Lowering this property leads to softer and less harsh reverb.

delay_modulation_depth

Type: float

Range: [0.0, 1.0]

Default value: 0.0

Controls how deep the modulation of the delay lines is. Increasing this property slightly makes the late reverb sound less metallic, while extremely high values add chorus-like effects. This property acts as a multiplier, and the correspondance between it and physical units is intentionally left unspecified.

delay_modulation_frequency

Type: float

Range: [0.0, 500.0]

Default value: 10.0

Controls how fast the internal delay lines modulate.

density

Type: float

Range: [0.0, 1.0]

Default value: 0.5

Controls the density of the reverb. Extremely low values sound “grainy”; extremely high values tend to resonate.

t60

Type: float

Range: [0.0, INFINITY]

Default value: 1.0

The t60 is the time it takes the reverb to decay by 60 decibals.

class libaudioverse.FeedbackDelayNetworkNode(server, max_delay, channels)

Implements a feedback delay network. This is possibly the single-most complicated node in Libaudioverse, and full documentation of it goes well beyond the manual. Unless you know what a feedback delay network is and have a specific reason for using one, this node will probably not help you.

This node has n inputs and outputs, where n is the lines parameter to the constructor. Each input and output pair represent the input and output of a specific delay line, respectively.

The inputs of this node are described above.

The outputs from this node are described above.

delays

Type: float_array

The lengths of the delay lines in seconds. This array must be channels long. All values must be positive and no more than the maximum delay specified to the constructor.

filter_frequencies

Type: float_array

The frequencies of the filters. The range of this property is 0 to Nyquist, or half the sampling rate.

filter_types

Type: int_array

Range: FdnFilterTypes

Allows insertion of filters in the feedback paths. These filters can be individually enabled and disabled; the default is disabled.

matrix

Type: float_array

The feedback matrix.

A column vector is formed by reading all delay lines. This vector is multiplied by this matrix, and then fed back into the delay lines.

The matrix is stored in row-major order. The supplied array must have a length equal to the square of the channels specified to the constructor.

max_delay

Type: float

This property is read-only.

The maximum delay any of the internal delay lines may be set to.

output_gains

Type: float_array

Allows control of the individual gains of the output. These gains do not apply to the feedback path and are only for controlling relative output levels. The array for this property allows any floating point values, and must be exactly channels long.

class libaudioverse.FftConvolverNode(server, channels)

A convolver for long impulse responses.

This convolver uses the overlap-add convolution algorithm. It is slower than the ConvolverNode for small impulse responses.

The difference between this node and the ConvolverNode is the complexity of the algorithm. This node is capable of handling impulses longer than a second, a case for which the ConvolverNode will fail to run in realtime.

Furthermore, as the most common operation for this node is reverb, it is possible to set each channel’s response separately.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to be convolved.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The convolved signal.

set_response(node, channel, length, response)

Set the response for a specific channel.

set_response_from_file(node, path, file_channel, convolver_channel)

Set the impulse response for a specific channel of this node from a file.

exception libaudioverse.FileError

Represents a miscelaneous file error.

exception libaudioverse.FileNotFoundError

Libaudioverse could not find a specified file.

class libaudioverse.FileStreamerNode(server, path)

Streams a file, which must be specified to the constructor and cannot be changed thereafter.

This node is a stopgap solution, and should be considered temporary. It will likely remain for backward compatibility. Libaudioverse plans to eventually offer a more generic streaming node that also supports web addresses; such a node will have a completely different, less buffer-like interface.

In order to stream a file, it must be passed through a resampler. Consequentlty, the position property is slightly inaccurate and the ended property and callback are slightly delayed.

This node has no inputs.

Outputs:

index	channels	description
0	Depends on the file.	The output of the stream.

ended

Type: boolean

This property is read-only.

Switches from false to true once the stream has ended completely and gone silent. This property will never go true unless looping is false.

get_end_callback()

Get the end callback.

This is a feature of the Python bindings and is not available in the C API. See the setter for specific documentation on this callback.

looping

Type: boolean

Default value: False If true, this node repeats the file from the beginning once it reaches the end. Note that setting looping means that ended will never go true. If ended is already true, it may take until the end of the next processing block for ended to properly go false once more.

position

Type: double

Range: dynamic

Default value: 0.0

The position of playback, in seconds. The range of this property corresponds to the total duration of the file. Note that this property may be slightly inaccurate because this node has to pass data through a resampler.

set_end_callback(callback, additional_args=None, additional_kwargs=None)

Set the end callback.

Additional_args and additional_kwargs are passed to the callback in addition to any arguments from Libaudioverse. Note that Libaudioverse always uses positional arguments.

C callback signature: void (LavHandle nodeHandle, void * userdata)

Called outside the audio threads after the stream has both reached its end and gone silent. When called, ended will be set to true,.

Callback parameters:

nodeHandle

The node which called this callback.

userdata

The userdata parameter as passed to the setter for this callback.

class libaudioverse.FilteredDelayNode(server, max_delay, channels)

This node consists of a delay line with a biquad filter attached. The output of the delay line is filtered. The difference between this node and a delay line and filter pair is that this node will use the filtered output for the feedback.

This node is equivalent to the delay line in the Karplus-strong algorithm.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to process.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The result of processing the audio via the filter and delay line.

dbgain

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

This property is a the gain in decibals to be used with the peaking and shelving filters. It measures the gain that these filters apply to the part of the signal they boost.

delay

Type: float

Range: dynamic

Default value: 0.0

The delay of the delay line in seconds. The range of this property depends on the maxDelay parameter to the constructor.

delay_max

Type: float

This property is read-only.

The max delay as set at the node’s creation time.

feedback

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The feedback coefficient. The output of the filter is fed back into the delay line, multiplied by this coefficient.

filter_type

Type: int

Range: BiquadTypes

Default value: BiquadTypes.lowpass

The type of the filter. This determines the interpretations of the other properties on this node.

frequency

Type: float

Range: [0, INFINITY]

Default value: 2000.0

This is the frequency of interest. What specifically this means depends on the selected filter type; for example, it is the cutoff frequency for lowpass and highpass.

interpolation_time

Type: float

Range: [0.001, INFINITY]

Default value: 0.001

When the delay property is changed, the delay line crossfades between the old position and the new one. This property sets how long this crossfade will take. Note that for this node, it is impossible to get rid of the crossfade completely.

q

Type: float

Range: [0.001, INFINITY]

Default value: 0.5

Q is a mathematically complex parameter, a full description of which is beyond the scope of this manual. For lowpass, bandpass, and high pass filters, Q can be interpreted as a measure of resonation. For Q<=0.5, the filter is said to be damped: it will cut frequencies. For Q>0.5, however, some frequencies are likely to be boosted.

Q controls the bandwidth for the bandpass and peaking filter types as well as the slope for the shelving EQ.

For everything except the peaking filter, this property follows the normal definition of Q in the electrical engineering literature. For more specifics, see the Audio EQ Cookbook. It is found here: http://www.musicdsp.org/files/Audio-EQ-Cookbook.txt

class libaudioverse.FirstOrderFilterNode(server, channels)

A first order filter section, implementing the transfer function \(H(Z) = \frac{B_0 + B_1 Z^{-1} }{1+A_0 Z^{-1} }\)

This filter is not your friend unless you know DSP or have a specific goal in mind. Most applications will want a BiquadNode or a OnePoleFilterNode instead.

This filter is not controlled through frequency specifications. Instead, the position of the pole and the zero on the real axis are individually controllable with a-rate properties. Some helper functions exist to position them for common configurations, but other filter types do most of it better. The major advantage for this filter type is that it is incredibly inexpensive as compared to the IirNode and supports automation of the pole and zero’s position.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to filter.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The filtered signal.

configure_allpass(node, frequency)

Configure this node as an allpass. You specify the \(\frac{\pi}{2}\) frequency. You get a filter with a phase of \(\pi\) at DC and 0 at Nyquist.

configure_highpass(node, frequency)

Configure the filter as a highpass with a roll-off of 6 DB per octave. This is identical to the OnePoleFilterNode highpass configuration.

configure_lowpass(node, frequency)

Configure the filter as a first-order Butterworth lowpass. This is equivalent to the OnePoleFilterNode lowpass configuration.

pole

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The position of the pole on the real axis.

The pole may be positioned anywhere, but stable filters usually keep all poles inside the unit circle. For a stable filter, the value of this property should usually between -1 and 1.

zero

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The position of the zero on the real axis.

class libaudioverse.Float3Property(handle, slot)

Represents a float3 property.

class libaudioverse.Float6Property(handle, slot)

Represents a float6 property.

class libaudioverse.FloatArrayProperty(handle, slot, lock)

Represents a float array property.

class libaudioverse.FloatProperty(handle, slot)

Proxy to a float property.

class libaudioverse.GainNode(server, channels)

This node is essentially in instantiated generic node, offering only the functionality therein. Its purpose is to allow changing the gain or adding offset to a large collection of nodes. One possible use is as a simple mixer: point all the nodes to be mixed at the input, set mul, and then point the output at the destination for the mixed audio.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal whose gain is to be changed.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal with its gain changed.

exception libaudioverse.GenericError

Base for all libaudioverse errors.

class libaudioverse.GenericNode(handle)

Base class for all Libaudioverse nodes.

All properties and functionality on this class is available to all Libaudioverse nodes without exception.

add

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

After mul is applied, we add the value to which this property is set to the node’s result.

channel_interpretation

Type: int

Range: ChannelInterpretations

Default value: ChannelInterpretations.speakers

How to treat channel count mismatches. The default is to apply mixing matrices when possible.

If set to ChannelInterpretationSpeakers, mixing matrices are applied to inputs. Otherwise, when set to ChannelInterpretationDiscrete, they are not.

This property is almost never needed.

connect(*args)

Form a connection between this node and another object.

This function has 3 valid signatures:

node.connect(output, other_node, input): Connect output to the specified input of other_node. node.connect(output, property): Connect the specified output to the specified property on another node. The property must be a float or double property. node.connect(output, server): Connect the specified output to the server.

Any node which is connected directly or indirectly to the server will remain alive even if your program lets go of it. For more details on the subject of node lifetimes, see the Libaudioverse manual.

disconnect(*args)

Disconnect from other nodes.

Eventually, this function will support all signatures of connect. At the moment, we support:

node.disconnect(output): disconnect all connections involving the specified output. node.disconnect(output, other, input): Disconnect the specific connection made with node.connect(output, other, input).

This function does not allow key word arguments for the same reason connect doesn’t.

get_property_names()

Get the names of all properties on this node.

isolate()

Disconnect all outputs.

mul

Type: float

Range: [-INFINITY, INFINITY]

Default value: 1.0

After this node processes, the value to which mul is set is used as a multiplier on the result. The most notable effect of this is to change the node’s volume. A variety of other uses exist, however, especially as regards to nodes which are connected to properties. Mul is applied before add.

reset()

Perform the node-specific reset operation.

This directly wraps Lav_nodeReset.

server

Get the server.

state

Type: int

Range: NodeStates

Default value: NodeStates.playing

The node’s state. See the basics section in the Libaudioverse manual for details. The default is usually what you want.

class libaudioverse.GraphListenerNode(server, channels)

This node defines a callback which is called every block. The callback is passed pointers to the audio data passing through this node for the current block. The effect is that this node allows observing audio passing through any location in the audio graph.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The audio which will be passed to the associated callback.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The same audio as connected to the input without modification.

get_listening_callback()

Get the listening callback.

This is a feature of the Python bindings and is not available in the C API. See the setter for specific documentation on this callback.

set_listening_callback(callback, additional_args=None, additional_kwargs=None)

Set the listening callback.

Additional_args and additional_kwargs are passed to the callback in addition to any arguments from Libaudioverse. Note that Libaudioverse always uses positional arguments.

C callback signature: void (LavHandle nodeHandle, unsigned int frames, unsigned int channels, float * buffer, void * userdata)

When set, audio is passed to this callback every block. This callback is called inside the audio threads; do not block.

Callback parameters:

nodeHandle

The node which called this callback.

frames

The number of frames of audio being made available to client code. This should always be the same as the server’s block size.

channels

The number of channels of audio being made available to client code.

buffer

The data, stored in interleaved format. The length of this buffer is frames*channels.

userdata

The userdata parameter as passed to the setter for this callback.

class libaudioverse.HardLimiterNode(server, channels)

The input to this node is hard limited: values less than -1.0 are set to -1.0 and values above 1.0 are set to 1.0. Use the hard limiter in order to prevent oddities with audio hardware; it should usually be the last piece in your pipeline before the server. Note that the 3D API handles hard limiting appropriately, and you do not need to worry about this there.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to limit

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The limited signal: no sample shall have an absolute value greater than 1.0.

exception libaudioverse.HrtfInvalidError

An attempt to use an invalid HRTF database.

class libaudioverse.HrtfNode(server, hrtf_path)

This node implements an HRTF panner. You can use either Libaudioverse’s internal HRTF (The Diffuse MIT Kemar Dataset) by passing “default” as the HRTf file name, or an HRTF of your own.

Inputs:

index	channels	description
0	1	The signal to pan.

Outputs:

index	channels	description
0	2	The signal with the HRTF applied.

azimuth

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The horizontal angle of the panner in degrees. 0 is straight ahead and positive values are clockwise.

elevation

Type: float

Range: [-90.0, 90.0]

Default value: 0.0

The vertical angle of the panner in degrees. 0 is horizontal and positive values move upward.

should_crossfade

Type: boolean

Default value: True By default, panners crossfade their output. This property allows such functionality to be disabled. Note that for HRTF nodes, crossfading is more important than for other panner types. Unlike other panner types, the audio artifacts produced by disabling crossfading are noticeable, even for updates of only a few degrees.

class libaudioverse.IirNode(server, channels)

Implements arbetrary IIR filters. The only restriction on the filter is that the first element of the denominator must be nonzero. To configure this node, use the function Lav_iirNodeSetCoefficients.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to filter.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal with the IIR filter applied.

set_coefficients(node, numerator_length, numerator, denominator_length, denominator, should_clear_history)

Configure the coefficients of the IIR filter.

libaudioverse.InitializationManager()

Use this with a with block to manage Libaudioverse initialization and shutdown.

The advantage of this function is that Libaudioverse will shutdown properly in all cases that involve Python exceptions. While segfaulting the interpreter will not cause a shutdown, exceptions unrelated to Libaudioverse will. Since failure to call shutdown can cause crashes, this is the preferred method of initialization in production applications; it will prevent many types of crashes in your app from turning into Libaudioverse crashes.

class libaudioverse.IntArrayProperty(handle, slot, lock)

Represents an int array property.

class libaudioverse.IntProperty(handle, slot)

Proxy to an integer property.

exception libaudioverse.InternalError

If you see this error, it’s a bug.

exception libaudioverse.InvalidHandleError

A value passed in as a handle is not currently a handle which is valid.

exception libaudioverse.InvalidPointerError

Attempt to free a pointer that Libaudioverse doesn’t know about.

exception libaudioverse.InvalidPropertyError

An attempt to access a property which does not exist on the specified node.

class libaudioverse.LeakyIntegratorNode(server, channels)

A leaky integrator. Leaky integrators integrate their input signals, while leaking over time. Introducing the leak allows for avoiding DC offset problems. If you feed this node a signal that is zero, it will slowly decrease the output in accordance with the Lav_LEAKY_INTEGRATOR_LEAKYNESS property.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	A signal to integrate.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The integral of the signal.

leakyness

Type: double

Range: [0.0, 1.0]

Default value: 1.0

The leakyness (or time constant) of the integrator.

If you feed the leaky integrator a constant signal of 0, then this property’s value is the percent decrease as observed after 1 second.

class libaudioverse.LibaudioverseProperty(handle, slot, getter, setter, converter=<function LibaudioverseProperty.<lambda>>)

Proxy to Libaudioverse properties.

All properties support resetting and type query.

type

The property’s type.

class libaudioverse.LoggingLevels

Possible levels for logging.

critical = 10

Logs critical messages such as failures to initialize and error conditions.

debug = 30

Logs everything possible.

info = 20

Logs informative messages.

off = 40

No log messages will be generated.

exception libaudioverse.MemoryError

Libaudioverse triedd to allocate a pointer, but could not.

class libaudioverse.MultipannerNode(server, hrtf_path)

A panner which can have the algorithm it uses changed at runtime. The use for multipanners is for applications in which we may wish to change the speaker configuration at runtime. Capabilities include switching from HRTF to stereo and back, a useful property for games wherein the user might or might not be using headphones.

Inputs:

index	channels	description
0	1	The signal to pan.

Outputs:

index	channels	description
0	Depends on the currently set panning strategy.	The signal, panned according to the configured panning strategy.

azimuth

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The horizontal angle of the panner, in degrees. 0 is straight ahead and positive values are clockwise.

elevation

Type: float

Range: [-90.0, 90.0]

Default value: 0.0

The vertical angle of the panner, in degrees. 0 is horizontal and positive values are upward.

should_crossfade

Type: boolean

Default value: True Whether or not this panner should crossfade. Lack of crossfading introduces audible artifacts when the panner is moved. You usually want this on.

strategy

Type: int

Range: PanningStrategies

Default value: PanningStrategies.stereo

What type of panning to use. Possibilities include HRTF, stereo, 5.1, and 7.1 speaker configurations. For something more nontraditional, use an amplitude panner.

exception libaudioverse.NoSuchDeviceError

Attempt to use an I/O device that doesn’t exist. In addition to being caused by your code, this can happen if the user unplugs the device.

class libaudioverse.NodeStates

used to indicate the state of a node. This is the value of the node’s state property and determins how the node is processed.

always_playing = 2

This node advances always.

paused = 0

This node is paused.

playing = 1

This node advances if other nodes need audio from it.

class libaudioverse.NoiseNode(server)

Generates any of a variety of types of noise.

This node has no inputs.

Outputs:

index	channels	description
0	1	The noise generated by this node.

noise_type

Type: int

Range: NoiseTypes

Default value: NoiseTypes.white

The type of noise to generate.

should_normalize

Type: boolean

Default value: False Whether or not to normalize the output. Some types of noise are quieter without this enabled. Turning it on is sometimes helpful and sometimes not.

class libaudioverse.NoiseTypes

Specifies types of noise.

brown = 2

Brown noise. Brown noise decreases at 6 DB per octave.

pink = 1

Pink noise. Pink noise falls off at 3 DB per octave.

white = 0

gaussian white noise.

exception libaudioverse.NotInitializedError

Failure to call Lav_initialized.

exception libaudioverse.NullPointerError

You passed a null pointer into Libaudioverse in a context where null pointers are not allowed.

class libaudioverse.ObjectTypes

An enumeration.

class libaudioverse.OnePoleFilterNode(server, channels)

A one-pole filter section, implementing the transfer function \(H(Z) = rac{1}{1+A_0 Z^{-1} }\)

This filter is capable of implementing either a lowpass or highpass filter and is extremmely cheep. The produced filter rolls off at about 6 DB per octave.

The default filter configuration is a lowpass at 500 HZ. The type of the filter is controlled via the is_highpass property. If said property is true, the filter becomes a highpass.

Note that this filter can be swept with a-rate accuracy.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to filter.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The filtered signal.

frequency

Type: float

Range: dynamic

Default value: 500.0

The -3 DB frequency of the filter.

The range of this property is from 0 to half the sampling rate.

is_highpass

Type: boolean

Default value: False True if the filter is a highpass.

If this property is false, the filter is a lowpass.

exception libaudioverse.OverlappingAutomatorsError

An attempt to schedule an automator within the duration of another.

class libaudioverse.PanningStrategies

Indicates a strategy to use for panning. This is mostly for the MultipannerNode and the 3D components of this library.

hrtf = 0

Indicates HRTF panning.

stereo = 1

Indicates stereo panning.

surround40 = 2

Indicates 4.0 surround sound (quadraphonic) panning.

surround51 = 3

Indicates 5.1 surround sound panning.

surround71 = 4

Indicates 7.1 surround sound panning.

exception libaudioverse.PropertyIsReadOnlyError

Attempt to set a read-only property.

class libaudioverse.PropertyTypes

Indicates the type of a property.

buffer = 8

Property holds a handle to a buffer.

double = 2

Property holds a 64-bit double.

float = 1

Property holds a 32-bit floating point value.

float3 = 4

Property holds a float3, a vector of 3 floats.

float6 = 5

Property holds a float6, a vector of 6 floats.

float_array = 6

Property is an array of floats.

int = 0

Property holds a 32-bit integer.

int_array = 7

Property is an array of ints.

string = 3

Property holds a string.

class libaudioverse.PullNode(server, sr, channels)

This node calls the audio callback whenever it needs more audio. The purpose of this node is to inject audio from an external source that Libaudioverse does not support, for example a custom network protocol.

This node has no inputs.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The result of the configured callback.

get_audio_callback()

Get the audio callback.

This is a feature of the Python bindings and is not available in the C API. See the setter for specific documentation on this callback.

set_audio_callback(callback, additional_args=None, additional_kwargs=None)

Set the audio callback.

Additional_args and additional_kwargs are passed to the callback in addition to any arguments from Libaudioverse. Note that Libaudioverse always uses positional arguments.

C callback signature: void (LavHandle nodeHandle, int frames, int channels, float * buffer, void * userdata)

Called when the node needs more audio.

Callback parameters:

nodeHandle

The node which called this callback.

frames

The number of frames of audio needed. This is not guaranteed to be the same on every call.

channels

The number of channels as set when the pull node is created.

buffer

The destination to which audio should be written. This is a buffer that is frames*channels long. Write interleaved audio data to it and do not assume that it is zeroed.

userdata

The userdata parameter as passed to the setter for this callback.

class libaudioverse.PushNode(server, sr, channels)

The purpose of this node is the same as the pull node, but it is used in situations wherein we do not know when we are going to get audio. Audio is queued as it is pushed to this node and then played as fast as possible. This node can be used to avoid writing a queue of audio yourself, as it essentially implements said functionality. If you need low latency audio or the ability to run something like the Opus encoder’s ability to cover for missing frames, you need a pull node.

This node has no inputs.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	Either audio from the internal queue or zero.

feed(node, length, frames)

Feed more audio data into the internal queue.

get_low_callback()

Get the low callback.

This is a feature of the Python bindings and is not available in the C API. See the setter for specific documentation on this callback.

get_underrun_callback()

Get the underrun callback.

This is a feature of the Python bindings and is not available in the C API. See the setter for specific documentation on this callback.

set_low_callback(callback, additional_args=None, additional_kwargs=None)

Set the low callback.

Additional_args and additional_kwargs are passed to the callback in addition to any arguments from Libaudioverse. Note that Libaudioverse always uses positional arguments.

C callback signature: void (LavHandle nodeHandle, void * userdata)

Called once per block and outside the audio thread when there is less than the specified threshold audio remaining.

Callback parameters:

nodeHandle

The node which called this callback.

userdata

The userdata parameter as passed to the setter for this callback.

set_underrun_callback(callback, additional_args=None, additional_kwargs=None)

Set the underrun callback.

Additional_args and additional_kwargs are passed to the callback in addition to any arguments from Libaudioverse. Note that Libaudioverse always uses positional arguments.

C callback signature: void (LavHandle nodeHandle, void * userdata)

Called exactly once and outside the audio thread when the node runs out of audio completely.

Callback parameters:

nodeHandle

The node which called this callback.

userdata

The userdata parameter as passed to the setter for this callback.

threshold

Type: float

Range: [0.0, INFINITY]

Default value: 0.03

When the remaining audio in the push node has a duration less than this property, the low callback is called.

exception libaudioverse.RangeError

A function parameter is not within a valid range. This could be setting property values outside their range, accessing inputs and outputs that do not exist, or any of a variety of other range error conditions.

class libaudioverse.RecorderNode(server, channels)

Records audio to files.

The usage pattern for this node is simple: connect something to the input, call Lav_recorderNodeStartRecording, and ensure that the node is processed. In order to avoid potential problems with blocks of silence at the beginning of the recording, this node’s default state is playing. You should connect the output to something that will demand the recorder node’s audio or change the state to always playing, usually after a call to Lav_recorderNodeStartRecording. If you don’t, no recording will take place.

Unlike most other nodes in Libaudioverse, it is important that you call Lav_recorderNodeStopRecording when done recording. Failure to do so may lead to any of a number of surprising results.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to record.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The same as the input signal.

start_recording(node, path)

Begin recording to the specified files. The sample rate is the same as that of the server. The channel count is the same as this node was initialized with. The format of the file is determined from the extension: this function recognizes “.wav” and “.ogg” on all platforms.

stop_recording(node)

Stops recording.

Be sure to call this function. Failure to do so may lead to any of a number of undesirable problems.

class libaudioverse.RingmodNode(server)

This node has two inputs and one output. The two inputs will be converted to mono and then multiplied, before being sent to the output.

Inputs:

index	channels	description
0	1	The first signal.
1	1	The second signal.

Outputs:

index	channels	description
0	1	The result of multiplying the two input signals together.

class libaudioverse.Server(sample_rate=44100, block_size=1024)

Represents a server. All libaudioverse nodes must be passed a server at creation time as the first argument to their constructor and cannot migrate between them. Furthermore, it is an error to try to connect objects from different servers.

Instances of this class are context managers. Using the with statement on an instance of this class invoke’s Libaudioverse’s atomic block support.

For full details of this class, see the Libaudioverse manual.

call_in(when, callback, extra_args=None, extra_kwargs=None, in_audio_thread=False)

Schedule a fucntion to run in the future.

If in_audio_thread is false, it is safe to call the Libaudioverse API.

Wraps Lav_serverCallIn.

clear_output_device()

Clears the output device, stopping audio and allowing use of get_block again.

get_block(channels, may_apply_mixing_matrix=True)

Returns a block of data.

This function wraps Lav_getBlock. Note that calling this on a server configured to output audio is an error.

If may_apply_mixing_matrix is True, audio will be automatically converted to the output channel type. If it is false, channels are either dropped or padded with zeros.

get_block_callback()

The Python bindings provide the ability to retrieve callback objects. This function retrieves the set block callback, if any.

set_block_callback(callback, additional_args=None, additional_kwargs=None)

Set a callback to be called every block.

This callback is called as though inside a with block, and takes two positional argguments: the server and the servers’ time.

Wraps lav_serverSetBlockCallback.

set_output_device(identifier=’default’, channels=2, mixahead=2)

Sets the output device. Use -1 for default system audio. 0 and greater are specific audio devices. To enumerate devices, use enumerate_devices.

threads

The number of threads the server is using for processing.

This wraps Lav_serverGetThreads and Lav_serverSetThreads.

write_file(path, channels, duration, may_apply_mixing_matrix=True)

Write blocks of data to a file.

This function wraps Lav_serverWriteFile.

class libaudioverse.SineNode(server)

A simple sine oscillator.

This node has no inputs.

Outputs:

index	channels	description
0	1	A sine wave.

frequency

Type: float

Range: [0, INFINITY]

Default value: 440.0

The frequency of the sine wave in HZ.

frequency_multiplier

Type: float

Range: [-INFINITY, INFINITY]

Default value: 1.0

An additional multiplicative factor applied to the frequency of the oscillator.

This is useful for creating instruments, as the notes of the standard musical scale fall on frequency multiples of a reference pitch, rather than a linear increase.

phase

Type: float

Range: [0.0, 1.0]

Default value: 0.0

The phase of the sine node. This is measured in periods, not in radians.

class libaudioverse.SourceNode(server, environment)

The source node allows the spatialization of sound that passes through it. Sources have one input which is mono, to which a node should be connected. The audio from the input is spatialized according both to the source’s properties and those on its environment, and passed directly to the environment. Sources have no outputs. To hear a source, you must connect its environment to something instead.

Since the source communicates with the environment through a nonstandard mechanism, environments do not keep their sources alive. If you are in a garbage collected language, failure to hold on to the source nodes will cause them to go silent.

Inputs:

index	channels	description
0	1	The audio to enter the 3D environment.

This node has no outputs. If you want it to advance, be sure to use foo.state = nodeStates.always_playing.

control_distance_model

Type: boolean

Default value: False In order to make working with sources easier for simple applications, some properties of source objects are ignored in favor of values on the environment. This property is used to disable this behavior for properties related to the distance model.

control_panning

Type: boolean

Default value: False In order to make working with sources easier for simple applications, some properties of source objects are ignored in favor of values on the environment. This property is used to disable this behavior for properties related to panning.

control_reverb

Type: boolean

Default value: False In order to make working with sources easier for simple applications, some properties of source objects are ignored in favor of values on the environment. This property is used to disable this behavior for properties related to reverb.

distance_model

Type: int

Range: DistanceModels

Default value: DistanceModels.linear

The distance model determines how quickly sources get quieter as they move away from the listener. The default value of this property is set from the corresponding property on the environment at source creation. By default, sources ignore this property in favor of the value provided by their environment. Set Lav_SOURCE_CONTROL_DISTANCE_MODEL to true to control it yourself.

feed_effect(node, effect)

Begin feeding the specified effect send.

head_relative

Type: boolean

Default value: False Whether or not to consider this source’s position to always be relative to the listener.

Sources which are head relative interpret their positions in the default coordinate system, relative to the listener. Positive x is right, positive y is up, and positive z is behind the listener. The orientation and position properties of an environment do not affect head relative sources, making them ideal for such things as footsteps and/or HUD effects that should be panned.

max_distance

Type: float

Range: [0.0, INFINITY]

Default value: 150.0

The maximum distance from the listener at which the source will be audible. The default value of this property is set from the corresponding property on the environment at source creation. By default, sources do not respect this property and use the corresponding value from their environment. Set Lav_SOURCE_CONTROL_DISTANCE_MODEL to true to control it yourself.

max_reverb_level

Type: float

Range: [0.0, 1.0]

Default value: 0.6

The maximum amount of audio to be diverted to reverb sends, if any.

Behavior is undefined if this property is ever less than Lav_SOURCE_MIN_REVERB_LEVEL.

The default value of this property is set from the corresponding property on the environment at source creation. By default, this property is ignored in favor of the value provided by this source’s environment. Set Lav_SOURCE_CONTROL_REVERB to true to control it yourself.

min_reverb_level

Type: float

Range: [0.0, 1.0]

Default value: 0.15

The minimum reverb level allowed.

if a send is configured to be a reverb send, this is the minimum amount of audio that will be diverted to it.

Behavior is undefined if this property is ever greater than the value you give to Lav_SOURCE_MAX_REVERB_LEVEL.

The default value of this property is set from the corresponding property on the environment at source creation. By default, this property is ignored in favor of the value provided by this source’s environment. Set Lav_SOURCE_CONTROL_REVERB to true to control it yourself.

occlusion

Type: float

Range: [0.0, 1.0]

Default value: 0.0

A scalar representing how occluded this source is.

This property controls internal filters of the source that make occluded objects sound muffled. A value of 1.0 is a fully occluded source, which will be all but silent; a value of 0.0 has no effect.

It is extremely difficult to map occlusion to a physical quantity. As a consequence, this property is unitless.

orientation

Type: float6

Default value: [0.0, 0.0, -1.0, 0.0, 1.0, 0.0]

The orientation of the source. This is not currently used. In future, it will be used for sound cones and filters on sources facing away. The interpretation is the same as that for the listener: the first 3 values are the direction of the front and the second 3 the direction of the top. Note that these must both be unit vectors and that they must be orthoganal. They are packed because, also like the listener, they must never be modified separately.

panning_strategy

Type: int

Range: PanningStrategies

Default value: PanningStrategies.stereo

The strategy for the internal multipanner. The default value of this property is set from the corresponding property on the environment at source creation. By default, this property is ignored and sources use the value provided by their environment. Set Lav_SOURCE_CONTROL_PANNING to true to control it yourself.

position

Type: float3

Default value: [0.0, 0.0, 0.0]

The position of the source in world coordinates.

reverb_distance

Type: float

Range: [0.0, INFINITY]

Default value: 75.0

The distance at which the source will only be heard through the reverb effect sends.

If this source is not feeding any effect sends configured as reverbs, this property has no effect.

For values greater than Lav_SOURCE_MAX_DISTANCE, the source will always be heard at least somewhat in the dry path. Lav_SOURCE_DISTANCE_MODEL controls how this crossfading takes place.

The default value of this property is set from the corresponding property on the environment at source creation. By default, sources ignore this property in favor of the value provided by their environment. Set Lav_SOURCE_CONTROL_REVERB to true to control it yourself.

set_properties_from_environment(node)

A convenience function for working with properties on sources. When called, this function sets the values of all properties which have corresponding properties on the environment to the values from the environment.

size

Type: float

Range: [0.0, INFINITY]

Default value: 0.0

The size of the source. Sources are approximated as spheres. The size is used to determine the closest point on the source to the listener, and is the radius of this sphere. Size currently has no other effect.

The default value of this property is set from the corresponding property on the environment at source creation.

stop_feeding_effect(node, effect)

Stop feeding an effect send.

class libaudioverse.StringProperty(handle, slot)

Proxy to a string property.

class libaudioverse.ThreeBandEqNode(server, channels)

A three band equalizer.

This node consists of a peaking filter and a highshelf filter in series, such that the frequency spectrum may be equalized in three, configurable bands.

The lowest of these bands begins at lowband_frequency and continues down to 0 hz. The highest is from highband_frequency and continues until nyquist. The middle is the remaining space between the low and high band. If the high band begins below the low band, behavior is undefined, but will almost certainly not do what you want. Libaudioverse does not check for this case.

The slopes that this node institutes are not perfect and cannot increase effectively beyond a certain point. This is the least expensive of the Libaudioverse equalizers, and is sufficient for many simpler applications.

Inputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The signal to equalize.

Outputs:

index	channels	description
0	Depends on arguments to this node’s constructor.	The equalized signal.

highband_dbgain

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The gain to apply to the highest frequency band as decibals.

highband_frequency

Type: float

Range: dynamic

Default value: 1000.0

The frequency that divides the middle band from the high band.

lowband_dbgain

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The gain of the lowest frequency band as decibals.

lowband_frequency

Type: float

Range: dynamic

Default value: 300.0

The frequency that divides the low and middle bands.

This ranges from 0 to nyquist.

midband_dbgain

Type: float

Range: [-INFINITY, INFINITY]

Default value: 0.0

The gain to apply to the middle band of the equalizer.

exception libaudioverse.TypeMismatchError

Indicates an attempt to manipulate a property through a function that does not work with that property’s type.

exception libaudioverse.UnknownError

Something went wrong. This error indicates that we couldn’t figure out what.

class libaudioverse.VectorProperty(handle, slot, getter, setter, length)

class to act as a base for float3 and float6 properties.

This class knows how to marshal anything that is a collections.sized and will error if length constraints are not met.

libaudioverse.enumerate_devices()

Returns a list of DeviceInfo representing the devices on the system.

libaudioverse.initialize()

Corresponds to Lav_initialize, plus binding specific setup.

Call this before using anything from Libaudioverse.

libaudioverse.shutdown()

Corresponds to Lav_shutdown.

Call this at the end of your application. You must call it before the interpreter shuts down. Failure to do so will allow Libaudioverse to call your code during Python’s shutdown procedures.