VarnetEnvelope

Defined in: voxatlas.features.acoustic.envelope.varnet

class voxatlas.features.acoustic.envelope.varnet.VarnetEnvelope

Bases: BaseExtractor

Extract the acoustic.envelope.varnet feature within the VoxAtlas pipeline.

Computes a smoothed, frame-aligned RMS amplitude envelope using a longer analysis window (by default, 50 ms). This slower-timescale contour is useful for characterizing modulation patterns in the amplitude envelope as described by Varnet and colleagues.

Algorithm

The implementation mirrors the code path.

1. RMS amplitude The waveform is framed (typically with a longer window than acoustic.envelope.rms) and converted to RMS values \(r_t\).

2. Smoothing The RMS contour is smoothed with a moving-average window of length smoothing frames.

name

Registry key for this extractor ("acoustic.envelope.varnet").

Type:

str

input_units

Required input unit level. None means this extractor operates directly on waveform audio.

Type:

str | None

output_units

Output alignment unit ("frame").

Type:

str | None

dependencies

Upstream features required before execution. Empty for this extractor.

Type:

list[str]

default_config

Default runtime parameters: frame_length=0.05, frame_step=0.01, peak_threshold=0.1, smoothing=9.

Type:

dict

References

Varnet, L., Ortiz-Barajas, M.-C., Erra, R. G., Gervain, J., & Lorenzi, C. (2017). A cross-linguistic study of speech modulation spectra. *The Journal of the Acoustical Society of America, 142*(4), 1976–1989. https://doi.org/10.1121/1.5006179

Examples

>>> import numpy as np
>>> from voxatlas.audio.audio import Audio
>>> from voxatlas.features.acoustic.envelope.varnet import VarnetEnvelope
>>> from voxatlas.features.feature_input import FeatureInput
>>> audio = Audio(waveform=np.zeros(1600, dtype=np.float32), sample_rate=16000)
>>> feature_input = FeatureInput(audio=audio, units=None, context={})
>>> params = VarnetEnvelope.default_config.copy()
>>> out = VarnetEnvelope().compute(feature_input, params)
>>> out.unit
'frame'

name: str = 'acoustic.envelope.varnet'

input_units: str | None = None

output_units: str | None = 'frame'

dependencies: list[str] = []

default_config: dict = {'frame_length': 0.05, 'frame_step': 0.01, 'peak_threshold': 0.1, 'smoothing': 9}

compute(feature_input, params)

Compute the extractor output for a single pipeline invocation.

This method is the reusable execution entry point for the extractor. It receives the standard FeatureInput bundle, applies the configured algorithm, and returns feature values aligned to the extractor output units for storage in the pipeline feature store.

Parameters:

• feature_input (object) – Structured extractor input bundling audio, hierarchical units, and execution context for this feature computation.

• params (object) – Resolved feature configuration for this invocation. Keys are feature-specific and merged from defaults and pipeline settings.

Returns:

Structured output aligned to the frame unit level when applicable.

Return type:

FeatureOutput

Examples

>>> import numpy as np
>>> from voxatlas.audio.audio import Audio
>>> from voxatlas.features.acoustic.envelope.varnet import VarnetEnvelope
>>> from voxatlas.features.feature_input import FeatureInput
>>> audio = Audio(waveform=np.zeros(1600, dtype=np.float32), sample_rate=16000)
>>> feature_input = FeatureInput(audio=audio, units=None, context={})
>>> params = VarnetEnvelope.default_config.copy()
>>> result = VarnetEnvelope().compute(feature_input, params)
>>> result.values.shape[0] > 0
True