HilbertEnvelope

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

class voxatlas.features.acoustic.envelope.hilbert.HilbertEnvelope

Bases: BaseExtractor

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

Computes a Hilbert-based amplitude envelope from the raw audio waveform. It does not require linguistic units as input and returns a frame-aligned time series.

Algorithm

The extractor computes the analytic-signal envelope using the Hilbert transform.

1. Analytic signal Given waveform \(x[n]\), the code forms

   \[z[n] = x[n] + j\,\mathcal{H}\{x[n]\},\]

   where \(\mathcal{H}\) denotes the Hilbert transform.

2. Magnitude envelope The returned contour is the magnitude \(a[n] = |z[n]|\) and is then aligned to frame times as required by the output container.

name

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

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.025, frame_step=0.01, peak_threshold=0.1, smoothing=1.

Type:

dict

References

Cohen, L. (1995). Time-Frequency Analysis. Prentice Hall.

Examples

>>> import numpy as np
>>> from voxatlas.audio.audio import Audio
>>> from voxatlas.features.acoustic.envelope.hilbert import HilbertEnvelope
>>> 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 = HilbertEnvelope.default_config.copy()
>>> out = HilbertEnvelope().compute(feature_input, params)
>>> out.unit
'frame'

name: str = 'acoustic.envelope.hilbert'

input_units: str | None = None

output_units: str | None = 'frame'

dependencies: list[str] = []

default_config: dict = {'frame_length': 0.025, 'frame_step': 0.01, 'peak_threshold': 0.1, 'smoothing': 1}

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.hilbert import HilbertEnvelope
>>> 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 = HilbertEnvelope.default_config.copy()
>>> result = HilbertEnvelope().compute(feature_input, params)
>>> result.values.shape[0] > 0
True